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

package/docs/n8r-surface/getting-started.md

@@ -0,0 +1,107 @@
+# Create a Surface from saved research
+
+This candidate adds a linked research HTML record and partial Surface JSON to
+the existing Markdown research workflow. Reopen either saved file to revise the pair. The package remains private and unpublished.
+Use Node 22, 24 or 26, Codex CLI **0.166.0**, and an existing ChatGPT sign-in with
+access to `gpt-6-astra`. No API-key billing or model fallback is used.
+
+For isolated checks of both official npm package candidates, use the
+[distribution walkthrough](npm-distribution.md). The global install below uses
+the checkout tarball and replaces the command in your npm global prefix.
+
+## 1. Install
+
+- Open a terminal in this checkout at the reviewed candidate revision and paste:
+
+  ```sh
+  npm ci && npm pack && npm install --global ./n8r-surface-0.1.0-experimental.2.tgz
+  ```
+
+  Expect successful installation and the terminal prompt. Stay in the checkout.
+  If installation fails, stop and report the error.
+
+## 2. Create and save a Surface
+
+Use your existing saved note and its original source. Replace `NOTE` and `SOURCE`
+with their paths (keep quotes). If you have no note, use the optional steps below.
+
+- Paste:
+
+  ```sh
+  n8r-surface reopen "NOTE" --source "SOURCE" --model gpt-6-astra
+  ```
+
+  Type **y** at the transmission prompt. Expect evidence comparisons, a fresh
+  conversation and your retained choices. At `You>`, paste:
+
+  ```text
+  Create a Surface from these notes; show me what is selected and still unknown. Preserve the component IDs, source evidence and my decisions. Prepare the linked research and Surface preview.
+  ```
+
+  Expect a **Validated partial Surface preview** listing components, declared
+  connections, human decisions, requirements, coverage, gaps and evidence.
+- Enter `/save surface`. Expect **Saved and read back** for `research.html` and
+  `surface.json`. Open both: they should match the preview. Copy the JSON path,
+  then enter `/exit`; expect exit 0 and the terminal prompt.
+
+## 3. Reopen and revise
+
+- Paste, replacing `SURFACE_JSON` with the saved JSON path and `SOURCE` with the
+  same source path:
+
+  ```sh
+  n8r-surface reopen "SURFACE_JSON" --source "SOURCE" --model gpt-6-astra
+  ```
+
+  Type **y**. Expect the same component identities and decisions. Ask to change
+  one decision, with your reason, and prepare an updated Surface. For the optional
+  Lumen case below, paste:
+
+  ```text
+  Select external OIDC in the desired composition because this investigation now requires centralized sign-in. This is my selection, not proof of a configured provider. Keep the provider and model unknown, preserve existing IDs and evidence, and prepare the updated Surface preview.
+  ```
+
+- Inspect the preview, enter `/save surface`, then `/exit`. Expect a new numbered
+  pair, exit 0 and the original pair unchanged. Open both revisions and compare
+  component IDs, evidence, the decision and parent references. The new
+  `research.html` path can also be used with the same reopen command.
+
+Report **Pass**, **Fail** or **Blocked**, with the changed decision and unexpected
+message or excerpt. Wording and filenames vary. Lost evidence/IDs/decisions,
+overwrites or a claimed save without files are failures. Keep test pairs or delete
+only their numbered directories afterward; keep your vault, source and earlier work.
+
+`/save` still writes Markdown. `/save surface` needs a current validated preview;
+a later question invalidates the old preview, so request an updated one after a
+correction. Edited HTML or mismatched pair bytes are rejected and preserved; make
+changes conversationally in a new revision. Ctrl-C cancels with exit 130. The
+[maintainer evidence](surface-revisions-verification.md) distinguishes agent
+rehearsal from human acceptance and lists remaining limits.
+
+## Optional: create a research note first
+
+- Paste:
+
+  ```sh
+  n8r-surface
+  n8r-surface discover examples/researcher/sources/lumen-guide.md --model gpt-6-astra
+  ```
+
+  The first command reuses your vault (or asks you to choose/create it once).
+  The second names the fictional source and requests permission to send inspected
+  text to OpenAI. Type **y**; expect the connected model and `You>` prompt.
+- At `You>`, paste this as one line:
+
+  ```text
+  Describe the AI components and connections with stable component IDs and source citations. For this investigation I choose not to use external OIDC: retain that as my decision, not a change to the source. Keep unknowns and useful next steps clear.
+  ```
+
+  Expect a source read and cited findings. The [source](../../examples/researcher/sources/lumen-guide.md)
+  describes configured inference; OIDC is an option, not proof of selected or
+  exercised authentication. Your decision must stay separate from source claims.
+- Enter `/save`. Expect a numbered destination followed by **Saved and read back**,
+  its full path and SHA-256 digest. While waiting, a spinner shows
+  **Preparing note** and elapsed seconds; answers use **Waiting for Codex**.
+  It should stop when the operation finishes or you cancel. Open that file: it should retain component IDs,
+  your OIDC choice, evidence and next steps. Copy its path, then enter `/exit`.
+  Expect exit 0 and the terminal prompt.

