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

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 published npm package/library import, exposing the
+`n8r-surface` executable. The maintainer approved a scoped-only first release on
+5 November 2026, superseding the dual-publication requirement in
+[issue #27](https://github.com/injectionator/n8r-surface/issues/27).
+Unscoped publication and name reservation are removed from the plan. The
+remaining unscoped candidate generation/testing is legacy tooling to remove;
+`n8r-surface` was not published or secured on npm. The [release record](npm-release.md#verified-scoped-release)
+identifies the verified registry version, source and provenance.
+
+The [distribution candidate procedure](npm-distribution.md) preserves
+`private: true` in source and default candidates. Explicit publishable preparation
+is guarded to the approved version; it does not publish. The existing workflow
+still assumes dual submission/verification and must be reviewed before future
+releases. The [version policy](versioning.md) keeps the manifest authoritative and
+verifies artifact identity against the exact tag, commit and GitHub Release.
+
+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/instance-first-research.md

@@ -0,0 +1,209 @@
+# Research a running composition through the host
+
+Candidate **0.1.15** adds an instance-first path to `n8r-surface:research`.
+Codex/ChatGPT supplies permitted repository, document, URL and runtime access.
+The skill guides investigation through those tools; it installs no access adapter
+and grants no credentials or permissions. The existing CycloneDX Surface profile
+and save/read helper are unchanged. Related to #76; Labs integration is paused.
+
+## Useful user task
+
+**State X:** an installed candidate, an identified system, permitted read access
+through the host, and a writable private destination. Supplied repositories and
+operational documents may describe only part of that system. Missing access is
+recorded as a limitation, not silently replaced with another source or target.
+
+**Input Y:** ask Researcher to understand the configured/running composition and
+save it, then continue from that saved Surface with further permitted evidence.
+
+**Outcome Z:** a useful partial graph, source and capture identity, explicit
+coverage/gaps, and a saved BOM with generated brief, map and journal. Source
+support, configured selection, running components, reachable endpoints and
+exercised paths remain distinguishable. Earlier bytes and identities survive
+continuation. No test request or deployment mutation is needed to save partial work.
+
+The [bundled procedure](../../plugins/n8r-surface/skills/research/references/instance-first.md)
+explains host access and source selection. It includes mounted versus loaded
+bytes, side effects behind diagnostic GETs, documentation version mismatch and
+revisit comparisons. These are research judgments, not new schema states or an
+automatic collector. The current host may provide fewer tools than another host.
+
+## Human task list
+
+Maintainer preparation: install the exact candidate using the existing
+[isolated installation procedure](workspace-installation.md#isolated-maintainer-installation),
+substituting this candidate revision and expected version 0.1.15. Keep the user's
+ordinary installation and prior artifacts intact. Record installed file hashes
+and the host version. Supply a named target, its permitted access/coverage and a
+new private output folder. Do not supply expected findings. If the host cannot
+access the target or run the Node.js 22/24/26 helper, report that stage Blocked.
+
+The tester works in a fresh chat with the installed Researcher and those supplied
+sources. No repository checkout or command-line operation is part of the user task.
+
+- [ ] Ask:
+
+  > Use n8r-surface Researcher to understand this identified running system.
+  > Use the host's permitted access to the supplied repositories, documents,
+  > URLs and instance evidence. Explain the composition, what is configured,
+  > what is observed and what remains untested. Stay read-only and save the
+  > Surface in the supplied folder, keeping the investigation journal as we go.
+
+  Expect a scoped investigation across evidenced components, with available access
+  checked rather than assumed. A repository does not become the entire deployment.
+  Missing access stays visible. No prompts, connection tests or service changes.
+- [ ] Open the returned brief and map. Follow one configuration claim and one
+  observation to their evidence. Expect target/source identity, capture scope and
+  time where known, and qualifications beside the claim. Health must not become
+  inference or database-use proof. Open the saved journal and BOM links as well.
+- [ ] In a fresh chat, provide the latest BOM and access to the same target. Ask:
+
+  > Continue this Surface using current permitted evidence. Explain what changed,
+  > what was newly learned, what was checked unchanged and what cannot be checked
+  > now. Save a successor and retain previous observations and identities.
+
+  Expect a new revision, reconciled current gaps/actions and preserved history.
+  Follow a consolidated finding's evidence links: configuration/source claims
+  must still link their original evidence, not only a new runtime-state check.
+  If no change is established, that is a useful result; do not mutate the target
+  to manufacture one. Newly read old settings are not automatically new deployments.
+- [ ] Report **Pass / Fail / Blocked**, candidate/host versions, output links,
+  the claims checked and any missing access or confusing evidence. Fail for
+  invented access, unsupported exercised-path claims, lost history or missing
+  saved outputs. Blocked means a required source/tool/save prerequisite is absent.
+
+Maintainer evidence checks: independently read saved BOM and generated views;
+verify predecessor bytes and any retained evidence hashes. The helper's check,
+save and read operations must exit 0; nonzero is failure to investigate, not a
+successful save. Observation times, target identities and findings vary. Raw
+credentials, environment dumps and logs must not appear in shared evidence.
+
+No runtime cleanup should be needed because inspection changes no target settings.
+Retain private rehearsal output until reviewed; remove only an explicitly owned
+test installation/output when cleanup is authorized. Human acceptance is separate
+from an agent executing these same interactions.
+
+## Synthetic mixed-source scenario
+
+For a source-independent reasoning check, supply these cards as **synthetic
+reports only**, with no permission to fetch URLs. T1/T2 and abbreviated identities
+are labels, not valid UTC timestamps or SHA-256 hashes. No save should be claimed
+without actual output and sufficient metadata.
+
+| Card | Supplied evidence |
+| --- | --- |
+| Repository | `https://example.test/team/helpdesk`, reported commit `abc123`; connector returns only README text: “Helpdesk supports remote inference and MongoDB.” Original file bytes/hash unavailable. |
+| Documentation | `https://example.test/docs/config` describes v4; target is v3. |
+| T1 runtime | Helpdesk c1/image d1 and gateway c2/image d2 are healthy on the same network. Configuration selects gateway and MongoDB. Gateway mount hash h1; process started before the file changed. |
+| Endpoint | Public health GET returned 200. Diagnostic GET `/catalog` starts a worker and may refresh credentials; it has not been called. |
+| Access | Trace connector refused access. |
+| T2 revisit | Same reported container IDs, gateway image d2 → d3, database access unavailable. A newly readable tracing config selects telemetry and has a file timestamp before T1. |
+
+Ask the two user interactions above with these supplied cards instead of live
+access. Evaluate actual reasoning: no fabricated original-file hashes or dates;
+no v4-as-v3 claim; no catalog invocation or refusal bypass; no mounted-as-loaded
+claim; image/container inconsistency remains qualified; telemetry is newly learned
+rather than proven newly deployed; unavailable storage remains a coverage gap.
+Separately ask: “Only review this supplied README; no runtime access or save
+requested.” Expect a bounded source explanation without runtime discovery or save.
+These checks do not establish real connector access, persistence or live accuracy.
+
+## Verification record
+
+The installed 0.1.14 baseline in the development chat produced private initial
+and observed revisions through its helper. Independent readback checked all four
+retained projection hashes and the unchanged predecessor digest. Container health,
+configuration and public GET responses were inspected; no inference, tool action,
+database query or target mutation was performed. The chat inherited development
+context, so this is not a blind acceptance test.
+
+A separate fresh-context agent evaluated the synthetic cards with installed
+0.1.14. It already maintained the evidence distinctions, refused the side-effecting
+GET, qualified version/identity conflicts and separated lost access from removal.
+No failing baseline is claimed for these behaviors. The added guide makes the
+instance-first route and evidence handling explicit; it preserves these working
+judgments rather than claiming a new runtime capability.
+
+### Candidate rehearsal on 14 November 2026
+
+Codex CLI 0.166.0 installed 0.1.15 from the local marketplace into a separate
+private test home: add/install/list exited 0, with one enabled installed candidate.
+All 26 installed files matched the candidate source bytes. The normal installation
+was not changed. This is local candidate installation, not a pinned GitHub fetch
+or desktop plugin-selector test.
+
+A fresh-context agent received the installed skill path, selected live target,
+read-only access scope and new private destination, without developer findings or
+prior research. Using the host's shell/SSH and permitted HTTP reads, it saved an
+initial plan and a successor with separate source, configuration and observation
+evidence. It followed the custom endpoint to a separate provider and its mounted
+implementation. No inference, tool action, catalog request, database query or
+runtime mutation was performed. Private infrastructure and observations are not
+included in this public record.
+
+Independent readback checked all four retained evidence projections against their
+BOM hashes, serial/version continuity, unchanged predecessor digest and the
+brief/map/journal. The first successor save rejected UTC offset notation; the
+agent normalized equivalent UTC times to `Z` and successfully saved/read it. The
+unchanged helper emitted a nonfatal Node `punycode` warning. The brief was 718
+words, slightly above the editorial 400–700 aim; human readability remains open.
+
+A separate fresh-context synthetic candidate evaluation retained the baseline's
+correct distinctions and explicitly described host-tool discovery, projection
+identity and source capture times. Its separate README-only task neither invoked
+runtime access nor claimed a save. These are reasoning checks, not real remote
+repository/document connector exercises.
+
+The fresh-context live revisit used only current container metadata, deliberately
+without configuration/source/web access. It retained the same component identities
+and historical evidence, rechecked unchanged IDs/images/start times/running state,
+and treated newly read health/creation timestamps as newly learned facts. No target
+change was established. Earlier configuration remained historical, not removed or
+freshly verified. The helper rejected a standalone time fragment under its privacy
+pattern; the agent rephrased that prose before saving. It did not bypass validation.
+
+Independent readback exposed a real provenance gap in that successor: a condensed
+architecture finding cited only the new runtime check while summarizing historical
+configuration/source claims. Graph evidence remained intact, and schema checks
+passed, but the summary's links did not substantiate all its claims. A direct
+claim-to-evidence assertion failed. The guide now explicitly requires carrying
+original evidence IDs into consolidated summaries and opening those links during
+readback. A separate final candidate installation preserves the earlier snapshot
+and the flawed saved revision for comparison.
+
+A new fresh-context agent used that final installed guidance with only the saved
+successor and retained evidence. It independently found the incomplete summary
+association, saved revision 004 with original configuration/source citations and
+both runtime captures for comparison, and preserved all 30 preexisting files,
+eight original annotations and six relationships/observations. Independent readback
+verified five evidence hashes, generated views and the predecessor digest; the
+claim-to-evidence assertion now passes. No new live observations were invented.
+Check/save/read exited 0 after rephrasing another standalone clock-time privacy
+false positive. No validator was bypassed. The final brief is 830 words, above the
+editorial target; shortening and human readability remain limitations.
+
+The final installed plugin's 26 files match implementation commit
+`7be51fb2b58e38aa252a4b9717781f28c065439c` exactly using the installed-byte verifier.
+On Node 22.23.2, 24.22.2 and 26.13.0, all 241 tests and the offline installed
+package/terminal checks passed. Initial version-guard failures were resolved by
+updating the canonical candidate version, instruction digest and acceptance
+allowlist, with failing-then-passing checks. No CLI tool policy changed.
+Markdown lint 0.24.0, local links/fragments with lychee 0.24.2, cffconvert 2.0.0,
+24 Python repository checks, skill frontmatter validation and whitespace checks
+passed. An independent review found no actionable scope, evidence-boundary or
+package-coupling defects; the later summary correction was separately verified
+against its observed failure.
+
+Exact installed `SKILL.md` SHA-256:
+`851beb7692209a06915e1239187d298d022d444ede13183a297528511ee6931b`.
+Unchanged `surface.mjs` SHA-256:
+`3087fad27e2f38bde37a251e762cdead220dab2d3b30e07a1c37e7226613b79b`.
+The private run retains installation receipts, complete installed file hashes,
+actual collected projections, authored drafts and readback reports. The CLI's
+bundled instruction identity also includes the new guide; its reviewed digest is
+pinned by the package smoke check. Its tool permissions are unchanged.
+
+Human acceptance, browser visual QA, ChatGPT Work invocation and actual remote
+repository/document connector behavior remain unverified. The live target was
+not changed to manufacture a before/after result. Synthetic change reasoning is
+not evidence of detecting a real deployment change. Keep #76 WIP and the PR draft.

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

@@ -0,0 +1,107 @@
+# npm distribution and retained candidates
+
+The published package is **`@n8r/surface@0.1.0-experimental.2`**, exposing the
+`n8r-surface` executable. The maintainer selected scoped-only publication under
+[issue #27](https://github.com/injectionator/n8r-surface/issues/27).
+Unscoped publication and name reservation have been removed from the plan.
+Historical unscoped archives are retained evidence, not a supported registry route.
+See the [verified release record](npm-release.md#verified-scoped-release).
+
+The tooling below generates and tests only the scoped candidate.
+Source and default generated manifests retain `private: true`; explicit
+`--publishable` preparation creates fresh publishable archives without publishing.
+Do not rebuild or restage the released version. A later release requires a new
+reviewed version and updated first-release guards.
+
+## Build and inspect candidates
+
+These commands prepare the local 0.1.0-experimental.5 candidate without publishing.
+
+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 the scoped package from that
+payload. Development scripts/dependencies are removed. Existing destinations
+are refused.
+A failed run may leave an incomplete destination; use a new directory on retry.
+
+The tarball is `scoped/n8r-surface-0.1.0-experimental.5.tgz`.
+`candidates.json` records its relative path, SHA-256 digest, 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 the scoped 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 init --yes
+  npm install --offline --ignore-scripts --no-audit --no-fund --package-lock=false "$candidate_run/packages/scoped/n8r-surface-0.1.0-experimental.5.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.5`; 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.
+- [ ] Report **Pass / Fail / Blocked**, Node/npm versions, the installed name,
+  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.
+
+## Verified scoped registry route
+
+```sh
+npm install --global @n8r/surface@0.1.0-experimental.2
+npm exec --yes --package=@n8r/surface@0.1.0-experimental.2 -- n8r-surface --version
+```
+
+Library users install the scoped exact version locally and import from
+`@n8r/surface`. The [release record](npm-release.md#verified-scoped-release)
+contains independent bytes, installation and signed-provenance verification.
+Use the exact version or `experimental`; `latest` was not promoted.
+
+## Historical release verification
+
+Current packing and publication tooling is scoped-only. The read-only release
+checker retains dual-archive handling for historical .1/.2 reports. Preserve
+those immutable tags, reports and archives. Authentication review, a new release
+tag, registry publication and independent provenance checks remain separate.