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

package/docs/n8r-surface/skill-usefulness-verification.md

@@ -0,0 +1,135 @@
+# Installed Surface skill: two-product usefulness check
+
+Related to [#52](https://github.com/injectionator/n8r-surface/issues/52).
+This checks the standalone Surface skill before CLI integration. The products
+are research subjects, not new integrations or deployment targets.
+
+## Run identity and scope
+
+- Date: 8 November 2026.
+- Skill: 0.1.11, source commit `8e4cb3ade3c9e5ca59ab0a37838ccaf874b7fc42`
+  from PR #54. An isolated Codex marketplace installation matched every tracked
+  plugin file to that commit before research.
+- Host: Codex CLI 0.166.0 app-server, ChatGPT sign-in, configured model
+  `gpt-6-astra`, Node 26.13.0. Fresh ephemeral sessions had no prior turns;
+  previous-thread and receipt access were independently denied.
+- Source access: pinned public file copies, read-only research; no source
+  execution, additional fetches or deployment inspection. Each product was
+  bounded to model API, storage and identity connections.
+- Configuration and reviewer inputs were fictional test fixtures. They do not
+  describe a real deployment or constitute human acceptance.
+
+| Product | Pinned source | Files supplied |
+| --- | --- | --- |
+| LibreChat | [f4154b6](https://github.com/danny-avila/LibreChat/tree/f4154b649efa37e1345ccc517a4d8d1ed2178c82) | README, database connection, OpenID strategy |
+| Open WebUI | [b7a005e](https://github.com/open-webui/open-webui/tree/b7a005e5a5c0c0d869f2aebf4b8f051c5fb37245) | README, SQL database layer, OAuth implementation, model API router |
+
+## Interaction exercised
+
+1. Ask the installed Researcher which model API, storage and identity connections
+   a reviewer should examine; save a checked Capability with source hashes and
+   bounded evidence. Do not infer selected targets from supported options.
+2. Supply a fictional configuration declaring Model Service A, Database Service A
+   and Identity Service A. Permit only six named nonsecret fields to be projected
+   from a fixture containing synthetic sensitive sentinels. Supply a second
+   same-revision handover note declaring Identity Service B.
+3. Give a scripted Test reviewer preference for Identity Service A in a future
+   revision, explicitly leaving the current contradiction unresolved and runtime
+   verification deferred. Save a Bound Surface; retain both source claims and
+   keep the reviewer decision separate from evidence.
+4. Start a fresh session, reopen the saved Bound artifacts and supply a later
+   configuration selecting Model Service B. Save a successor with stable
+   identities, exact parents, unchanged prior files, retained decision and
+   unresolved identity conflict. Independently read all saved directories.
+
+Shell/file tools and Node are permitted. Only the `n8r-surface` product executable
+is prohibited. The initial fresh-session prompt mistakenly said “no CLI use”;
+both sessions declined file access, accurately reported the blocker and created
+no successor. Those receipts are retained. The retry clarified this instruction
+in new sessions without changing skill code or overwriting previous artifacts.
+
+For a repeat of the corrected revision step, start a fresh Researcher chat with
+that trial's workspace selected and send:
+
+```text
+Reopen bound-001 and read change.md. Shell/file tools and Node.js are allowed,
+including the installed scripts/artifacts.mjs helper. Do not invoke the
+n8r-surface product executable. Save a checked successor in bound-002 selecting
+Model Service B. Preserve identities, decisions, unresolved identity evidence,
+exact parent references and all previous files. Retain the previous research
+as a dependency. Use the existing safe projection; do not expose private fields
+from instance.json. Saving is authorized. Read back both revisions, compare
+prior-file hashes, return output links and stop.
+```
+
+## Useful findings sampled against sources
+
+| Product | Finding | Independent source check |
+| --- | --- | --- |
+| LibreChat | Model integrations are documented possibilities, not an observed request path. | README lines 74–99 |
+| LibreChat | Storage uses a Mongoose/MongoDB connection; stored AI data and controls remain unverified. | `api/db/connect.js` lines 1–27 and 43–74 |
+| LibreChat | OIDC discovery and login depend on configuration, including PKCE/nonce settings. | `api/strategies/openidStrategy.js` lines 954–1006 |
+| Open WebUI | Chat/Responses routing sends a POST to the selected connection. | `backend/open_webui/routers/openai.py` lines 1506–1587 |
+| Open WebUI | SQLAlchemy has SQLite/PostgreSQL paths and rejects SQLCipher in async URL conversion. | `backend/open_webui/internal/db.py` lines 230–250, 264–285 and 450–468 |
+| Open WebUI | OAuth identity can affect local authority; effective settings remain unknown. | `backend/open_webui/utils/oauth.py` lines 168–190 and 1618–1650 |
+
+These are bounded agent checks of cited claims, not exhaustive source review,
+runtime proof or security certification. The developing agent did not author
+the Researcher's findings or saved bundles.
+
+## Observed result
+
+Both products passed the bounded agent rehearsal on the unchanged 0.1.11 skill.
+No product-specific code or new skill implementation was needed.
+
+| Independent check | LibreChat | Open WebUI |
+| --- | --- | --- |
+| Capability, Bound and successor helper readback | Exit 0, checked | Exit 0, checked |
+| Model target revision | A to B | A to B |
+| Database target | A retained | A retained |
+| Conflicting identity declarations | A and B retained | A and B retained |
+| Scripted reviewer decision | Exactly preserved | Exactly preserved |
+| Research/Surface parent references and Capability pin | Exact match | Exact match |
+| Files present before successful revision | 27 unchanged | 24 unchanged |
+| Source hash comparisons, including repeated dependency references | 19 matched | 28 matched |
+| Files scanned for synthetic sensitive sentinels | 68, no matches | 62, no matches |
+
+The owned raw sentinel input was excluded from the leak scan; artifacts,
+projections and execution receipts were included. This is evidence about those
+specific sentinels, not complete secret detection. All supplied public source
+copies remained byte-identical. Successor checks independently compared node and
+relationship identities, role endpoints, decisions, pins and parent digests.
+
+The initial harness recorded completed *turns* before checking whether outputs
+existed. That was not artifact success: independent readback found both missing
+successors. The retry requires successful helper readback before recording success.
+The blocked attempts and corrected requests remain in the private evidence.
+
+Private evidence retains the installation inventory, source identities/hashes,
+requests, execution receipts, before/after inventories, independent helper output
+and per-product verification reports. Saved briefs, HTML and JSON were read back;
+no screenshot or desktop visual acceptance is claimed.
+
+## Human acceptance and completion boundary
+
+**Agent rehearsal: Pass. User acceptance: accepted on 8 November 2026.** The user accepted the skill verification and authorized PRs #54 and #58 to be
+made ready to merge. The test-reviewer correction was scripted input, not a PM
+decision about a deployment or a separately observed human rerun. There is no remaining
+skill-code blocker identified by this bounded check. Broader research coverage,
+runtime use, CLI integration and Labs compatibility have not been established.
+No further presentation polish or additional product trials are required by this
+increment. Review and merge of PR #54 remain separate decisions.
+
+The accepted evidence can be reviewed using the two final `bound-002/brief.md` links supplied with
+this run's handoff; no installation or new research is necessary:
+
+- [ ] Read each brief. It must explain Model Service B, the retained database
+  target, the unresolved identity disagreement, evidence and unknowns.
+- [ ] Open its research HTML or JSON if a claim needs inspection. The reviewer
+  preference must remain separate from source evidence and actual runtime use.
+- [ ] Report **Pass / Fail / Blocked** for usefulness. For Fail, name the unclear
+  or unsupported claim; for Blocked, name the inaccessible file or missing context.
+
+User acceptance completes the usefulness decision for this scope. Readiness
+authorization does not authorize merge, publication or deployment. Keep #52 WIP while its
+implementing PRs await review/merge, following the repository's issue policy.

package/docs/n8r-surface/skill-workspace-automation.md

@@ -0,0 +1,359 @@
+# Installed Researcher workspace acceptance
+
+Issue [#43](https://github.com/injectionator/n8r-surface/issues/43) binds only the
+first three [canonical scenarios](../../tests/acceptance/skill-workspace.feature)
+to Cucumber: create, repeat setup and fresh-session reopen. The other scenarios
+remain manual. Ordinary `npm test` is offline and never starts inference.
+
+## Scope and interface
+
+The runner uses **Codex CLI 0.166.0 app-server over stdio**, not the desktop UI
+and not the standalone n8r command. It requires an enabled installed Researcher
+**0.1.9**, byte-identical to source commit
+`3cb08f59a4a932121bdd1c742fbac724d12a6d74`. The default installation is the normal
+Codex plugin cache. `--installed PATH --revision FULL_COMMIT` can select another
+already-installed, byte-verified 0.1.9 candidate. The runner never installs or
+replaces a plugin. See the [installation procedure](workspace-installation.md).
+
+The [documented skill input](https://developers.openai.com/codex/app-server#skills)
+loads the discovered installed SKILL.md. The harness supplies only the selected
+folder and scenario request. The model reads the skill reference and chooses the
+installed helper invocation; the harness never invokes the helper or writes
+workspace identity metadata. Its sole content write is the synthetic user note
+between create and repeat.
+
+One ephemeral thread holds create and repeat. Reopen starts another app-server
+process and empty ephemeral thread, with no copied transcript, expected identity
+or answer. The first process is closed; the second must fail to read the old
+thread through `thread/read`. The
+[permission profile](https://learn.chatgpt.com/docs/permissions) grants writes only
+to the disposable workspace and reads to the installed plugin and runtime paths.
+It denies access to retained evidence; a sandbox command checks allowed skill
+reads and denied evidence reads before each session, including the actual setup
+receipt before reopen. This technical probe never invokes the workspace helper.
+
+Memories, project instructions, apps, configured MCP servers, browser/computer
+access, remote control, multi-agent/history features and web search are disabled.
+The normal sign-in is used by the host, never copied into fixtures or receipts.
+Local commands receive a restricted environment. Command network access is off;
+Codex authentication and model service traffic still need network access.
+
+These controls establish the tested CLI boundary, not a general sandbox security
+certification. Runtime paths remain readable. The Codex service processes the
+conversation. No claim is made about desktop behavior, other hosts, or complete
+system-wide file auditing.
+
+## Run the three scenarios
+
+Maintainer prerequisites: Node.js 22, 24 or 26; Git; `npm ci`; Codex CLI 0.166.0
+signed in with ChatGPT; the identified plugin installed/enabled; a configured
+available OpenAI model. The runner records the selected model and refuses a
+provider fallback. A live run consumes account inference allowance and may incur
+cost under the account's terms. It is opt-in and is not scheduled in CI.
+
+From the repository root, on the branch under test:
+
+```sh
+npm run acceptance:skill -- --live --evidence .local/skill-acceptance/run-1
+```
+
+The evidence directory must not already exist. Create its parent first if needed:
+`mkdir -p .local/skill-acceptance`. Keep it private and ignored. A second run uses
+a new evidence directory and automatically creates a new disposable workspace:
+
+```sh
+npm run acceptance:skill -- --live --evidence .local/skill-acceptance/run-2
+```
+
+There are at most three user turns, one per scenario, each limited to 120 seconds,
+and a 600-second suite limit. No simulated user, retries or automatic conversation
+repair are used. A missing capability, unexpected host question or unanswered
+setup question is a failure/blocker; dependent scenarios cannot pass.
+
+The runner reports **automated** results separately from full Gherkin acceptance.
+Independent checks compare the saved format, UUID, folder-derived name, supplied
+purpose, complete entry lists, hashes and file timestamps. They compare helper
+receipts and assistant identity/location claims with filesystem readback. This
+detects changed-note and wrong-identity evidence without a model grader.
+
+Semantic criteria, such as useful continuation, accurate attachment claims and
+absence of unnecessary questions, remain **pending human review**. Each scenario
+runs its automated checks before an After hook marks it pending. Cucumber's
+passing intermediate steps are not full scenario acceptance. No pending criterion
+is counted as passed by default.
+
+Exit codes:
+
+- **1:** at least one automated scenario or final installation check failed.
+- **2:** blocked prerequisites, or automated checks passed but human review is
+  pending. Inspect `results.json` and `blocked.json` to distinguish these cases.
+- **0:** successful owned-fixture cleanup. Offline report and review modes have
+  their own exit meanings below. A live run does not claim full human
+  acceptance and therefore does not return 0 in this increment.
+
+## Evidence and human verification
+
+The evidence directory contains run/install identity once (`metadata.json`), raw
+app-server requests/events, each turn, before/after inventories, final metadata,
+Cucumber JSON and individual results with outstanding review criteria. Failed
+attempts get their own directory; rerunning never overwrites them. Paths, model
+responses and tool receipts are private: do not commit these files or paste raw
+receipts into public issues/PRs. Review and sanitize any published summary.
+
+Tester steps, after the maintainer has prepared the prerequisites above:
+
+- [ ] Run the first command from the repository root. Expect three automated
+  results and exit 2 when all automated checks pass with human review pending.
+  An automated failure, skipped prerequisite or `blocked.json` is not a pass.
+- [ ] Open `results.json`, `1-turn.json`, `2-turn.json` and `3-turn.json` in the
+  selected private evidence directory. For each result, inspect the listed
+  `reviewRequired` criteria against actual responses and tool activity.
+  Expect creation only, recognition on repeat, and useful readiness orientation
+  on reopen. No research, credentials request, attachment claim or repeated
+  setup permission question should occur. Use the
+  [existing experience rubric](workspace-human-check.md#independent-evidence-and-report).
+- [ ] Open the inventory files and `final-record.json`. Expect only identity
+  metadata after create, then that metadata plus the synthetic note, unchanged
+  through repeat/reopen. Inspect `setup.jsonl` and `reopen.jsonl` for the installed
+  helper path, denied-evidence probes and distinct empty ephemeral sessions.
+- [ ] Run again with `run-2`. Expect the same observable outcomes with a different
+  disposable destination, UUID, session IDs and timings. These values may vary;
+  preservation within one journey must not vary.
+- [ ] Report **Pass / Fail / Blocked** per scenario, including the reviewed run
+  directory and criterion, without publishing private transcripts. An automated
+  pass with unreviewed criteria is **Pending**, not human acceptance.
+
+After preserving/reviewing evidence, clean only the owned disposable fixture:
+
+```sh
+npm run acceptance:skill -- --cleanup --evidence .local/skill-acceptance/run-1
+```
+
+Expected: exit 0 and “Removed owned fixture only; evidence retained.” Cleanup
+requires the recorded ownership token and final inventory, refuses other roots,
+and leaves the evidence, normal installation and earlier trials untouched.
+
+## Offline checker tests
+
+```sh
+node --test tests/skill-acceptance.test.mjs
+```
+
+These tests deliberately substitute an incorrect identity, alter a synthetic note
+and timestamp, add a file, remove/fail the installed helper receipt, and fail a
+scenario prerequisite. They validate the assertions; they are not installed-skill
+acceptance runs. They also run in the normal offline `npm test` suite.
+
+## Development evidence — 8 November 2026
+
+Initial live rehearsals used macOS, Node 26.13.0, Codex CLI 0.166.0 and the
+configured `gpt-6-astra` model (medium effort). The normal installed Researcher
+0.1.9 matched all 14 files at the pinned revision before use. No installation
+replacement, desktop claim, merge or release was involved.
+
+Failed attempts are retained privately:
+
+| Attempt | Observed result |
+| --- | --- |
+| Initial interface probe | Installed skill selected its helper; Node could not read its system OpenSSL configuration. Destination remained empty. |
+| Permission probe launch | Nested config was incorrectly serialized as JSON rather than TOML; server did not start. |
+| First runner preflight | The harness incorrectly rejected the standard configured endpoint; no inference. An offline regression test now covers it. |
+| First full journey | Create passed. Repeat preserved files/identity but the checker wrongly demanded the absolute path again rather than allowing “selected folder.” Reopen was blocked by that failed prerequisite. The corrected assertion retains the create location requirement. |
+
+Two later fresh-fixture journeys passed all three automated scenarios:
+
+| Private run label | Create | Repeat | Fresh reopen | Full Gherkin result |
+| --- | --- | --- | --- | --- |
+| run-3 | 17.842 s | 11.881 s | 16.574 s | Pending human review |
+| run-4 | 21.449 s | 12.872 s | 18.257 s | Pending human review |
+
+These are developing-agent rehearsals, not PM acceptance. They used a dirty
+checkout during implementation; run-4 records complete harness file digests.
+A subsequent startup-deadline fix has an offline regression test; the committed
+rehearsals below include that fix. The maintained feature text is
+unchanged apart from selection tags. Checker tests demonstrate rejection of
+incorrect identity, altered notes, ambiguous isolation failures, malformed output
+and unsafe cleanup. The runner leaves human criteria pending instead of treating
+these tests or filesystem results as full conversational acceptance.
+
+### Committed-code repetitions
+
+Both runs below exercised clean commit
+`d9c99c4e9853ca407264f126a9dd2aa6b8599df4`, with identical harness digests and
+the environment/installed revision above. Each used a fresh disposable fixture,
+a different generated identity, and separate setup/reopen processes. Both exited
+2 with all automated checks passed and all full scenarios pending human review.
+
+| Private run label | Create | Repeat | Fresh reopen |
+| --- | --- | --- | --- |
+| run-5 | 18.251 s | 8.713 s | 17.801 s |
+| run-6 | 17.966 s | 8.431 s | 14.814 s |
+
+Independent readback confirmed unchanged repeat/reopen inventories, global
+settings fingerprints and installed bytes. Both reopen receipts retain the exact
+missing-thread error and denied evidence reads. Agent inspection of the messages
+found orientation, no repeated initialization question, honest attachment/access
+boundaries and no research activity. This is an agent assessment, not PM acceptance;
+the runner correctly leaves those human criteria pending. The documented cleanup
+command then removed both owned fixtures, exited 0 and retained all evidence.
+
+A deliberately missing installation exited 2 before inference and marked all
+three scenarios blocked. All 153 offline tests passed, including 14 acceptance
+checker/adapter tests. The package check passed locally on Node 26.13.0. CI for
+`d9c99c4` passed Node 22/24/26, fixtures/tooling, Markdown and local links. Local
+Markdown lint, lychee 0.24.2 offline links/anchors, citation validation and diff
+checks also passed. No live inference was run by CI.
+
+### Human acceptance — 8 November 2026
+
+The user ran the documented command from clean commit
+`77b1bc49108c2741e012cf1d6b5ca43e3cee97ab` on macOS with Node 22.23.2,
+Codex CLI 0.166.0 and `gpt-6-astra`. The installed Researcher remained 0.1.9
+at the pinned revision above. All three automated scenarios passed.
+
+After reviewing the actual final responses and relevant tool activity presented
+from that run, the user explicitly accepted **create, repeat setup and
+fresh-session reopen: Pass**. The user also accepted the reopen turn's denied
+attempt to read the unrelated Superpowers skill; its read returned exit 1 and
+the Researcher inspection subsequently succeeded. Recorded metadata/note
+inventories and global-settings fingerprints were unchanged through the
+applicable checks. Scenario durations were 16.998, 10.737 and 19.492 seconds.
+
+This is human acceptance of the reviewed run, separate from the earlier agent
+rehearsals. A private acceptance receipt accompanies the original run evidence;
+the raw Cucumber pending results remain unchanged as the historical automated
+output. Future runs still require their own human review. The user authorized
+PR #44 to become ready for review, not merge or release.
+
+## Readable reports and recorded human verdicts
+
+The follow-up in [#45](https://github.com/injectionator/n8r-surface/issues/45)
+adds a private `review.md` after live-run finalization. It contains each actual
+final response, user input, commentary, tool commands and results, including
+failed or denied operations. Successful tool outputs and technical session
+receipts are expandable in Markdown viewers supporting HTML details; their full
+text remains in the file. Failed outputs remain visible. Missing evidence is
+explicit. No model generates the report or judges the interaction.
+
+The runner prints the report path and a SHA-256 **run fingerprint**. The companion
+`review-manifest.json` binds the evidence file names/bytes and the report bytes.
+These files contain private machine paths and transcripts: retain them with the
+ignored run directory, not in public commits. Existing reports are verified,
+never silently regenerated over different evidence.
+
+To generate or verify a report for a retained run without inference:
+
+```sh
+npm run acceptance:skill -- --report --evidence .local/skill-acceptance/run-1
+```
+
+Expected: exit 0 when the report is successfully generated or verified, with the
+report path, fingerprint and automated status. Exit 0 here means reporting worked,
+not that the scenario passed. A blocked run can have a valid readable report.
+Missing required evidence prevents an overall Pass. Once a verdict receipt exists,
+this command also shows the three human verdicts and combined overall status.
+
+### Human review task list
+
+Prerequisite: a completed run from the command above or the live command. No new
+Codex sign-in, network access or inference is needed for report/review commands.
+From the repository root:
+
+- [ ] Run `--report` as shown above and open the printed `review.md` path. Read
+  each scenario's human criteria, actual final response and tool activity.
+  Inspect any failed commands and preservation warnings. Expect the same actual
+  responses as the retained turn receipts; there are no invented summaries.
+- [ ] Copy the report's run fingerprint. Choose **Pass**, **Fail** or **Blocked**
+  independently for create, repeat and reopen. The command below shows all Pass
+  only as an example; replace each verdict with your actual judgment, replace
+  the fingerprint and reviewer, and use the optional comment for any caveats:
+
+  ```sh
+  npm run acceptance:skill -- --review \
+    --evidence .local/skill-acceptance/run-1 \
+    --run COPY_THE_64_CHARACTER_RUN_FINGERPRINT \
+    --reviewer 'Your name' \
+    --create Pass --repeat Pass --reopen Pass \
+    --comment 'Reviewed the actual responses and tool activity.'
+  ```
+
+  Expect a separate `human-review.json` containing the run fingerprint, report
+  digest, reviewer, date/time, each verdict and comment. The terminal shows
+  automated status, human verdicts and overall status together. **Pass → exit 0;
+  Fail → exit 1; Blocked → exit 2.** A human Pass cannot override an automated
+  failure, final preservation error, missing evidence or blocked prerequisite.
+- [ ] Run `--report` again. Expect verification of the unchanged evidence/report
+  and the recorded human verdicts. Original Cucumber JSON and pending results
+  remain untouched; a verdict receipt does not retroactively alter execution.
+- [ ] Report **Pass / Fail / Blocked** for this review workflow with the private
+  run reference and any failed step. If commands refuse modified evidence, an
+  incorrect fingerprint or a duplicate review, that is the expected protection;
+  retain the refusal when reporting a problem. Do not publish raw private files.
+
+Only one review receipt is supported per run in this increment. Duplicate
+submissions refuse to overwrite it. A correction workflow, reviewer identity
+verification and signed audit records are out of scope. A reviewer name is a
+self-attribution, not authentication. Fingerprints detect drift relative to the
+retained manifest; they do not make files tamper-proof against someone able to
+rewrite both evidence and manifest. Evidence must be quiescent while reporting
+and reviewing; concurrent writers are unsupported.
+
+Owned-fixture cleanup still uses `--cleanup`. It retains reports and verdicts;
+its later `cleanup.json` receipt is excluded from the evidence fingerprint. The
+three generated review files are also excluded from that fingerprint, with
+report bytes bound separately. All other evidence files are included. Symlinks,
+nested entries and files over 64 MiB are refused. Historical manually written
+acceptance receipts are preserved, not automatically imported as new approval.
+
+Offline report/review checks:
+
+```sh
+node --test tests/skill-review.test.mjs
+```
+
+These tests use synthetic reviewer names and verdicts. They do not establish
+human acceptance of any real run. Live execution retains its existing pending
+exit behavior; `--review` is the separate acceptance step.
+
+### Report/review development evidence — 8 November 2026
+
+The observed baseline was the user's accepted #43 run: an agent had to extract
+responses/tools from JSON for human review. The new offline report command was
+exercised against that retained real run and a retained missing-installation run;
+they reported automated Pass and Blocked respectively without new inference or
+rewriting raw evidence. The earlier manual acceptance receipt was preserved and
+was not imported as a new command-recorded review.
+
+A fresh installed-skill run on macOS, Node 26.13.0, Codex CLI 0.166.0 and the
+configured `gpt-6-astra` model passed all three automated scenarios and generated
+the report automatically. The installed 0.1.9 plugin matched the same pinned
+revision before and after. This was a development checkout with harness file
+hashes retained privately, not a clean-commit or human acceptance claim.
+
+The agent checked every final response and command against the readable report,
+then exercised the documented review command using reviewer name
+“Codex agent rehearsal (not human acceptance)” and an explicit rehearsal comment.
+It recorded three Pass verdicts, exited 0 and displayed separate automated/human
+results. Offline report verification still succeeded after owned-fixture cleanup;
+raw results and all evidence remained retained. These verdicts test the recording
+workflow; they are not the user's acceptance of this increment.
+
+Focused offline checks cover changed/missing evidence, wrong fingerprints,
+modified reports, invalid/duplicate reviews, blocked/failing aggregation, null or
+empty required evidence, and interrupted-turn tool recovery from session receipts.
+The latter two cases were found in fresh review, corrected and regression-tested.
+All 171 offline tests passed, including 18 report/review cases; the installed
+package check also passed on Node 26.13.0. No new dependencies or live CI were added.
+
+A second fresh run exercised clean commit `1eb4cae` with the same environment
+and installed skill. All three automated scenarios passed in 52.7 seconds;
+live execution retained its pending-human status. The agent inspected the actual
+responses, tool activity, preservation and isolation receipts, then recorded an
+explicitly labeled agent rehearsal with three Pass verdicts (exit 0). Cleanup
+and offline report verification both exited 0, preserving the exact fingerprint
+and recorded verdicts. This does not establish desktop or human acceptance.
+
+A later offline regression caught an evidence file named `__proto__` being omitted
+from a plain JavaScript object's hash map. Null-prototype maps now include that
+filename; changing its contents is detected. The final narrow fix was verified
+by the offline suite rather than another live inference run.

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

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