package/docs/n8r-surface/host-contract.md

@@ -0,0 +1,176 @@
+# Researcher host contract 0.1
+
+This is the integration boundary for the future shared Researcher instructions,
+not an implemented runner or Lab adapter. It builds on the
+[artefact contracts](contracts.md) and [shared cases](../../examples/researcher/README.md).
+The existing chat harness was the first skill host. The standalone CLI now has a
+bounded conversation adapter with [Markdown save/reopen support](save-reopen-verification.md).
+The current candidate additionally stages and saves one linked structured research/Surface
+pair; [its evidence](surface-revisions-verification.md) bounds that workflow. Lab adaptation remains later work. A Lab is optional, and AI runner selection is
+independent of the destination for results.
+
+## Version negotiation
+
+A host must identify its adapter version, the exact Researcher instruction
+revision, supported artefact contract versions and understood vocabulary/extension
+versions. The bundled #17 skill is version `0.1.8`, with
+[bounded package and behavioral evidence](researcher-skill-verification.md).
+It produces working notes, not validated contract artefacts. Broader host support
+requires the applicable trial; applications consume that revision
+rather than maintaining a separate copy of discovery knowledge.
+
+Reject unsupported core versions before modification. Report unrecognized
+vocabulary/extension meanings while retaining their data. Successful parsing does
+not imply that the host understands or can operate the selected composition.
+Use a separate migration with explicit losses when a host cannot preserve data.
+The original artefact remains recoverable.
+
+The proposed `urn:n8r:researcher:provenance` extension may record the instruction
+revision and adapter version used for a new revision. It must contain no credentials,
+local paths or copied chat history. Until #17 implements it, this is a reserved
+extension convention rather than a required field or proof of AI execution.
+
+## Capabilities supplied by a host
+
+The following operations specify behavior and inputs/outputs, not API/MCP method
+names. A host can implement them as local functions, attachment tools or application
+services. Missing capabilities must be explicit; the core must not fabricate
+access or a successful save.
+
+The Researcher's primary result is an AI Surface graph, not an application-wide
+configuration inventory. Source access includes user-selected code, documents,
+websites, prior research/definitions and permitted live observations. The
+[shared discovery guide](../../plugins/n8r-surface/skills/research/references/discovery-map.md)
+defines discover, continue and reconcile behavior across these combinations.
+Product libraries provide reusable navigation/evidence where available; no Lab
+or registry connection is required or implied.
+
+| Capability | Input | Result and required behavior |
+| --- | --- | --- |
+| Describe capabilities | No source inspection | Versions, available operations, bounded sizes, inference destination and save/download mode. |
+| Establish source scope | Explicit supplied directory/file/attachment selection | Opaque scope ID and allowed material; no ancestor traversal or implicit corpus scan. |
+| List/read source | Scope ID, relative reference, requested range | Text, exact source/version/digest, inspected range and excluded/unreadable/truncated coverage. No source execution. |
+| Find related knowledge | Explicitly available library and product/source scope | Applicable guides, research and definitions with identity/revision/coverage; no implicit scan or union of different deployment selections. |
+| Read web/live evidence | Selected URL/system/environment and graph question | Available connector/API/browser/computer observations with location, time and nonsecret results. Host-supported human sign-in, read-only inspection, no credential copying or bypass of denied access. |
+| Invoke inference | Selected runner/model, instructions, bounded conversation/tool outputs | Response/tool proposals or explicit unavailable/error; no silent account/provider fallback. |
+| Ask human | Consequential question with current evidence/options | Answer, deferred answer or unavailable interaction; unresolved work stays in the record. |
+| Read artefact | Explicit artefact/revision selection | Original bytes, parsed contract status and exact byte-conflict token; do not render unvalidated imported HTML. |
+| Create artefact | Valid new artefact and explicit destination | Created identity/revision and actual location/download, or conflict/error; never overwrite an existing identity silently. |
+| Revise artefact | Proposed successor and expected byte token | Recheck current bytes, validate parent, retain previous bytes and commit atomically; reject conflicts. |
+| Continue | Accepted record plus newly established source access | Preserve IDs, findings, decisions, questions and extensions; record new evidence in a successor. |
+| Export selection | Reviewed selected definition and encoding | JSON/YAML preserving supported meaning, or explicit rejection; no implicit deployment or publication. |
+
+Reading is not permission to upload. Before inference, the host identifies the
+provider and source transmission scope and obtains the user's authorization for
+that discovery session. The implemented bare-startup overview does not inspect or transmit sources;
+future source selection must have a specified scope. No status subcommand is planned.
+The runner sees only authorized source extracts and context selected by the host;
+source instructions are data, and tool arguments remain subject to deterministic
+path, version, size and operation checks.
+
+Live inspection uses existing host capabilities; this contract adds no browser,
+admin client or runner. Inspect enablement and connection targets needed by the
+graph, not all settings. The user completes private authentication directly.
+Stored configuration, observed effective configuration, reachability and exercised
+behavior remain separate. Record access/identity limits and sanitized evidence;
+do not manufacture a source digest when the host provides no stable source bytes.
+An authorized settings read does not authorize a configuration change or a
+connection test. Document each real host path before claiming it was verified.
+
+## Continuation and persistence
+
+The current standalone increment uses numbered Markdown working notes and an
+experimental host metadata footer. It requires `/save`, preserves predecessor
+bytes, and reacquires explicit source/transmission permission on `reopen`.
+This is a bounded implementation of working-note continuity, not the structured
+HTML/Surface contract below. See [SAVE-01](command-outcomes.md#save-01-save-reopen-and-continue).
+
+A portable continuation needs the current accepted HTML record, exact referenced
+source identities/revisions, and the intended output or selected definition.
+The record carries inspected coverage, findings, alternatives, human decisions,
+notes and open questions. A new host must reacquire actual source access; a saved
+source locator or prior conversation does not grant it.
+
+A host unable to read a referenced source must retain its evidence and mark the
+new inspection as unavailable. It cannot claim to have rechecked that evidence.
+A host unable to persist returns downloadable artefacts and says so. It must not
+claim that they were saved to a corpus or Lab.
+
+Use byte hashes for optimistic concurrency, including edits that leave logical
+data unchanged. Parent logical digests bind the accepted revision's meaning.
+Keep both the edited bytes and accepted predecessor during reconciliation. A
+successful write reports the actual revision/location; a failed or interrupted
+write must leave recoverable work. The local persistence implementation is #16.
+
+A host can have a mutable draft and deliberate named baselines in addition to
+artefact snapshots. It must map these explicitly: an artefact snapshot is not
+necessarily a product release or named Surface version. Import identity collisions
+require exact-match reuse or an explicit fork/migration; do not merge by label.
+
+## Candidate structured pair host
+
+The restricted `surface_draft` tool stages content in memory. The host fills
+revision envelopes and exact research references, validates both artefacts and
+shows a deterministic preview. `/save surface` publishes exactly that preview as
+`research.html`, `surface.json` and `manifest.json` in a new numbered directory
+under `surfaces/<source-slug>/`. The manifest is host storage/provenance metadata,
+not a model contract. Its hashes detect byte edits; they do not authenticate authors.
+
+Either saved member reopens the pair after validation and renewed transmission
+consent. The complete context is bounded to 512 KiB independently of individual
+file limits. Original notes and accepted pair revisions remain unchanged. Source
+availability comparisons retain historical evidence. Manual HTML/data edits fail
+closed; this increment does not implement automatic reconciliation or arbitrary
+multi-record imports. Directory topology must remain stable during synchronous
+operations. See [SURFACE-01](command-outcomes.md#surface-01-generate-save-and-revise-a-partial-surface).
+
+## Lab requirements review
+
+The #15 review compared this boundary with the separate application's relevant
+saved-definition, discovery, revision and import/continuation requirements.
+This public report records alignment and integration obligations only; private
+application prompts, code, operational data and internal source locations are
+not reproduced. No application implementation or compatibility trial was run.
+
+| Requirement | Contract decision | Later consumer work or gap |
+| --- | --- | --- |
+| Offline saved work independent of equipment | Research and selected definitions need no Lab or running target. | Adapt application storage and selection without applying setup. |
+| Explicit context/ownership | Artefact IDs carry no authority to create/configure Lab resources. | Map application ownership explicitly; do not infer it from graph containment or rewrite this model's Lab/Experiment semantics. |
+| Sources and attachments | Opaque scopes plus versioned evidence; portable locators grant no access. | Supply attachment/source adapters and permission checks. |
+| Human-guided research | Decisions/questions are durable; unsupported interaction remains visible. | Implement session questions and compare behavior on shared cases. |
+| Stable identity and immutable evidence | Exact revisions/digests, stable finding/node/edge IDs, separate runtime evidence. | Map local snapshot and deliberate version labels; retain prior Run references. |
+| Partial import and continuation | Unknowns/conflicts/opaque extensions are preserved; no operational readiness claim. | Build an importer that previews limitations and rejects unsupported loss. |
+| Reuse of one Researcher core | Version negotiation includes instruction and artefact versions. | Consume #17's identified instruction revision and run both discovery and import cases. |
+
+The application may use different persistence and ownership conventions. This
+profile describes component graphs. The current model has Lab → Experiment →
+Setup ownership: the Experiment requests setup directly from its Lab, which owns
+resource configuration and local bindings. Historical ownership records remain
+historical. Consumer lifecycle/authority mapping remains an explicit integration
+obligation, not something passing JSON/YAML tests resolves. See the proposed
+[recreation handoff](recreation-handoff.md).
+
+## Acceptance for later adapters
+
+Use the [command outcome specification](command-outcomes.md) to define initial
+state, actual human interaction, state changes and independent readback. The
+cases below must be exercised through the relevant host, not fulfilled by the
+developing agent outside it. The installed CLI's complete path is E2E-01;
+LibreChat requires its own E2E-02 rehearsal before a product-support claim.
+
+1. Research Lumen and Harbor separately from the supplied sources, keeping the
+   10/25 conflict and unknown authentication/model facts.
+2. Ask the human about selection; do not turn every supported option into an edge.
+3. Import the incomplete Harbor r1 record without inventing authentication or
+   requiring a deployed system. Establish access to the second source and continue
+   the same finding into a new revision.
+4. Detect the edited Lumen HTML, preserve it, resolve the human correction and
+   produce a successor without changing the old record or losing extensions.
+5. Produce the selected graph, retaining shared components, cycles, parallel edges,
+   requirement references, decisions and exact research revision links.
+6. Import/continue the result in a named Lab version and document supported meanings,
+   unsupported data and any losses. Compare facts and decisions, not prose wording.
+
+Steps 1–5 require real runner/harness trials in #17 beyond #15's deterministic
+fixtures. Step 6 is later application work. Until those trials run, alignment is
+a design review and byte/value checks are only contract verification.

package/docs/n8r-surface/implementation-decisions.md

@@ -0,0 +1,96 @@
+# Initial implementation decisions
+
+These choices complete the remaining implementation decisions for
+[issue #15](https://github.com/injectionator/n8r-surface/issues/15). They are
+maintainer-reviewable implementation choices within the approved design, not
+claims that the CLI or runner has shipped.
+
+## Runtime and distribution
+
+Use TypeScript compiled to ESM JavaScript, npm with a committed lockfile, and the
+built-in Node test runner. The initial supported majors are **Node.js 22, 24 and
+26**. Test the current patch of each supported major before a release. Odd-numbered
+majors and Bun-only execution are not part of the initial support promise. Revisit
+22 before its scheduled end of support. The official
+[Node release schedule](https://github.com/nodejs/Release/blob/main/schedule.json)
+lists 22/24/26 support windows through April 2027/2028/2029 respectively (checked
+4 November 2026).
+
+Use **`@n8r/surface`** as the preferred npm package/library import and
+**`n8r-surface`** as the supported alternative, both exposing `n8r-surface`.
+This supersedes the unscoped-first/fallback decision under
+[issue #27](https://github.com/injectionator/n8r-surface/issues/27).
+Generate both from one build with matching payloads and version. The
+[distribution candidate procedure](npm-distribution.md) preserves `private: true`
+by default. The maintainer confirmed `0.1.0-experimental.2` and authorized
+publication; explicit `--publishable` preparation creates fresh public archives.
+The [first-release workflow](npm-release.md) retains both archives before
+publication, uses stage-only token bootstrap with provenance and maintainer 2FA approval, and requires
+independent registry verification. Merge and account prerequisites remain. Registry
+lookups do not reserve names or establish publishing rights. The approved
+[package version policy](versioning.md) makes the root manifest authoritative,
+derives CLI output from the installed manifest and verifies retained artifact
+identity against the exact Git tag, commit and GitHub Release metadata.
+
+Issue #15 ships a library, built declarations, contracts and synthetic assets.
+The first #16 increment adds a `bin` entry for bare startup only; see its
+[settings, parser and inspection decisions](startup.md). It must be exercised
+through the installed tarball outside the source checkout. #17 adds the versioned
+Researcher instructions. Runtime consumers do not need TypeScript or Bun.
+
+Use `yaml` 2.9.1 as the single runtime dependency; its parsed nodes allow rejection
+of tags, aliases, duplicate keys and unsupported numeric forms before conversion.
+See its [version 2 documentation](https://eemeli.org/yaml/) and the locked version
+in [package-lock.json](../../package-lock.json). TypeScript 6.0.3 and Node typings
+22.20.5 are development dependencies. The bounded field/reference checker and
+HTML renderer need no framework, browser runtime or general ontology dependency.
+
+## First CLI AI runner
+
+The user revised the order on 4 November 2026: use the Researcher as a
+[shareable skill](researcher-skill.md) in Codex/ChatGPT first, adapt it in n8r-labs
+second, then complete the standalone command. The current host supplies inference,
+file access, search and conversation. The skill does not configure a provider,
+extract credentials, or connect a second AI account.
+
+For the later CLI, select installed Codex with ChatGPT sign-in. This supersedes
+the earlier direct OpenAI Responses API adapter decision from #15. The
+[official authentication guide](https://learn.chatgpt.com/docs/auth) distinguishes
+ChatGPT subscription access from separately billed API-key access. The
+[SDK guide](https://learn.chatgpt.com/docs/codex-sdk) documents local-agent control
+and directs interactive clients to app-server. Reviewed 4 November 2026.
+
+Before implementing the CLI integration, verify a supported interface against its
+actual installed version, preserve user permissions and source scope, and record
+real tool events, human continuation and saved-output readback. Do not borrow
+application tokens, silently switch accounts/providers or fall back to API billing.
+Source transmission and a result destination remain separate decisions. A Lab is
+optional. No standalone runner or Lab compatibility is established by installing
+the skill. No API key was read or model API invoked by #15's contract tests.
+
+## HTML ownership and numeric scope
+
+The embedded data owns the record and the whole readable HTML is its deterministic
+projection. The reader rejects divergence, including benign reformatting, so human
+edits cannot disappear in a later save. Reviewed corrections become successors;
+a rich editor and automatic merging are deferred.
+
+Use only safe integer numbers in the initial portable data subset. Decimal and
+large quantities require explicit strings/units. This costs convenience but makes
+lossy numeric conversion an explicit error instead of an undetected change to
+evidence or identity. Expanding either HTML editing or numeric support requires
+versioned tests and a documented migration.
+
+## Verification boundary
+
+`npm test` checks this profile, its source/reference fixtures and HTML/data
+consistency. `npm run check:package` packs and installs into a temporary directory,
+then imports built exports and bundled fixtures with no checkout-relative imports.
+Prepare npm's local dependency cache with `npm ci` and `npm cache add yaml@2.9.1`:
+the latter also fetches registry metadata needed on a fresh machine. The installer
+then runs with `--offline --ignore-scripts`. Temporary files are removed after the
+check. See [contributor commands](../../CONTRIBUTING.md#researcher-contract-library).
+
+These checks do not prove an AI can research LibreChat, a consumer understands an
+extension, a Lab can import the format, or a selected composition runs. Keep those
+later tests separate and name the actual runner/consumer versions when they run.

package/docs/n8r-surface/npm-distribution.md

@@ -0,0 +1,137 @@
+# Dual npm distribution candidates
+
+Issue [#27](https://github.com/injectionator/n8r-surface/issues/27) selects
+`@n8r/surface` as the preferred package and library import, with `n8r-surface` as
+an official alternative. Both expose the `n8r-surface` executable. Install one
+route per environment because they provide the same command name.
+
+This increment prepares **private local candidates**, not a published release.
+The root manifest and default generated manifests retain `private: true`. The
+maintainer selected `0.1.0-experimental.2` and authorized publication. Explicit
+`--publishable` preparation removes the generated guards only; see the
+[first-release procedure](npm-release.md). Registry installation remains unproved.
+
+## Build and inspect candidates
+
+From the checkout root, with Node 22, 24 or 26, npm, Git, POSIX `tar` and Python 3.9+:
+
+```sh
+npm ci
+npm cache add yaml@2.9.1
+npm test
+npm run check:package
+candidate_run=$(mktemp -d)
+npm run pack:candidates -- "$candidate_run/packages"
+cat "$candidate_run/packages/candidates.json"
+```
+
+Dependency preparation uses the network. Candidate packing and consumer checks
+use local files/cache with lifecycle scripts disabled. `pack:candidates` builds
+once into a fresh temporary directory (excluding stale checkout `dist/` files),
+captures npm's source payload once, and generates both packages from that
+payload. Development scripts/dependencies are removed from both manifests;
+only `name` differs between them. Versions, engines, licenses, dependencies,
+exports, executable and asset bytes match. Existing destinations are refused.
+A failed run may leave an incomplete destination; use a new directory on retry.
+
+Both tarballs are named `n8r-surface-0.1.0-experimental.2.tgz`, so they live in
+separate `scoped/` and `unscoped/` directories. `candidates.json` records their
+relative paths, SHA-256 digests, version, source HEAD and dirty status. This is
+local build evidence, not registry provenance. Each entry also names a unique
+`releaseAsset` for later GitHub upload; see the [version and release policy](versioning.md). Release evidence must use a clean
+reviewed checkout; a dirty report does not identify all inputs by commit alone.
+
+`check:package` installs each candidate in a separate temporary consumer outside
+the checkout, imports its own package name, checks installed identity and assets,
+and runs the startup/discovery terminal rehearsals. Temporary homes isolate
+settings and vaults. Discovery uses a scripted offline fixture, not real inference.
+Existing [real Codex evidence](surface-revisions-verification.md) remains separate.
+
+## Human verification
+
+Maintainer preparation: supply this checkout and the candidate build above.
+Keep the same terminal so `candidate_run` remains set. No global installation,
+Codex sign-in or existing vault is needed for this distribution check.
+
+- [ ] Install the preferred candidate into an isolated consumer and inspect it:
+
+  ```sh
+  mkdir "$candidate_run/consumer"
+  cd "$candidate_run/consumer"
+  npm install --offline --ignore-scripts --no-audit --no-fund --package-lock=false "$candidate_run/packages/scoped/n8r-surface-0.1.0-experimental.2.tgz"
+  node --input-type=module -e 'import {decode} from "@n8r/surface"; console.log(typeof decode)'
+  ./node_modules/.bin/n8r-surface --version
+  ```
+
+  Expect successful installation, `function`, then
+  `n8r-surface 0.1.0-experimental.2`; each exits 0.
+- [ ] Run bare startup with a fresh isolated home and closed input:
+
+  ```sh
+  mkdir "$candidate_run/home"
+  HOME="$candidate_run/home" USERPROFILE="$candidate_run/home" ./node_modules/.bin/n8r-surface </dev/null
+  echo "$?"
+  ls -A "$candidate_run/home"
+  ```
+
+  Expect the overview, `Vault setup required; run n8r-surface in an interactive
+  terminal.`, exit **1**, and no home entries. This is the expected unconfigured
+  path. No normal settings or vault should change.
+- [ ] Repeat the first two tasks in a new `consumer-alternative` directory,
+  using the `unscoped/` tarball, import `"n8r-surface"` and a new `home-alternative`.
+  Expect identical command behavior and exit codes.
+- [ ] Report **Pass / Fail / Blocked**, Node/npm versions, both installed names,
+  and unexpected output. Missing imports/assets, a different version or writes
+  during closed-input startup are failures. Return the candidate report too.
+  After inspection, leave the consumer directory and remove only the temporary
+  directory created by `mktemp`; keep any evidence you need first.
+
+## Registry routes after a separately approved release
+
+These are planned routes; do not use them as evidence of a release today.
+Replace `VERSION` with the same verified published version for either route:
+
+```sh
+npm install --global @n8r/surface@VERSION
+# Alternative in a separate environment:
+npm install --global n8r-surface@VERSION
+# Explicit executable selection for a one-off invocation:
+npm exec --package=@n8r/surface@VERSION -- n8r-surface --version
+npm exec --package=n8r-surface@VERSION -- n8r-surface --version
+```
+
+Library users install the chosen exact version locally and import from
+`@n8r/surface` (preferred) or `n8r-surface`. Source links must resolve to
+[the official repository](https://github.com/injectionator/n8r-surface).
+After publication, check each registry manifest's version, repository and
+`dist.integrity`, verify its provenance against the reviewed source revision,
+and repeat isolated installs and the command/asset readback for both names.
+Matching repository text alone does not prove origin.
+
+## Remaining release decisions and recovery
+
+On 5 November 2026, public metadata lookups returned E404 for both names and
+`npm whoami --registry=https://registry.npmjs.org` returned E401. This establishes
+neither name availability nor publishing rights. An authorized maintainer must
+establish the npm identity, `n8r` organization/team rights and unscoped ownership.
+Subsequent authenticated readback identified the intended npm account and its
+`n8r` owner role; new-package publication rights still require an actual publish.
+
+The approved first version is `0.1.0-experimental.2`. Review the release
+workflow before merging; account configuration and registry verification remain. Prefer trusted publishing for both packages
+from the public repository on GitHub-hosted runners. npm documents Node 22.14+
+and npm 11.5.1+ for trusted publishing and automatic provenance for public packages
+from public repositories. Configure and verify each package's trust relationship;
+local tarball tests cannot do this. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/)
+(checked 5 November 2026). The manual workflow and its remaining account prerequisites are described in
+[the first-release procedure](npm-release.md).
+
+Use the same version and an explicit `experimental` distribution tag for both
+packages; do not promote `latest` implicitly. Record each package's publication,
+integrity and verification separately. If only one publishes, report the release
+as incomplete and retain the exact approved build. Inspect existing registry
+bytes before retrying the missing package; never replace or rebuild a published
+version under an assumption of equivalence. Align tags only after both packages
+pass registry readback. A mismatching published payload needs a new approved
+version for both names. Publication, registry rehearsals, provenance verification
+and human acceptance remain open under #27.