docs: core smoke checklist + Atlas-handoff design finding

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 <noreply@anthropic.com>

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 `<span>` 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: <key>" -H "API-Pin: <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-<world>-<ts>/` 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.

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 <path>. 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.