@n8r/surface 0.0.0-stage → 0.1.0-experimental.2

package/docs/n8r-surface/save-reopen-verification.md

@@ -0,0 +1,152 @@
+# Saved continuation: evidence and limits
+
+Related to [#17](https://github.com/injectionator/n8r-surface/issues/17).
+Use [the short human check](getting-started.md). This increment implements
+SAVE-01 in numbered Markdown; it does not complete structured HTML/JSON/YAML,
+broader host/live trials, Lab integration or registry distribution.
+
+## Current verification
+
+**Pass (agent rehearsal), 5 November 2026. Human acceptance remains pending.**
+The prior conversation increment was user-reported Pass and PR #33 merged at
+`b186050`; the new saved-continuation evidence is recorded separately here.
+
+- Implementation: [`447f440`](https://github.com/injectionator/n8r-surface/commit/447f44058c142d3a49ed827298d922a6458fbcb1).
+  Rehearsal completed while repository HEAD was `b4407aa`, which changes only the
+  offline test driver's prompt matching and plan notes, not product code.
+- Installed tarball SHA-256:
+  `926823a95209ace0183875b2aaa2a3423f46671ad423f38e2b1fcdf885ef9b2d`.
+- Environment: macOS arm64, Node 26.13.0, Codex CLI 0.166.0, existing ChatGPT
+  sign-in, explicit `gpt-6-astra`. A private run under the selected vault held the
+  isolated install, n8r HOME/settings and copied synthetic source. Existing Codex
+  sign-in was reused through CODEX_HOME without copying credentials.
+- Loaded Researcher 0.1.8, combined instruction SHA-256
+  `8af29c3073df9b8210a7dd94ced9700379b0a98f76bd3a2902f9430b93c98a2a`.
+- [Actual sanitized terminal transcripts](save-reopen-transcript.md) retain model
+  messages and source-read activity. Findings and note prose were produced by
+  real Codex, not prewritten by the developing agent.
+
+### Exercised interaction and independent readback
+
+Starting state: copied `lumen-guide.md`, complete configured test vault, no saved
+notes and unchanged version-1 settings. The installed command performed the short
+human walkthrough's source investigation and OIDC decision, `/save`, `/exit`,
+explicit-note reopen with renewed transmission consent, authentication follow-up,
+`/save`, `/exit`. Both processes exited **0**. The original first note remained
+byte-identical after its successor was saved.
+
+A third process tested the user's additional request: append a human edit to the
+older first note, prioritizing session-expiry evidence while retaining the OIDC
+non-selection, then run `reopen --source SOURCE --model gpt-6-astra` without NOTE.
+It suggested the edited `research-001.md`, showed its edit time, and waited for
+selection and transmission consent. The conversation retained that edit and saved
+`research-003.md`, linking the edited first note. It did not overwrite 002 or edit
+001 again. This process also exited **0**.
+
+Independent file reads found all five stable IDs in every note:
+`component:lumen`, `component:inference`, `component:archive`,
+`component:callback`, `component:oidc`. All retained the OIDC decision separately
+from source claims, cited the actual guide, preserved unknowns and included
+recommended next steps. The third retained the session-expiry priority. The first
+note explicitly explains that source references require the accompanying guide.
+No runtime connection or alternative authentication mechanism was invented as fact.
+
+| Readback | SHA-256 / result |
+| --- | --- |
+| Source before and after all processes | `98d3374c79c166b37f0debb4ffb5e457eda1385dd7847b042cbad674cac98693` |
+| Original 001, preserved after saving 002 and referenced by 002 | `9910959c740959e943e7d6cf4e81b1d365468ab33576fb9c83aa9ce25dc054e7` |
+| Deliberately edited 001, preserved after saving 003 and referenced by 003 | `76b6abe6d616b903f641f2b8d52f06777ad5383060701ce49a314d3ff68eca52` |
+| Saved 002 | `927a6a84a810d518b5e7bc8f37df3f29916e353a3bb6817ccf21b2cc36aee265` |
+| Saved 003 | `56f317af8dfd30ea76cbfe0318bf74b226cc3be0ef851e0edc67bcd120d029d6` |
+| n8r settings | Unchanged bytes |
+
+Raw transcripts, saved files and readback report remain under the selected vault's
+runs/ convention. No local vault path or private infrastructure data is published.
+These are agent rehearsals using supplied synthetic human input, not human acceptance.
+
+### Automated verification and review
+
+- 97 Node tests passed on each of Node 22.23.2, 24.22.2 and 26.13.0.
+- Installed-package checks passed on all three runtimes, including 20 offline
+  discovery/save/reopen terminal scenarios. They cover no premature writes,
+  failed and cancelled staged drafts, source scope, latest selection/refusal,
+  changed-source comparisons, preserved predecessors and process cleanup.
+- Storage tests cover edit-time ranking, occupied names, changed predecessors,
+  symlink/replaced-folder refusal, bounded UTF-8 and human edits after metadata.
+- Fresh review found missing historical evidence and incompatible reopen-size
+  limits. Regression tests failed first, then passed after preserving unavailable
+  evidence and using bounded comparison summaries rather than embedded source text.
+- Linux CI exposed a test-driver race: a generic `[y/N]` matcher reused the first
+  prompt's suffix. The driver now waits for the complete transmission prompt.
+  Product code was unchanged; the initial failed CI run remains visible.
+- Python fixture/workflow suite: 24 passed. Shell syntax, Markdownlint 0.24.0,
+  offline Lychee 0.24.2 with fragments, cffconvert 2.0.0 and whitespace passed.
+
+Scripted protocol tests are not AI evidence; fixture integrity is not model
+conformance. The real rehearsal used one synthetic source and unchanged source
+bytes. Broader products, live observations, second-source integration, structured
+HTML/JSON/YAML, named Lab consumers and npm distribution remain open in #17/#27.
+
+## Storage and continuation boundary
+
+`/save` authorizes one numbered Markdown output. A dynamic `research_note` call
+stages a draft in memory only during that host-authorized turn. The host writes
+only after successful turn completion; ordinary conversation and unsolicited tool
+calls cannot write. Natural-language save requests receive `/save` guidance.
+The host shows the destination, appends current source-tool evidence and identified
+Researcher/model metadata, writes a temporary file, publishes by exclusive hard
+link, independently reads it back and prints the saved path and byte digest.
+Predecessors retain their bytes; successors link their name and exact digest.
+A changed predecessor requires reopening its edited version before another save.
+
+Notes have a 256 KiB total limit, with at most 192 KiB of model prose and 1,000
+source evidence entries. They use an experimental host metadata envelope, not
+an AI Surface interchange schema. Model-authored prose and IDs are checked in the
+rehearsal, not mechanically validated for truth. Metadata and human-edited prose
+are untrusted input on reopening; hashes identify bytes, not authenticity.
+
+`reopen [NOTE] --source SOURCE` requires explicit current source selection and
+renewed note/source transmission permission. It starts a new ephemeral Codex
+thread, compares saved evidence hashes with the selected source, reports changed
+or unavailable evidence, and supplies the note plus comparisons as untrusted
+research context. Reopening compares the saved evidence paths, retaining unavailable prior evidence
+for subsequent attempts. Compact comparisons sent to the model are bounded to
+128 KiB with an explicit omitted count; full source text is read on demand through
+the normal tools. Combined context is bounded to 512 KiB. Current source reads retain their normal limits;
+no shell, broad filesystem write or extra execution environment is granted.
+
+Without NOTE, the command suggests the latest filesystem-edited numbered note in
+that source's research folder, showing UTC edit time and requiring acceptance.
+A tied time sorts by filename; an invalid newest note is reported, not skipped.
+Folder naming and edit time do not establish source identity. Explicit NOTE can
+select another folder, and successors remain there. Only this command's metadata
+notes are supported; generic Markdown import is later work.
+
+Destination ancestor identities and predecessor bytes are checked again before
+publishing. Existing names are never replaced. Directory topology must remain
+stable during synchronous filesystem operations; this is not protection against
+an adversarial concurrent directory replacement. An interrupted process can leave
+an unreferenced hidden temporary file; it does not overwrite an earlier note.
+Local storage does not provide backup, encryption or publication.
+
+## Pending-operation indicator follow-up
+
+The user reported long silent waits during `/save` and after questions. Commit
+`a6d11ad` adds a terminal-only spinner with elapsed seconds for connecting,
+answering, reopening and preparing a note. It clears around normal output and
+stops before returning to the prompt, including errors/cancellation. It reports a
+pending request, not known server-side progress; nonterminal output never animates.
+
+An isolated installed candidate was rehearsed with real Codex 0.166.0,
+`gpt-6-astra`, ChatGPT sign-in and Node 26.13.0 on macOS. The same synthetic Lumen
+question/OIDC choice was followed by `/save` and `/exit`. The spinner produced
+162 preparation frames over approximately 40 seconds, cleared before
+**Saved and read back**, and produced no activity after the final `You>` prompt.
+One note was saved, exit was 0, and source/settings bytes remained unchanged.
+Raw terminal output and independent readback remain in the selected vault's runs/.
+Tarball SHA-256: `d90df87bc3f1db05a5de01ee0080d88a599ca4050e63473e548907f53b6dfe3a`.
+
+99 Node tests and the installed-package check passed. Terminal scenarios still
+cover cancellation/failure; focused tests verify repeated activity, clearing around
+output, timer cleanup and nonterminal silence. The six GitHub checks passed on
+`a6d11ad`. The short walkthrough now names the visible labels and expected stop.

package/docs/n8r-surface/startup-human-check.md

@@ -0,0 +1,172 @@
+# Human verification: bare startup (STARTUP-01)
+
+Use a macOS or Linux terminal with Bash or zsh, Node.js **22, 24 or 26**, npm,
+Python **3.9+**, Git and an authenticated GitHub CLI (`gh`). The recorded run used
+macOS; this human procedure has not been rehearsed on Linux. No AI or Lab
+credentials are needed.
+
+Run the blocks below **in order, in the same terminal**, starting anywhere inside
+an existing `injectionator/n8r-surface` checkout. Stop if a preparation command
+fails. Installation downloads npm dependencies and creates ignored build files in
+the checkout. The installed package, synthetic home, captured output and snapshot
+all go in one temporary folder. Only the command under test receives that home.
+
+## 1. Select PR #25 and run the automated checks
+
+First run `git status --short`. **Expected: no output.** If it lists changes, keep
+those changes and use your normal process to finish that work before switching.
+Then run:
+
+```sh
+cd "$(git rev-parse --show-toplevel)"
+gh pr checkout 25
+git branch --show-current
+git rev-parse HEAD
+node --version
+npm ci && npm cache add yaml@2.9.1 && npm test && npm run check:package
+```
+
+**Expected:** branch `feat/16-bare-startup`; record the printed commit for your
+review. `node --version` must start with `v22.`, `v24.` or `v26.`. The final command
+must exit **0**. Its output must show **43 tests passed, 0 failed, 0 skipped** for
+`npm test`, then **20 tests passed, 0 failed, 0 skipped** for the installed startup
+checks, plus these messages (Node's summary formatting varies by version):
+
+```text
+Installed package passed on Node v…; 4 nodes, 6 relationships, exact research references.
+Installed PTY startup passed: overview before question, y and EOF, unchanged files.
+```
+
+Those checks drive a terminal automatically. Continue below to see and answer the
+installed command yourself.
+
+## 2. Install a disposable copy and prepare the starting state
+
+```sh
+n8r_verify=$(mktemp -d "${TMPDIR:-/tmp}/n8r-startup-review.XXXXXX")
+n8r_verify=$(cd "$n8r_verify" && pwd -P)
+npm pack --ignore-scripts --pack-destination "$n8r_verify"
+npm install --prefix "$n8r_verify/install" --offline --ignore-scripts --no-audit --no-fund "$n8r_verify/n8r-surface-0.0.0-experimental.1.tgz"
+mkdir -p "$n8r_verify/home/.n8r" "$n8r_verify/home/n8r/artifacts"
+cat > "$n8r_verify/home/.n8r/n8r-surface.json" <<'JSON'
+{
+  "version": 1,
+  "artefactRoot": "~/n8r/artifacts",
+  "surfaceFormat": "json",
+  "private": "PRIVATE_VALUE_MUST_NOT_APPEAR"
+}
+JSON
+cat > "$n8r_verify/home/n8r/artifacts/librechat-uniqueid.json" <<'JSON'
+{
+  "contract": "n8r.surface/0.1",
+  "id": "urn:surface:librechat-uniqueid",
+  "title": "LibreChat",
+  "scope": "Synthetic startup input; no research performed",
+  "revision": {
+    "id": "r1", "parent": null, "createdAt": "2026-11-04T00:00:00Z",
+    "author": "Synthetic author", "reason": "Human startup verification"
+  },
+  "extensions": {}, "kind": "definition", "records": [], "vocabularies": [],
+  "nodes": [], "relationships": [], "requirements": [], "coverage": [], "gaps": []
+}
+JSON
+cp -R "$n8r_verify/home" "$n8r_verify/before"
+printf 'Test home: %s\n' "$n8r_verify/home"
+```
+
+**Expected:** every preparation command exits **0**. The last line identifies the
+home to expect in the overview. Your real `~/.n8r` and `~/n8r` are not used.
+
+## 3. Run with closed input
+
+```sh
+n8r_exit=0
+(cd "$n8r_verify" && env HOME="$n8r_verify/home" "$n8r_verify/install/node_modules/.bin/n8r-surface" </dev/null) >"$n8r_verify/closed.txt" 2>"$n8r_verify/stderr.txt" || n8r_exit=$?
+cat "$n8r_verify/closed.txt"
+printf 'Exit code: %s (expected 1)\n' "$n8r_exit"
+```
+
+**Expected:** return to the shell within **five seconds**, with no question or input
+needed. If it is still waiting, press Ctrl-C and report a failed check. Output must
+match the following; `<test-home>` is the path printed in step 2, and the positive
+PID and UTC timestamp vary each run. Do not type the angle-bracket placeholders.
+
+```text
+Configuration
+  File: <test-home>/.n8r/n8r-surface.json
+  Settings version: 1
+  Artefact folder: <test-home>/n8r/artifacts
+  Surface output: JSON
+  AI runner: Not configured
+  Lab connection: Not configured
+
+Processes
+  n8r-surface overview: running (PID <number>); observed <UTC timestamp>
+  Runner/Lab processes: Status unknown (no live status source)
+
+Local artefacts (1)
+  LibreChat | Surface definition | <test-home>/n8r/artifacts/librechat-uniqueid.json
+
+Setup and AI conversation are not implemented in this build. Research needs a supported AI runner.
+Run in an interactive terminal for read-only setup guidance.
+Exit code: 1 (expected 1)
+```
+
+There must be exactly one artefact row. **Exit 1 is expected** because setup and
+conversation are unavailable in this increment; exit 0 or 2 fails this prepared
+case. Check private-value omission and stderr with:
+
+```sh
+if grep -Fq 'PRIVATE_VALUE_MUST_NOT_APPEAR' "$n8r_verify/closed.txt" "$n8r_verify/stderr.txt"; then printf 'FAIL: private value leaked\n'; else printf 'PASS: private value absent\n'; fi
+if test -s "$n8r_verify/stderr.txt"; then printf 'FAIL: unexpected stderr\n'; cat "$n8r_verify/stderr.txt"; else printf 'PASS: stderr empty\n'; fi
+```
+
+**Expected:** `PASS: private value absent` and `PASS: stderr empty`.
+
+## 4. Answer the real terminal question
+
+Paste this block, then wait for the question. Do not pipe it through `tee` or
+redirect its input/output: the command must see a terminal.
+
+```sh
+n8r_exit=0; (cd "$n8r_verify" && env HOME="$n8r_verify/home" "$n8r_verify/install/node_modules/.bin/n8r-surface") || n8r_exit=$?; printf '\nExit code: %s (expected 1)\n' "$n8r_exit"
+```
+
+**Before typing anything**, confirm that the configuration, processes and the one
+LibreChat row have appeared, followed by the unavailable-setup message and then
+`Show setup requirements? [y/N]`. The private marker must be absent. The closed-input
+message about running in an interactive terminal must not appear here.
+
+Type **`y` and Enter**. Expect:
+
+```text
+Research will require an explicitly selected runner, model and external credential reference. A Lab connection is optional. No settings have been changed.
+
+Exit code: 1 (expected 1)
+```
+
+Run the same block again. This time press **Ctrl-D at the empty question**. Expect
+an immediate return to the shell, `Exit code: 1 (expected 1)`, and no guidance answer
+or error stack. No setup or conversation is expected to start in either case.
+
+## 5. Confirm unchanged files and clean up
+
+```sh
+if diff -r "$n8r_verify/before" "$n8r_verify/home"; then printf 'PASS: fixture files and directory contents unchanged\n'; else printf 'FAIL: startup changed the fixture\n'; fi
+```
+
+**Expected:** only `PASS: fixture files and directory contents unchanged`, with no
+diff. If any step differs from its expectation, retain the temporary folder while
+you investigate and report the step, commit and Node version; do not call it a pass.
+After inspection, remove only the temporary verification folder:
+
+```sh
+rm -r -- "${n8r_verify:?}"
+unset n8r_verify n8r_exit
+git status --short
+```
+
+**Expected:** no output. The temporary installation, synthetic home, snapshot and
+captured output are gone. Ignored `node_modules/` and `dist/` from the build remain
+in the checkout. This procedure verifies bare startup only; it does not complete
+\#16 or verify AI-driven research.

package/docs/n8r-surface/startup-verification.md

@@ -0,0 +1,161 @@
+# STARTUP-01 verification record
+
+**Result:** specified, implemented and verified for the read-only bare-startup
+increment. This does not complete #16 or verify setup, status, discovery or an AI
+conversation. [Settings, parser decisions and limits](startup.md) define the
+implemented boundary. [PR #25](https://github.com/injectionator/n8r-surface/pull/25)
+carries the increment originally developed on #15. This record preserves the
+pre-integration verification revision and does not claim a release.
+
+## Human verification
+
+Follow the [copy-and-paste human check](startup-human-check.md) for prerequisites,
+PR checkout, a disposable installation and synthetic home, exact expected output,
+interactive `y`/EOF steps, private-value checks and cleanup. Its expected exit 1
+is explained explicitly. The automated commands later in this record support
+that hands-on check.
+
+On 4 November 2026, Codex rehearsed the guide's disposable installation, closed
+input, terminal `y` and Ctrl-D, private-value/stderr checks and unchanged-file
+comparison on Node 22.23.2, npm 11.5.2 and macOS ARM64. The expected output and
+exit codes matched; all 43 tests and 20 installed startup checks also passed.
+This is an agent rehearsal, not recorded human acceptance.
+
+## Revision and environment
+
+- Date: 4 November 2026. Implementer/verifier: Codex; separate read-only agent
+  review found no important issues in the startup implementation.
+- Baseline: `5f67dbea2be93a6ee6bedb9a029bc79be4b3997d`.
+- Implementation and retained test revision:
+  `b90358aaf22fead155081bb00f6d837a0f8f59e7`. The matrix below was repeated from
+  this committed revision with a clean working tree before writing this record.
+- macOS ARM64; Node.js **22.23.2, 24.22.2 and 26.13.0**; npm **11.5.2**;
+  Python **3.13.1** for the terminal rehearsal.
+- Private package `n8r-surface@0.0.0-experimental.1`, built and packed locally,
+  then installed outside the checkout using `--offline --ignore-scripts`.
+  `npm ci` populated the dependency cache; no registry publication occurred.
+  Each matrix executable was the `node` binary in its own runtime directory.
+
+## Baseline and prepared state
+
+At the baseline, `command -v n8r-surface` returned no path (exit 1) and the package
+manifest contained no `bin` entry. The installed product interaction was therefore
+**blocked by an absent executable**, not an observed failed startup. No research
+or setup result was invented. After adding the process tests, 16 startup checks
+failed on the missing built entry point while the existing 23 library tests passed.
+
+The repeatable check creates a temporary home containing:
+
+- `~/.n8r/n8r-surface.json`: version 1, `artefactRoot: "~/n8r/artifacts"`,
+  `surfaceFormat: "json"`, and synthetic private markers in ignored settings.
+- `~/n8r/artifacts/librechat-uniqueid.json`: a valid synthetic `n8r.surface/0.1`
+  definition titled **LibreChat**. It is a prepared input, not Researcher output.
+- No runner or Lab configuration. A synthetic credential marker in the process
+  environment must also be absent from output. A saved PID in ignored settings
+  must not imply runner liveness.
+
+**Interaction:** invoke installed `n8r-surface` with no arguments from the
+isolated home. First close stdin and capture output/exit. Then run the same
+installed bin in a real POSIX terminal, wait for the guidance question, check the
+already-received overview, and answer `y`. Repeat with terminal EOF (Ctrl-D).
+No credentials or running Lab are required.
+
+## Observed terminal output
+
+This is the installed PTY readback, with only the temporary home replaced by `~`,
+PID/time represented by labelled placeholders, and readline cursor escapes removed.
+The assertions use the real paths, compare the child PID with its process result,
+and check the timestamp is present. File contents are independently reread.
+
+```text
+Configuration
+  File: ~/.n8r/n8r-surface.json
+  Settings version: 1
+  Artefact folder: ~/n8r/artifacts
+  Surface output: JSON
+  AI runner: Not configured
+  Lab connection: Not configured
+
+Processes
+  n8r-surface overview: running (PID <observed PID>); observed <UTC timestamp>
+  Runner/Lab processes: Status unknown (no live status source)
+
+Local artefacts (1)
+  LibreChat | Surface definition | ~/n8r/artifacts/librechat-uniqueid.json
+
+Setup and AI conversation are not implemented in this build. Research needs a supported AI runner.
+Show setup requirements? [y/N] y
+Research will require an explicitly selected runner, model and external credential reference. A Lab connection is optional. No settings have been changed.
+```
+
+With closed input, the same overview appears, followed by the unavailable-capability
+message and `Run in an interactive terminal for read-only setup guidance.` No
+question appears and the process exits within the five-second test deadline.
+Valid startup exits **1**, explicitly indicating unavailable setup/conversation;
+inspection errors and arguments exit **2**. This is not research success.
+
+## Independent readback and repeatable evidence
+
+| Expected outcome | Observed check |
+| --- | --- |
+| Readable settings and actual configured location | Output matches the prepared configuration path, `artifacts` override, JSON format and unconfigured runner/Lab. Defaults separately resolve to `artefacts`; relative paths resolve against the settings directory. |
+| One logical row per entry | The supplied LibreChat definition appears exactly once with its title, type and filename. Two-entry cases also list HTML research metadata; YAML definitions are read. Controls in titles are escaped. |
+| Private values stay private | Markers in nested/unknown settings, URL credentials, malformed input, artefact bodies and the credential environment are absent. Parser errors never echo source content. |
+| Reliable status only | The displayed live overview PID equals the spawned child PID. Runner/Lab status remains unknown, including with a saved PID or declared runner/Lab configuration. |
+| Read-only startup | Before/after bytes, modes and modification times match; the snapshot also checks the directory inventory. PTY `y` and EOF preserve the files and directories. |
+| Empty differs from unavailable | Empty folders say empty; missing/unreadable folders report the path/problem. Invalid or unreadable configuration prevents corpus inspection and remains intact. |
+| Unsupported entries do not disappear or hang | Unsupported, invalid, oversized, unreadable, symlink and directory entries retain a row with a limitation. FIFO configuration and entries finish without blocking. |
+| Overview precedes interaction | PTY checks see configuration, processes and the artefact row before the live guidance question, then supply `y` or EOF. |
+| Installed consumer needs no checkout | The tarball supplies the executable, library and assets. The same startup assertions invoke `n8r-surface` from its installed bin directory under a temporary home. |
+
+All **43 tests** (23 existing library checks plus 20 startup checks) passed with
+`npm test` on each supported Node major above, with no skips. The installed-package
+matrix passed the library consumer check, all **20 startup checks**, and both PTY
+interactions on each runtime. A separate reviewer also exercised terminal `n`,
+Ctrl-D and Ctrl-C on Node 22 without raw diagnostics or a hang.
+
+A validation regression found during implementation treated explicit null settings
+as defaults. Two new checks failed before the fix; null folder/format values now
+report invalid configuration without inspecting a fallback folder.
+
+Reproduce from the repository:
+
+```sh
+npm ci
+npm test
+npm run check:package
+```
+
+For the supported runtime matrix, run `npm test` with each runtime on PATH, then:
+
+```sh
+node scripts/check-package.mjs /path/to/node22/bin/node /path/to/node24/bin/node /path/to/node26/bin/node
+```
+
+The paths above are placeholders. Use binaries named `node` in separate runtime
+directories: the installed shebang resolves `node` from that directory on PATH.
+A custom-named executable beside a different `node` would not establish the same
+matrix. Retained evidence is ordinary code in
+[startup.test.mjs](../../tests/startup.test.mjs),
+[startup-pty.py](../../tests/startup-pty.py) and
+[check-package.mjs](../../scripts/check-package.mjs), plus the observed readback
+above. The checks remove their temporary installations/homes. No raw machine
+paths or private logs are retained in the repository.
+
+## Remaining limits
+
+Only the command's own process is directly known; there is no process registry or
+proof of a live AI runner or Lab. Configured runner/Lab objects are declarations
+whose contents are withheld. Missing setup is explained, not repaired.
+
+The listing recognizes the experimental #15 profile. Older illustrative LibreChat
+JSON, manually edited HTML, unknown formats and unsupported versions get a
+limitation row; there is no universal Surface conformance claim. Files are bounded
+per entry, but this increment does not provide a large-corpus index or total scan
+time limit. Network-mounted folders were not exercised. Linux and Windows were
+not exercised; PTY verification requires POSIX and Python. No inference, source
+research, Lab compatibility, registry/npx download or release claim is made.
+
+Next in #16: separately specify and verify `status`, then real setup, help/version,
+source selection, guarded storage and unavailable-discovery handling. Actual
+Researcher instructions and AI-driven repository research remain #17.

package/docs/n8r-surface/startup.md

@@ -0,0 +1,151 @@
+# Bare startup and local vault setup (#16)
+
+Bare `n8r-surface` displays readable non-private configuration, legacy saved
+artefacts and known own-process status. It then offers first-use vault setup or
+reuses the configured vault. Setup does not start research, scan source contents,
+use a network, launch a runner or require an account. Bare startup is unchanged by the separate [Codex discovery increment](codex-research-verification.md).
+SOURCE-01 remains paused; the new discovery path does not incorporate that checkpoint. This increment does not complete #16 or #30.
+
+The earlier read-only overview and guidance question were delivered by
+[PR #25](https://github.com/injectionator/n8r-surface/pull/25).
+[Historical STARTUP-01 evidence](startup-verification.md) applies to that revision.
+The setup increment replaces its guidance question and exit behavior; see the
+[current setup rehearsal and human tasks](vault-setup-verification.md).
+
+## Settings and parser decisions
+
+One settings file: `~/.n8r/n8r-surface.json`, version 1, limited to 64 KiB.
+The process home directory selects `~`, allowing an isolated verification home.
+There are no project settings, command-line overrides or credential environment
+reads. The repository's `.local/vault-path` remains an agent convention and is
+not read by this command.
+
+```json
+{
+  "version": 1,
+  "vaultRoot": "~/n8r/",
+  "artefactRoot": "~/n8r/artefacts",
+  "surfaceFormat": "json"
+}
+```
+
+`vaultRoot` is optional; absence means setup is pending. It stores the vault for
+future research, containing `research/`, `artifacts/` and `surfaces/`.
+`artefactRoot` remains the separate legacy structured-artefact location and defaults
+to `~/n8r/artefacts`. No migration, renaming or inference from its parent occurs.
+Both locations are displayed. Existing legacy content and every unknown settings
+value are preserved. `surfaceFormat` defaults to `json` and also accepts `yaml`.
+Optional `runner` and `lab` objects (or null) remain independent declarations;
+only configuration presence is shown, never their private contents.
+
+Expand `~/` against home. Stored relative paths resolve against the settings
+folder. Newly entered relative vault paths resolve against invocation cwd;
+first setup saves an absolute path. Validate the fully expanded/resolved path as
+well as the input so that neither can introduce forbidden control characters.
+Resolve pre-existing ancestors and an
+explicitly selected vault-root symlink before showing the destination. Reject
+empty custom paths, control characters, URL forms, non-directory collisions,
+settings symlinks/special files and symlinked required vault children. Invalid
+settings are retained for repair, never replaced with defaults.
+
+Only zero arguments launches startup. Discovery, reopening and local help/version
+have separate paths described in [the command inventory](command-outcomes.md#initial-public-command-inventory).
+Unknown arguments exit 2 without echoing them or inspecting settings. No `setup`,
+`--vault`, `--path` or `status` command is added.
+
+## First use, reuse and repair
+
+The read-only overview precedes all questions. With both input and output attached
+to terminals, first use asks:
+
+```text
+Vault directory [~/n8r/]:
+Vault directory: <resolved absolute path>
+Create vault folders and save this location? [y/N]
+```
+
+Enter at the location question chooses `~/n8r/`. Only `y` or `yes` (case insensitive)
+at confirmation permits writes. Refusal, EOF and interruption before acceptance
+exit 1 without writes. Acceptance creates only missing directories, then adds
+`vaultRoot` to settings and prints `Vault ready: <resolved absolute path>`.
+Existing JSON member bytes are retained when inserting the new field, including
+unknown numeric literals outside JavaScript precision/range.
+No source files are read or written. Reject writes to settings/vault paths inside
+the invocation directory, including symlink aliases and missing descendants.
+Also reject vault folders inside the legacy corpus: adding directories there
+would break its next inspection. Running setup from home can therefore be refused; run from a separate source
+folder. Complete configured reuse is read-only even from such a directory.
+
+A complete configured vault exits 0 without questions, locks or settings rewrites.
+Missing required folders need repair confirmation; repair creates folders without
+rewriting settings. An occupied child path or inaccessible vault exits 2. Existing
+vault files are never removed. A failed confirmed setup may leave empty folders;
+retry reuses them. Setup does not create the legacy corpus when it is absent.
+
+| Outcome | Exit | Writes |
+| --- | --- | --- |
+| Successful accepted setup/repair | 0 | Missing folders; settings only on first setup |
+| Complete configured reuse | 0 | None |
+| Decline, EOF or interrupt before confirmation | 1 | None |
+| Setup/repair needed with nonterminal input or output | 1 | None |
+| Invalid settings/arguments, filesystem or conflict error | 2 | No successful setup claim; partial confirmed folders may remain |
+| Legacy inspection error except absent corpus | 2 | None; takes precedence before any setup question |
+
+Closed-input setup/repair prints exactly:
+
+```text
+Vault setup required; run n8r-surface in an interactive terminal.
+```
+
+It finishes promptly without waiting. Missing legacy corpus is reported as
+unavailable/absent (`ENOENT`) and permits setup/reuse; it is not reported empty.
+Other legacy errors remain visible even when a complete vault exists.
+
+## Concurrency and recovery boundary
+
+The user approved this cooperating-writer boundary on 5 November 2026. Other
+editors must not write settings during confirmed setup. Directory/symlink topology
+must stay stable while setup runs. This is not an adversarial filesystem or
+power-loss durability guarantee, nor protection against arbitrary external writers.
+
+After confirmation, exclusively create `~/.n8r/n8r-surface.json.lock`. Other setup
+processes fail with exit 2 rather than wait or steal the lock. Compare the original
+settings bytes under the lock before folder creation and again before publication.
+Detected edits fail and retain the competing values. Write an exclusive temporary
+sibling and close it only after all required folders are available. For absent
+settings, publish with an exclusive hard link: a competing creator is preserved
+even after the final byte check. For existing settings, atomically rename under
+the lock. A writer ignoring that lock can still race the final check/rename;
+no stronger guarantee is claimed.
+
+Normal completion/failure removes only this invocation's temporary sibling and
+lock. A killed process may leave these and empty folders. If a lock remains,
+first establish that no setup process is active, inspect the saved settings and
+vault, then remove the stale `n8r-surface.json.lock` manually and retry. Never
+remove a lock while another setup may be running. Abandoned `.tmp` siblings may
+be inspected and removed manually after establishing ownership; automatic setup
+does not delete another invocation's files. No automatic age/PID-based lock theft.
+
+## Local inspection boundary
+
+List direct legacy folder entries in filename order, one terminal-safe line each.
+Read JSON/YAML definitions and HTML research records with existing bounded readers;
+use title/type metadata, never source or extension contents. Unsupported, invalid,
+oversized, unreadable, symlink and non-regular entries remain visible as errors.
+Do not recurse, open source locations or execute HTML. Reads are bounded to 2 MiB
+per artefact. Terminal controls, line separators and bidi characters are escaped.
+
+The process identifies only its own PID and observation time. Runner/Lab process
+status remains unknown; configured settings do not establish a live process.
+There is no daemon, PID registry, source scan, network probe or inference.
+
+## Verification boundary
+
+Transaction tests cover preserved values/bytes, malformed and oversized settings,
+source overlap and symlinks, deterministic conflicting writes, a second real
+process under a held lock, partial filesystem/publication failure and retry.
+Process and PTY checks exercise the real command with independent filesystem
+readback; the package check repeats them outside the checkout. See
+[the verification record](vault-setup-verification.md) for exact revisions,
+runtimes, human tasks and remaining limits. Automated rehearsal is not human
+acceptance or proof of research, save/continue, or consumer compatibility.