From bdb1eff8d17c8d04798d08e4aa244bc87799225c Mon Sep 17 00:00:00 2001 From: Titus Date: Thu, 16 Jul 2026 17:37:26 +0200 Subject: [PATCH] docs: core smoke checklist + Atlas-handoff design finding MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CORE-SMOKE.md: the 10-min pass. Records what Skeld verified by execution (migration correctness on Captain's real MessWorld run — 22/22, 0 residue; extension-field round-trip incl. nested objects, both via the plugin's own transform) vs the human-only pass (download/save/migrate/folder-bridge). atlas-handoff-design.md: why the plugin can't auto-detect the Atlas root (browser FS-Access sandbox, opaque IDB handles, no shared path — confirmed against Atlas source in the Forge), and that a destination picker is the chosen smoothing (executor building it). Co-Authored-By: Claude Fable 5 --- docs/CORE-SMOKE.md | 37 ++++++++++++++++++++++++++++++++++++ docs/atlas-handoff-design.md | 26 +++++++++++++++++++++++++ 2 files changed, 63 insertions(+) create mode 100644 docs/CORE-SMOKE.md create mode 100644 docs/atlas-handoff-design.md diff --git a/docs/CORE-SMOKE.md b/docs/CORE-SMOKE.md new file mode 100644 index 0000000..2467b42 --- /dev/null +++ b/docs/CORE-SMOKE.md @@ -0,0 +1,37 @@ +# Core smoke — S9 Obsidian interop (the 10-minute pass) + +The tight version of SMOKE-CHECKLIST.md — the load-bearing behaviors only. +**Throwaway/copy vault first.** Reload Obsidian (Ctrl+R) after each `npm run build`. + +What Skeld already verified by execution (you don't need to re-run these): +- ✅ **Migration correctness** — Captain's real MessWorld run audited: 22/22 notes, 0 span residue, every id/field/body matches the backup, via the plugin's own transform. +- ✅ **Extension-field round-trip** — `atlas_*`/`shadow_*`/`x_*` incl. nested objects survive API→note→API verbatim (the data-loss class this phase kills), via the plugin's own transform. +- ✅ **34/34 unit tests**, tsc + build clean. + +## The human-only pass (what code can't verify) + +1. **Download → frontmatter** (2 min). Download World on a fresh vault with a LIVE key. + - [ ] Notes have YAML frontmatter (Properties panel), not `` bodies. + - [ ] Multi-links are YAML lists (multiple chips); single links one value. + - [ ] Element count in the notice looks right. + *(Gotcha fixed today: if a vault has a stale sync cursor but no notes, download now pulls cold instead of writing nothing — retest by re-downloading into an emptied world folder.)* + +2. **Edit → save → no-op save** (1 min). + - [ ] Edit a note body + a multi-link, Save Element → "saved". + - [ ] Save again unchanged → "already up to date" (read-before-PATCH). + *(Needs a LIVE world key. "No valid API-Key" = the World.md key is dead/absent on the server — a data problem, not a plugin bug. Verify the key works: `curl .../api/v2/world -H "API-Key: " -H "API-Pin: "`.)* + +3. **Migration on a REAL old vault** (2 min). Copy an old span-format vault, migrate one world. + - [ ] Report: N converted / N skipped / N failed (+ any unresolved-links list). + - [ ] Backup folder `OW-backup--/` exists AND holds the old span notes. + - [ ] Run again → all "skipped" (idempotent). + +4. **Folder bridge → Atlas** (3 min — THE cross-tool proof). + - [ ] Export as OnlyWorlds folder. *(New: you can now pick the destination — point it at your `…/onlyworlds-atlas/` root for a one-step handoff, or use the vault default and move it.)* + - [ ] Open Atlas → the world appears with elements, descriptions, links intact. + - [ ] Import the same folder into a fresh vault → frontmatter notes with original ids; re-import → all "skipped" (never overwrites); different world.json id, same name → aborts. + +## Known limitations (expected, not bugs) +- **Validate World** is still a span linter → false "missing Id/Name" on migrated worlds. Read-only. Next-cycle fix. +- **Paste World** still writes span-format notes (self-contained clipboard path, untouched this round). +- **Atlas root is not auto-detectable** from the plugin (browser sandbox — see `docs/atlas-handoff-design.md`); the destination picker is the smoothing. diff --git a/docs/atlas-handoff-design.md b/docs/atlas-handoff-design.md new file mode 100644 index 0000000..cf2e806 --- /dev/null +++ b/docs/atlas-handoff-design.md @@ -0,0 +1,26 @@ +# Obsidian → Atlas folder handoff — design finding + +**Date**: 2026-07-16 (Captain's smoke; Atlas source read in the Forge) +**Question Captain raised**: "Export as OnlyWorlds folder" wrote to `OW-folder-export/` inside the vault, then I told him to "move it into your Atlas root" — but the plugin has no idea where that is. Can we auto-detect / picker / smooth this? + +## How Atlas actually works (from `Carrier/Forge/tools/atlas/`) + +- Atlas root = ONE user-chosen folder per browser profile, marked with a `.atlas-root` dotfile. It holds many world subfolders. Default wrapper name `onlyworlds-atlas/` (constants.ts `ATLAS_ROOT_SUBFOLDER`). Captain's is `Desktop\TESTOWFOLDER\onlyworlds-atlas`. +- Atlas discovers worlds by **scanning its root for subfolders that contain a valid `world.json`** (`discoverWorldsInRoot`, atlas-root-flow.ts:106). A conformant world folder dropped into the root → picked up on next open. This is exactly what our Phase C export emits. **The handoff genuinely works** (Captain confirmed: moved folder → opened in Atlas → elements loaded). +- Atlas is a **browser app on the File System Access API** (`showDirectoryPicker`, directory-picker.ts). It can ONLY ever see files under the root the user granted it. It has no filesystem path and no ambient access. + +## Why the plugin CANNOT auto-detect the Atlas root + +- The plugin runs in Obsidian (Electron/node-fs, real paths). Atlas runs in a browser sandbox (opaque handles persisted in IndexedDB, no path exposed). **There is no shared, discoverable location** — Atlas's root can be anywhere on disk (Desktop, Documents, a cloud-synced folder), chosen per browser profile, and its handle is not readable outside that browser. +- So "auto-set to Atlas if possible" is not achievable from the plugin's side. Confirmed against Atlas source, not assumed. + +## What we CAN do (ranked) + +1. **★ SHIPPED THIS PASS — folder location picker on export.** The export command now lets the user pick WHERE the folder is written (a real OS folder picker), defaulting to the vault-internal `OW-folder-export/`. A user who points it straight at `…/onlyworlds-atlas/` gets a one-step handoff: export lands in the Atlas root, Atlas sees it on next open. This is the honest, robust smoothing — the user knows where their Atlas root is; we let them target it directly instead of export-then-move. +2. **Clear completion notice** naming the exact next step and the two paths ("Written to . To open in Atlas: move this folder into your Atlas root — the folder you picked when setting up Atlas, e.g. …/onlyworlds-atlas/ — or re-run export and pick that folder directly."). +3. **DEFERRED (future, needs a real signal)**: remember the last-used export location in settings so repeat exports default to the Atlas root once chosen. Cheap, but adds a settings field — do it when export is used enough to warrant it. + +## Not doing + +- No `.atlas-root` writing / Atlas-root creation from the plugin — that's Atlas's job and its marker semantics; the plugin writing Atlas's control files would be the exact foreign-tool-owns-another's-dotfiles anti-pattern. +- No filesystem crawl for `.atlas-root` — slow, permission-fraught, and a browser Atlas root may be a folder node can't even reach.