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

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

@@ -0,0 +1,161 @@
+# Partial Surface generation and revision evidence
+
+This records the bounded #17 candidate, not human acceptance or completion of
+all #17 scope. Follow the [short tester walkthrough](getting-started.md); the
+[design](../superpowers/specs/2026-11-05-surface-revisions-design.md) and
+[SURFACE-01](command-outcomes.md#surface-01-generate-save-and-revise-a-partial-surface)
+define the intended outcome.
+
+## Starting state and actual interaction
+
+The installed baseline help on 5 November 2026 advertised Markdown-only saves.
+Structured generation/persistence was an explicitly authorized known missing
+capability. This was not represented as a failed live AI trial.
+
+The rehearsal starts with the real Researcher's earlier saved Lumen note, including
+five component IDs, a human decision not to select external OIDC and a later human
+session-expiry priority. The source is the fictional
+[Lumen guide](../../examples/researcher/sources/lumen-guide.md). The agent copied
+that existing note and source into a new local rehearsal directory, recorded their
+bytes and configured a separate test vault. It installed a candidate tarball into
+an isolated prefix with scripts disabled, keeping the normal global installation.
+
+Actual interactions through the installed command:
+
+1. Reopen the note with the explicitly selected source and renew transmission
+   consent. Ask the Researcher to create a partial Surface, retain all five IDs,
+   the OIDC non-selection and expiry priority, and show selections and unknowns.
+2. Inspect the host-generated preview; enter `/save surface`, then `/exit`.
+3. Start a fresh process from the saved JSON. Select OIDC because the investigation
+   now needs centralized sign-in, explicitly leaving provider identity and runtime
+   behavior unknown. Request the updated Surface, save and exit.
+4. Start another fresh process from the successor HTML. Ask which decision changed
+   and what remains unknown, then exit without saving.
+
+The developing agent supplied those interactions, not prewritten findings or
+structured artefacts. The real Codex Researcher read sources and generated content.
+Independent code read the actual saved files afterward; scripted protocol tests
+are separate evidence.
+
+## Probe and reviewed candidate
+
+The initial installed probe used product code `f34522f`. It completed all three
+Lumen processes with exit 0. Independent readback verified the five existing IDs,
+OIDC rejected → selected, session-expiry context, exact research references and
+successor lineage. The first definition had no selected edges; the second added
+the declared Lumen → OIDC selection. This is a partial desired composition, not
+runtime configuration or proof of reachability.
+
+Review identified two preview-state bugs: an invalid replacement could retain an
+earlier staged candidate, and a Markdown save turn could stage an unshown Surface.
+Both were reproduced with failing tests and fixed at `62cc6d9`. The same commit
+requires evidence basis for every generated entity and retains historical claims,
+notes and question identities. A fresh targeted reviewer verified the fixes and
+ran 19 focused tests without unresolved findings.
+
+The probe's script originally sampled checkout HEAD at completion, while review
+work had advanced it. Its local report was corrected to identify the installed
+`f34522f` product code and retain the originally sampled value with an explanation.
+Tarball hashes identify exact installed bytes; a later checkout revision is not
+substituted for the running candidate.
+
+## Corrected-candidate rehearsal
+
+The complete Lumen cycle passed against product code
+[`62cc6d9`](https://github.com/injectionator/n8r-surface/commit/62cc6d9131badb0a086f3bdb2e3f6bc38f0e14b9)
+on 5 November 2026. All three fresh installed processes exited 0. The independent
+Harbor check also passed through three fresh processes, each exiting 0.
+
+| Environment / input | Recorded identity |
+| --- | --- |
+| Host | macOS; Node 26.13.0; Codex CLI 0.166.0 |
+| Inference | `gpt-6-astra`, existing ChatGPT sign-in; no provider/API-key fallback |
+| Shared Researcher | 0.1.8; instruction digest `sha256:8af29c3073df9b8210a7dd94ced9700379b0a98f76bd3a2902f9430b93c98a2a` |
+| Host adapter | Structured tool instructions and restrictions at code `62cc6d9` |
+| Installed tarball | SHA-256 `59fde46cfff0f3b9bdba198d6c637891d0102ac46da5870580aab2a620367fdb` |
+| Original note | SHA-256 `76b6abe6d616b903f641f2b8d52f06777ad5383060701ce49a314d3ff68eca52` |
+| Lumen source | SHA-256 `98d3374c79c166b37f0debb4ffb5e457eda1385dd7847b042cbad674cac98693` before and after |
+
+The tarball contains the exact code at that revision plus in-progress documentation;
+its hash identifies the installed package. Independent byte comparison confirmed
+all installed built files match the source build. The shared instruction digest
+identifies bundled Researcher instructions; the host adapter code separately
+identifies its structured-output instructions.
+
+Independent readback used `readResearchHtml`, `decode`, `verifyReferences`,
+`verifySuccessor` and the host's additional preservation checks. It retained
+`component:lumen`, `component:inference`, `component:archive`, `component:callback`
+and `component:oidc` across both definitions. OIDC changed from rejected to selected
+under the same decision ID; the selected successor adds one declared centralized
+sign-in edge. Provider/model identity and runtime behavior remain unknown.
+
+The initial record has 11 findings and one source; its successor has 14 findings
+and two source observations, retaining historical claims and human notes. The
+session-expiry priority survives. Original note, first pair, source and settings
+bytes are unchanged. Reopening the successor HTML retained the changed decision
+without creating a third pair.
+
+| Logical object | Digest |
+| --- | --- |
+| Initial research | `sha256:a9cc46c071bebffe7048962971ec69d565c9418b6815d8fe0895879a930cc69b` |
+| Initial Surface | `sha256:ebf4cb0e801598ed512555db9f6af03ec21cf3dc204509a78ad6d2dfab81b85c` |
+| Successor research | `sha256:d6630b518b1fb655a9f2132f3ce51993013d966c666dc5b1d37091f466680b53` |
+| Successor Surface | `sha256:8b3c84e590851b234be05c853ad2b5b63c1f641778995f33812151ccf96aa43d` |
+
+Parent references match the exact initial identities, revisions and logical digests;
+manifest hashes match independently read file bytes. Raw terminal logs, original
+inputs, tarball and readback reports remain in the selected local vault's `runs/`
+folder; no machine-specific location is published.
+
+The independent Harbor trial used the fictional
+[interface notes](../../examples/researcher/sources/harbor-api.md). The Researcher
+created a Markdown note, then reopened it to generate a pair, then reopened the
+pair's HTML in another fresh process. Independent readback confirmed ten findings,
+three stable IDs (`urn:harbor:archive`, `urn:harbor:intake-client`,
+`urn:harbor:callback-receiver`), deferred callback selection and explicit unknown
+authentication/compatibility. Source, note and settings bytes remained unchanged.
+This is a smaller second-product check, not a Harbor integration or deployment trial.
+
+The [actual sanitized transcript](surface-revisions-transcript.md) preserves the
+six installed conversations, prompts, source tool output, previews and save paths
+with machine-specific path prefixes replaced. Spinner frames are omitted. The
+complete logs and readback retain their original bytes locally.
+
+## Automated supporting checks
+
+At `62cc6d9`, 115 Node tests and the installed-package check passed. New tests cover
+host-owned references, invalid structured input, immutable pair history, original
+note/predecessor conflicts, malformed manifests, symlink ancestry, relocated pairs,
+publication failure, missing historical sources, context bounds, validation repair,
+failed turns and stale/unshown preview rejection. The package test uses a scripted
+Codex process; it is not evidence of model reasoning.
+
+The full 115-test suite and installed-package check also passed separately on
+Node 22.23.2, 24.22.2 and 26.13.0. `npm ci` and `npm cache add yaml@2.9.1` prepared
+the dependency cache; package consumer installation used offline mode with scripts
+disabled. Final Markdownlint 0.24.0, offline Lychee 0.24.2, cffconvert 2.0.0,
+shell syntax, 24 Python tests and whitespace checks passed. All six GitHub checks
+also passed at code `62cc6d9`; later documentation commits have their own CI runs.
+
+## Storage and remaining limits
+
+Each numbered directory contains research HTML, Surface JSON and a host manifest
+with byte hashes/provenance. The host validates and reads back all members. The
+Surface pins the research logical revision/digest; successors pin their own
+predecessors. The manifest is storage metadata, not a second model or authenticity
+proof. Original Markdown notes and earlier pairs remain available.
+
+Reopening requires an intact host-created pair and renewed source/transmission
+consent. It supports one research record per pair, bounded to 512 KiB of transmitted
+context. Arbitrary multi-record imports, automatic reconciliation of manually edited
+HTML, deliberate component deletion/migration and YAML generation are outside this
+increment. Directory topology must remain stable during synchronous filesystem
+operations; no adversarial concurrent-filesystem guarantee is claimed.
+
+The host checks structure, references and selected preservation rules. Interpretation
+of prose, human intent and source meaning still needs review. Missing detail does
+not establish absence. Declared edges do not establish reachability or exercised
+behavior. These trials do not establish universal model conformance, consumer
+compatibility, Lab recreation, external-host lifecycle or registry distribution.
+The package remains private; npm work is last and separate. Human acceptance of
+this increment is pending, and #17 remains open.

package/docs/n8r-surface/tester-candidate.md

@@ -0,0 +1,158 @@
+# Try Researcher candidate 0.1.13
+
+**Takeaway: understand what your supplied sources reveal about an AI system,
+and choose the next useful investigation.** Save that understanding, its evidence
+and unanswered questions so you can return to it later.
+
+This is an interim test candidate, not a release or security certification.
+It describes and investigates; it does not configure or deploy your system.
+A source checkout shows supported possibilities. Nonsecret configuration can
+establish selected connections; dated runtime evidence is needed to claim use.
+
+## Choose a host
+
+| Host | Candidate evidence | Installation effort |
+| --- | --- | --- |
+| Codex CLI | Installed research/save/continuation rehearsed; human acceptance pending. | Existing CLI and sign-in, Node 22/24/26, then three commands below. |
+| Codex desktop / ChatGPT Work | CLI registration is checked; fresh desktop loading and acceptance remain pending. | Maintainer-assisted installation, restart and fresh-chat selection check. |
+| Claude Code | Skill file installation checked; research/save/continuation untested. | Existing Claude Code, Node and Git; one installer command below. |
+| Claude web / desktop Chat | Host supports custom skill ZIP upload; this candidate is untested there. | Upload a skill-shaped ZIP in Customize > Skills and enable it; source access, helper runtime and persistence still need checking. |
+
+The instructions use the host's tools and model rather than an OpenAI API client.
+Portability of instructions does not establish equivalent host behavior.
+Claude Code's local filesystem access is distinct from web/desktop Chat's
+execution environment. A local path mentioned in chat does not grant access.
+Cowork is another environment requiring its own rehearsal.
+
+For a nontechnical tester today, use an existing Codex installation with
+maintainer help for setup, then follow the short task below. There is no verified
+one-click cross-host installation. Claude's upload route is potentially simpler,
+but is not yet a recommended route for testing this candidate's saved Surfaces.
+
+## Install the pinned Codex candidate
+
+Prerequisites: Codex CLI 0.166.0, Git/network access and Node.js 22, 24 or 26.
+Research also needs the host's sign-in and access to the supplied sources.
+From any directory, for a **new** n8r-surface marketplace registration:
+
+```sh
+codex plugin marketplace add injectionator/n8r-surface --ref d0ec3ece555fbcffb9788aed6593f380900e2d25 --json
+codex plugin add n8r-surface@n8r-surface --json
+codex plugin list --marketplace n8r-surface --json
+```
+
+Expect exit 0 for each command and exactly one installed/enabled entry at
+`0.1.13`. These commands fetch GitHub content and write the selected Codex home's
+plugin configuration/cache. They do not install the npm product CLI or research
+the source. Existing registrations may be pinned elsewhere: have the maintainer
+inspect the source before following the [replacement procedure](workspace-installation.md).
+Do not silently replace a tester's existing registration.
+
+Restart the desktop host when applicable, open a fresh chat and select
+**n8r-surface Researcher**. Missing selection or an unexpected version is Blocked;
+CLI installation alone does not pass this desktop check.
+
+## Can I use npx?
+
+Yes, for a standalone skill installation through the third-party
+[Vercel Labs skills installer](https://github.com/vercel-labs/skills).
+This is different from running `npx @n8r/surface`, which starts the separate npm
+command and does not install the Researcher skill.
+
+The following exact command was exercised with `skills` 1.8.1 and Node 26.13.0.
+Run it in a new trial project folder, with Git/network access, for **Claude Code**:
+
+```sh
+env DISABLE_TELEMETRY=1 npx --yes skills@1.8.1 add https://github.com/injectionator/n8r-surface/tree/d0ec3ece555fbcffb9788aed6593f380900e2d25/plugins/n8r-surface/skills/research --skill research --agent claude-code --copy --yes
+```
+
+Expect exit 0, `.claude/skills/research/` and `skills-lock.json` in that folder.
+All 18 copied skill files matched the pinned source in the installation check.
+It downloads/runs the installer through npm's cache and fetches the source from
+GitHub; telemetry is disabled by the process-scoped variable. It copies the skill,
+not plugin manifests, icons or root licence files. Do not redistribute that bare
+copy as the complete licensed plugin package. Do not run over an existing
+same-named `research` skill. This project-scoped command does not register a
+Codex plugin or install into Claude web/desktop Chat.
+
+In Claude Code opened in that folder, `/research` is the host-documented invocation
+for a standalone skill named `research`. Actual candidate invocation, source
+research, helper execution and fresh-session continuation remain **untested**.
+Do not treat the install success as a support claim. Other agent targets offered
+by the installer were not rehearsed here.
+
+## Tester task: one useful explanation
+
+Maintainer preparation: verify installation and provide a readable source pack
+and a writable output folder. Reuse the [working manual](skill-manual.md) and
+[recorded rehearsal](skill-bom-verification.md); no services need starting.
+For a synthetic trial, provide [Lumen's guide](../../examples/researcher/sources/lumen-guide.md)
+and [settings](../../examples/researcher/sources/lumen-settings.md).
+
+- [ ] Open a fresh chat with the installed Researcher selected and supply the
+  source files. Ask:
+
+  > Explain what these sources reveal about the AI system. Keep the first answer
+  > short: Sources provided (distinguish inspected from merely supplied), Summary
+  > (link the evidence), and Now what? (one useful next action). Save the Surface
+  > in the output folder I supplied. Keep deployment choices unknown unless the
+  > supplied evidence establishes them. Do not execute the source or start services.
+
+  Expect an evidence-linked explanation, explicit coverage limits and links to
+  the saved brief, map and journal. For Lumen, retain conflicting batch maxima
+  10 and 25 and the unknown model version; do not silently choose one value.
+- [ ] Open the linked files. Follow one evidence reference back to the supplied
+  source. Expect the cited claim to be supported and unsupported selections to
+  remain unknown. The current generated brief is longer than the requested chat
+  summary; report whether that obstructs understanding.
+- [ ] Answer the Researcher's question or redirect it, then ask it to save.
+  Expect a new numbered revision retaining your decision and the earlier files.
+- [ ] Open a fresh chat with the same skill. Supply the latest
+  `surface.cdx.json` and source access. Ask: “Continue this Surface. What did I
+  choose, what remains uncertain, and what should we investigate next?” Expect
+  the choice and gaps to survive; unavailable evidence must be acknowledged.
+
+Return **Pass / Fail / Blocked**, the host/version, what you asked, one useful
+finding, and any missing or confusing result. Include nonsecret output references.
+Pass means useful explanation, inspectable evidence and preserved continuation;
+fabrication, lost choices or overwritten predecessors are failures. Missing host,
+source or runtime access is Blocked. Wording, filenames and findings may vary.
+Human acceptance is separate from the earlier agent rehearsals.
+
+Optional cleanup: use `codex plugin remove n8r-surface@n8r-surface --json` for
+this Codex installation, or remove only the newly created Claude trial folder.
+Keep your research outputs. Do not delete pre-existing skills or project files.
+
+## Package identity and remaining work
+
+The retained complete plugin ZIP is `n8r-surface-skill-0.1.13.zip`, containing
+24 files under `n8r-surface/`, including licences and notices. SHA-256:
+
+```text
+bdab66880bc1763c73ee30d98d3b188a4c8ae2af410f03b364785fbcc58640dd
+```
+
+It matches commit `d0ec3ece555fbcffb9788aed6593f380900e2d25` byte for byte.
+This plugin-shaped ZIP is **not** a verified Claude custom-skill upload ZIP;
+Claude expects a skill folder with SKILL.md. No upload or publication was done.
+
+On 13 November 2026, an isolated Codex home fetched that commit and installed
+0.1.13 with all 24 files matching; a separate trial folder exercised the npx
+command with all 18 skill files matching. Both commands exited 0. The prior
+installed research evidence is linked above; no new research acceptance is claimed.
+
+The proposed primary presentation is **Sources provided / Summary / Now what?**,
+with expandable inspected-source detail and links to deeper evidence. This was
+reviewed as an editorial preview, not implemented in the generator. Candidate
+0.1.13 still generates inventory, connections and gaps. Preserving an authored,
+evidence-linked summary in the authoritative Surface and regenerating it remains
+follow-up work; this package does not promise that presentation is already saved.
+
+## Official host references
+
+Reviewed 13 November 2026; host support does not establish candidate acceptance:
+
+- [OpenAI plugin packaging and marketplaces](https://developers.openai.com/plugins/build/plugins)
+- [Claude Code skills, invocation and local locations](https://code.claude.com/docs/en/skills)
+- [Claude custom skill upload and prerequisites](https://support.claude.com/en/articles/12512180-use-skills-in-claude)
+- [Vercel Labs installer commands and scope](https://github.com/vercel-labs/skills/blob/main/docs/commands.md)

package/docs/n8r-surface/vault-setup-verification.md

@@ -0,0 +1,210 @@
+# Vault setup: maintainer verification record
+
+**Installing or trying the command? Start with
+[Install and choose your vault](getting-started.md).**
+The procedures below are for maintainers recording isolated test evidence; they
+are not prerequisites for using the command.
+
+## Intent and expected result
+
+Given an installed candidate, an empty isolated home and a source directory
+outside the proposed vault, run `n8r-surface`, press Enter, then enter `y`.
+Expect exit 0, a saved version-1 `vaultRoot`, and `research/`, `artifacts/`,
+`surfaces/` under that vault. Independently open settings/folders and compare
+source bytes. Run again from a second source directory: expect the same vault,
+no question, exit 0 and unchanged settings/vault contents.
+
+With another empty home and closed input, expect the setup-required message,
+exit 1 promptly and no writes. No research, runner, scanning or findings are
+part of this result. See [the exact contract](startup.md) and
+[approved plan](../superpowers/plans/2026-11-05-standalone-vault.md).
+
+## Baseline actually observed
+
+On 5 November 2026, a clean tarball at
+`6c88ffb8fd325df0421f9291c81776a892b2bdc1` was built and installed offline outside
+the checkout. Environment: macOS 26.6.2 ARM64, Node 26.13.0. Two empty isolated
+homes and a synthetic source containing `README.md` were prepared.
+
+Both real-terminal and closed-input `n8r-surface` runs exited **2**, reported the
+missing legacy `n8r/artefacts` corpus (`ENOENT`) and said setup was unimplemented.
+No question appeared. Independently enumerated homes remained empty and source
+bytes were unchanged. **Fail** against the new setup intent; successful baseline
+observation. This supersedes the earlier missing-executable blocker, without
+claiming any baseline setup success.
+
+## Candidate observations
+
+Product/test revision: `ebcb4b7eea1029ef013aa4a82f01195c4548a913`, stacked
+on the unmerged planning PR #31 at `6c88ffb`. Agent rehearsal on 5 November 2026,
+macOS 26.6.2 ARM64; no human acceptance is claimed.
+
+| Runtime | Full suite | Installed process checks | Installed terminal interactions | Library consumer |
+| --- | --- | --- | --- | --- |
+| Node 22.23.2 | 74 passed | 25 passed | 18 passed | Passed |
+| Node 24.22.2 | 74 passed | 25 passed | 18 passed | Passed |
+| Node 26.13.0 | 74 passed | 25 passed | 18 passed | Passed |
+
+Each `npm test` and `npm run check:package` exited 0, with no failed/skipped tests.
+The package check installed a tarball outside the checkout and executed the bin.
+The full suite's terminal case repeats the same 18 interactions against the build.
+
+The human task list below was separately rehearsed through a disposable installed
+candidate on Node 26.13.0, using a real terminal and manually supplied Enter/`y`:
+
+| Task | Actual observation and independent readback | Agent result |
+| --- | --- | --- |
+| First use | Location then confirmation appeared; Enter/`y` printed `Vault ready:` and exited 0. | Pass |
+| Open saved state | Parsed/read JSON contained exactly `version: 1` and absolute `vaultRoot`; directory listing showed `research`, `artifacts`, `surfaces`. | Pass |
+| Another source directory | Same vault, no question, exit 0. Recursive before/after home comparison exited 0; both source comparisons exited 0. | Pass |
+| Closed input, empty home | Exact setup-required line, exit 1 promptly; independent directory enumeration found zero entries. | Pass |
+
+The automated interactions additionally exercised custom relative paths with
+spaces, retained legacy/unknown settings, repair without settings modification,
+refusal, EOF and SIGINT at both questions, and an external edit before acceptance.
+The final review added installed checks for legacy-corpus overlap refusal and
+safe/unsafe resolved root symlinks.
+Transaction tests exercised deterministic publication conflicts/failures and a
+second real process while the first held the lock. None of this is AI research
+or proof of safety against writers outside the documented boundary.
+
+Supporting repository checks: 24 Python fixture/workflow tests, Bash syntax,
+Markdownlint 0.24.0 (56 files), cffconvert 2.0.0 and whitespace checks passed.
+Lychee 0.24.2 passed for all tracked Markdown (zero errors). The exact
+broad `**/*.md` invocation failed on 15 pre-existing links in an ignored local
+evidence folder. That unrelated material was left unchanged; the broad command
+is not reported as passing.
+
+Fresh-context code review found three Important preservation/reuse failures:
+legacy overlap, unknown numeric literal loss, and controls introduced by path
+resolution. Each received a failing regression before the fix; the final suite
+and installed matrix above were repeated after all fixes. No Critical or Minor
+findings were reported, and none were deferred. The final pass retains the
+approved setup-only and concurrency boundaries; it is not approval to merge.
+
+Public output is sanitized; exact temporary paths and raw local evidence remain
+outside tracked files. No real deployment data was used.
+
+## Installation-guide rehearsal
+
+On 5 November 2026, the documentation follow-up exercised the exact three npm
+commands in [the getting-started guide](getting-started.md): `npm ci`, `npm pack`,
+and global installation of the generated local tarball. All exited 0. Only npm's
+global prefix was redirected to a temporary directory; the normal installation
+was untouched. The installed bin then passed all 18 terminal interactions under
+isolated homes on Node 26.13.0. This verifies the local-package installation route,
+not npm registry publication or human acceptance.
+
+## Maintainer preparation
+
+Use a POSIX macOS/Linux terminal with Bash or zsh, Node 22, 24 or 26, npm and
+Python 3.9+. The recorded environment is macOS; Linux and Windows are not local
+acceptance claims. No account or AI credentials are needed. Start in this PR's
+checkout, after preserving unrelated work. Record `git rev-parse HEAD`,
+`node --version` and the operating system. Do not use a real user home as the
+fixture or delete existing settings.
+
+Build/install a disposable candidate, prepare two small sources, and define a
+shell wrapper that gives only the installed command the isolated home:
+
+```sh
+npm ci && npm cache add yaml@2.9.1 && npm run build
+n8r_verify=$(mktemp -d "${TMPDIR:-/tmp}/n8r-vault-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_verify/closed-home" "$n8r_verify/source" "$n8r_verify/source-two"
+printf 'Synthetic source bytes.\n' > "$n8r_verify/source/README.md"
+printf 'Second source bytes.\n' > "$n8r_verify/source-two/README.md"
+cp -R "$n8r_verify/source" "$n8r_verify/source-before"
+cp -R "$n8r_verify/source-two" "$n8r_verify/source-two-before"
+n8r-surface() { env HOME="$n8r_verify/home" "$n8r_verify/install/node_modules/.bin/n8r-surface" "$@"; }
+cd "$n8r_verify/source"
+```
+
+Every preparation command must exit 0. npm preparation downloads dependencies;
+the local tarball installation uses the prepared cache. The command's own setup
+has no network activity. No vault/settings files are prepared on its behalf.
+
+## Tester task list
+
+- [ ] In that prepared terminal, run `n8r-surface`. Expect configuration and legacy
+  corpus information, followed by `Vault directory [~/n8r/]:`. Press Enter. Expect
+  the resolved path and `Create vault folders and save this location? [y/N]`.
+  Enter `y`. Expect `Vault ready:` with that path. Run `echo $?`: expect **0**.
+- [ ] Open the reported settings file and vault in your editor/file browser.
+  Expect `version: 1`, absolute `vaultRoot`, and the three directories `research`,
+  `artifacts`, `surfaces`. No legacy `artefacts` directory is promised or created.
+  Open the source folder: its original `README.md` should remain the only file.
+- [ ] Before reuse, the maintainer takes the readback snapshot described below.
+  Run `cd "$n8r_verify/source-two"`, then `n8r-surface`. Expect the same vault,
+  no question, and `echo $?` showing **0**. No research has begun.
+- [ ] Run the following closed-input case. Expect prompt return (within five
+  seconds), the exact setup-required line below and exit **1**. The maintainer
+  verifies the second home is still empty.
+
+```sh
+env HOME="$n8r_verify/closed-home" "$n8r_verify/install/node_modules/.bin/n8r-surface" </dev/null
+echo $?
+```
+
+```text
+Vault setup required; run n8r-surface in an interactive terminal.
+```
+
+**Report:** Pass / Fail / Blocked for each task, candidate commit, Node/OS, the
+interaction attempted, visible result and settings/folders inspected. Paths,
+PID and observation timestamp vary; directory names and exit codes do not.
+Missing folders, forgotten settings, changed source bytes or waiting on closed
+input are failures. Human acceptance is separate from the agent rehearsal.
+
+## Maintainer readback and cleanup
+
+Immediately after first setup, before reuse:
+
+```sh
+cp -R "$n8r_verify/home" "$n8r_verify/home-after-setup"
+cat "$n8r_verify/home/.n8r/n8r-surface.json"
+ls -la "$n8r_verify/home/n8r"
+```
+
+After all tester tasks:
+
+```sh
+diff -r "$n8r_verify/home-after-setup" "$n8r_verify/home"
+diff -r "$n8r_verify/source-before" "$n8r_verify/source"
+diff -r "$n8r_verify/source-two-before" "$n8r_verify/source-two"
+ls -A "$n8r_verify/closed-home"
+```
+
+Expect all three diffs to exit 0 with no output and the final listing to be empty.
+These checks independently inspect actual command-created state. The automated
+PTY harness also compares settings modification time on reuse/repair.
+Keep the dedicated folder until evidence is reviewed. Optional cleanup:
+
+```sh
+cd "$n8r_verify/.."
+unset -f n8r-surface
+rm -r -- "${n8r_verify:?}"
+unset n8r_verify
+```
+
+Only this dedicated test environment is removed. The checkout's ignored build
+and dependencies remain. Never apply this cleanup to a real home or source.
+
+## Supporting checks and limits
+
+`npm test` includes real terminal interactions and deterministic transaction tests.
+`npm run check:package` installs a tarball outside the checkout, runs the library
+consumer, closed-input process checks and terminal interactions. Conflict tests
+inject filesystem interleavings, including an exclusive-link race, a second real
+setup process under the first process's lock, detected external edits, publication
+failure and partial-folder retry. They do not establish arbitrary-writer safety.
+
+The [concurrency boundary](startup.md#concurrency-and-recovery-boundary) requires
+cooperating setup processes and no external edits during confirmed setup. Stable
+path topology, local filesystem semantics and ordinary process completion are
+assumed. Power loss, hostile filesystem mutation, network filesystems and Windows
+are not verified. A killed process may leave a lock and empty directories.
+The tarball stays private; no registry installation/release, research, continuation,
+SOURCE-01, Lab integration or full #16/#30 completion is claimed.

package/docs/n8r-surface/verification.md

@@ -0,0 +1,117 @@
+# Experimental contract verification record
+
+This record applies the [intent/outcome approach](command-outcomes.md) to the
+library delivered by #15. It records observed library behavior and its limits;
+this historical library record does not verify command or AI research outcomes.
+The later [STARTUP-01 record](startup-verification.md) separately verifies bare startup.
+
+- Date: 4 November 2026.
+- Implementer/verifier: Codex, with a separate read-only agent review of the
+  implementation at `a2dae4d`. Human product acceptance remains separate.
+- Baseline for the final correction: `ee56e45`.
+- Corrected implementation and test revision: `64b8c95`.
+- Environment exercised: macOS ARM64 (`darwin/arm64`); Node.js 22.23.2, 24.22.2
+  and 26.13.0. Other operating systems were not exercised.
+- Distribution: `n8r-surface` version `0.0.0-experimental.1`, local tarball installed
+  into a temporary consumer directory with no checkout-relative imports. The
+  package remains private and unpublished.
+
+## ARRAY-01: a consumer must not silently lose extension data
+
+**State X:** a valid research record contains `['original']` in an extension,
+constructed as an Array subclass with an inherited `toJSON` method returning
+`['replacement']`. Additional cases use inherited `toJSON` and `map` getters on
+custom array prototypes. These values violate the intended plain-data boundary.
+
+**Input Y:** submit the record through the public validation, logical digest and
+JSON/YAML encoding APIs. For encoding, reopen any returned string to inspect its
+actual value. Repeat the encoding rejection check from the installed package.
+
+**Expected Outcome Z:** reject the custom prototype before any inherited method
+or getter runs, leave the caller's original value unchanged, and return no encoded
+artefact or misleading digest. Ordinary arrays must still round trip normally.
+
+**Observed baseline:**
+
+| Operation | Input value | Reopened output | Digest agrees with input? |
+| --- | --- | --- | --- |
+| JSON encode/decode | `original` | `replacement` | No |
+| YAML encode/decode | `original` | `replacement` | No |
+
+The new regression failed against the baseline (22 of 23 tests passed). The
+independently installed package also failed the expected-rejection assertion.
+This confirms an observable data-loss bug, rather than an implementation-style
+preference or an unexercised review suggestion.
+
+**Change:** the portable-value boundary now requires an array's prototype to be
+exactly the ordinary `Array.prototype`, before traversing or serializing it.
+Non-array objects keep their existing plain-object rule.
+
+**Verification and actual result:** the public APIs now report `requires a plain
+array`. Regression assertions observe zero inherited-hook calls and the unchanged
+`original` value. Both installed JSON/YAML encoding paths reject the subclass.
+Existing normal-array, unknown-extension, HTML and graph round trips remain green.
+All 23 tests and the installed consumer check pass on each of the three Node
+versions above.
+
+**Assessment:** passed for this library boundary. It is not a sandbox for arbitrary
+JavaScript execution or proof that the future command can research a repository.
+
+## CONTRACT-01: retain useful, attributable research and selected definitions
+
+**State X:** the frozen [Lumen and Harbor fixtures](../../examples/researcher/README.md)
+include supplied source documents, original and successor HTML records, a manually
+edited pending file and equivalent JSON/YAML selected definitions. They are
+synthetic, authored acceptance fixtures, not outputs of an AI Researcher.
+
+**Input Y:** load the actual fixture bytes through the exported readers, verify
+source hashes and exact research references, validate successor links, and reopen
+both graph encodings. Repeat from assets bundled in the installed tarball.
+
+**Expected and observed Outcome Z:**
+
+| Required outcome | Independent check and observed result |
+| --- | --- |
+| Evidence is attributable to the supplied source snapshots. | Hash original source-file bytes independently; compare with record digests. All match. |
+| Conflicting/unknown facts remain useful. | Read both batch-limit claims (10 and 25), the unknown model version and initial unknown Harbor authentication. All remain explicit. |
+| A manual visible edit cannot silently replace or disappear behind structured data. | The pending HTML is rejected; the reviewed successor loads, records the selected callback decision and points to the intact predecessor. |
+| A second source can add knowledge without losing identity. | Harbor r2 retains its authentication finding ID and original source while adding the second source and supported authentication value. |
+| Selected graph meaning survives conversion. | JSON and YAML reopen to equal values with four nodes, six declared relationships, a shared identity node, a cycle, distinct parallel edges, requirements and exact research revision links. |
+| Installed consumers receive the necessary code and assets. | The temporary consumer imports built exports, reads bundled fixtures/contracts and repeats reference, successor, codec and conflict checks successfully. |
+
+**Assessment:** passed for these frozen examples and supported profile meanings.
+Reference integrity does not verify that arbitrary prose is true, a consumer
+understands an extension or any selected connection actually works.
+
+## Reproduce the supporting checks
+
+From the repository, using a supported Node version:
+
+```sh
+npm ci
+npm test
+npm run check:package
+```
+
+The first command obtains dependencies from npm. The tests and package consumer
+check then work offline; the latter uses the populated dependency cache and removes
+its temporary directory. To use already installed Node executables for the package
+matrix, follow the [contributor instructions](../../CONTRIBUTING.md#researcher-contract-library).
+
+The regression lives in [contracts.test.mjs](../../tests/contracts.test.mjs); the
+independent consumer interaction is [package-smoke.mjs](../../tests/package-smoke.mjs),
+invoked outside the checkout by [check-package.mjs](../../scripts/check-package.mjs).
+The fixture expectations are in [fixtures.test.mjs](../../tests/fixtures.test.mjs).
+These files retain the exact reproducible assertions; no private paths or raw
+machine logs are needed in the public evidence record.
+
+## Product proof still required
+
+The command inventory and State/Input/Outcome method are approved. E2E-01 and
+E2E-02 remain **not attempted**, because discovery, the Researcher instruction
+bundle and runner are not implemented. The first #16 increment separately
+[verifies bare startup](startup-verification.md); status/source/storage behavior
+still needs installed-command evidence. #17 must demonstrate the whole real-runner path,
+human decisions and actual saved/reopened outputs. LibreChat and external skill
+claims need their own actual rehearsals. Lab compatibility needs a named consumer
+trial. None of these claims follows from the passing library checks above.