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

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

@@ -0,0 +1,315 @@
+# First public npm release
+
+## Verified scoped release
+
+Published on 5 November 2026:
+**[`@n8r/surface@0.1.0-experimental.2`](https://www.npmjs.com/package/@n8r/surface/v/0.1.0-experimental.2)**,
+from commit `f38153645cd12f7ea60f76af251edfbaebb73409` and permanent tag
+`v0.1.0-experimental.2`. The
+[GitHub prerelease](https://github.com/injectionator/n8r-surface/releases/tag/v0.1.0-experimental.2)
+is finalized and read back as `immutable: true`. Its attached
+[verification summary](https://github.com/injectionator/n8r-surface/releases/download/v0.1.0-experimental.2/scoped-registry-verification.json)
+records the exact digest and checks.
+
+The maintainer approved **scoped-only** publication after npm accepted the scoped
+stage but rejected the unscoped submission with E403. `n8r-surface` remains the
+executable name; the unscoped registry package was not published or secured.
+Its archive remains retained solely as evidence of the original dual build.
+Unscoped publication and name reservation have since been removed from the plan.
+
+Independent readback verified registry bytes against the retained archive,
+installed library/assets and CLI identity on Node 22.23.2, 24.22.2 and 26.13.0,
+empty-home startup and a fresh-cache npm-exec invocation. npm audit verified
+registry signatures and the scoped package's provenance. Separate cryptographic
+verification required the exact GitHub workflow/tag certificate identity; the
+attestation subject digest and source commit/repository matched the release.
+These release checks are not new real-model research evidence.
+
+Use the exact version or npm tag `experimental`. `latest` still points to npm's
+`0.0.0-stage` placeholder; it has not been promoted. The `.1` preparation stopped
+before npm staging because of a faulty remote-tag API lookup. Its permanent tag
+and unpublished draft artifacts remain retained.
+
+## Experimental.5 release
+
+The maintainer authorized a new scoped release on 14 November 2026 after accepting
+PR #82. Version `0.1.0-experimental.5` packages the current library/CLI and
+Researcher skill 0.1.16. Earlier `.3`/`.4` candidates remain distinct; their older
+CLI evidence does not establish current release behavior. Only `@n8r/surface`
+is built or submitted. The source stays private and `latest` is unchanged.
+
+This release includes self-contained CycloneDX Surface saves in the skill,
+connected overviews and journals, instance-first investigation and progressive
+source-access guidance. CLI save formats remain separate; bundling the skill does
+not establish CLI/BOM parity. The [first-use evidence](first-use-access.md)
+records useful signed-in web responses but unresolved portable delivery/helper
+execution. Those limits remain; publication does not establish end-to-end web
+acceptance, runtime conformance or consumer compatibility.
+
+### Preparation and publication
+
+Start at the reviewed, clean release commit after Node 22/24/26 tests and installed
+package checks pass. Confirm GitHub account/repository and commit author. Create
+an annotated `v0.1.0-experimental.5` tag and push only that tag. It must be on `main`.
+Do not reuse or move a permanent release tag.
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.5 -f operation=prepare
+```
+
+The workflow builds one fresh publishable scoped archive, records its revision and
+SHA-256, retains a build artifact and creates a draft prerelease. Inspect its
+`candidates.json` and archive manifest: exact version, `@n8r/surface`,
+`private: false`, public registry and `experimental`. The source remains private.
+Download those assets; do not rebuild between preparation and staging.
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.5 -f operation=stage
+```
+
+The existing stage-only `NPM_BOOTSTRAP_TOKEN` route requires valid package write
+access. An expired credential blocks staging; renew it outside tracked files or
+review trusted publishing separately. A stage is not publication. Inspect the
+reported stage ID and validation state, then approve that exact stage with npm
+2FA. [npm's staged-publishing procedure](https://docs.npmjs.com/staged-publishing/)
+was rechecked on 14 November 2026. After approval:
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.5 -f operation=verify
+```
+
+Independently verify registry signatures and the package's own signed provenance,
+workflow/tag identity, source commit and archive digest. Exercise the isolated
+installation below on supported Node majors and a fresh-cache exact-version
+npm-exec route. Attach evidence and release notes before finalizing the immutable
+GitHub prerelease. Verify `immutable: true` afterward. Never promote `latest` as
+part of this procedure. Failed staging/readback leaves the draft incomplete;
+retain its bytes and verify existing registry state before retrying.
+
+### Human verification task list
+
+Maintainer preparation: provide the retained scoped archive from the draft release
+in a temporary directory, with Node 22/24/26 and npm installed. Run from that
+directory; `ARCHIVE` below is the archive's absolute path. No normal installation,
+Codex sign-in or research vault changes are needed.
+
+- [ ] Create an isolated consumer and install the archive:
+
+  ```sh
+  export ARCHIVE="$PWD/n8r-surface-0.1.0-experimental.5-scoped.tgz"
+  mkdir consumer
+  cd consumer
+  npm init --yes
+  npm install --ignore-scripts --no-audit --no-fund --package-lock=false "$ARCHIVE"
+  node --input-type=module -e 'import {decode} from "@n8r/surface"; console.log(typeof decode)'
+  ./node_modules/.bin/n8r-surface --version
+  ```
+
+  Expect exits 0, `function`, and `n8r-surface 0.1.0-experimental.5`.
+- [ ] Inspect `node_modules/@n8r/surface/plugins/n8r-surface/plugin.json`.
+  Expect skill version `0.1.16`. This does not install a plugin into a web host.
+- [ ] Exercise closed-input startup in an isolated home:
+
+  ```sh
+  mkdir empty-home
+  env HOME="$PWD/empty-home" USERPROFILE="$PWD/empty-home" ./node_modules/.bin/n8r-surface </dev/null
+  echo "$?"
+  ls -A empty-home
+  ```
+
+  Expect setup guidance, exit **1**, and an empty home. Missing imports, wrong
+  versions or home writes fail. After publication, repeat installation using
+  `@n8r/surface@0.1.0-experimental.5` in a new consumer and compare the result.
+- [ ] Report **Pass / Fail / Blocked**, Node/npm versions, archive digest and CLI
+  output. Missing archive/authentication is Blocked; any unexpected behavior is
+  Fail. Keep evidence, leave the consumer and remove only these temporary files.
+
+Agent rehearsal and human acceptance are separate. Build/registry evidence will
+be attached to the release; this preparation document does not assert publication.
+
+## Retained preparation procedure
+
+The procedure below records the original dual-package preparation. Its two-name
+acceptance requirement was superseded by the maintainer's scoped-only decision.
+Do not rerun it for the released version. The current workflow targets scoped experimental.5; the historical commands
+below are retained as first-release evidence only. Future
+releases require updated version guards, reviewed
+authentication configuration, and a new permanent version/tag. Trusted publishing
+has not been exercised; this release used stage-only token authentication and
+maintainer 2FA approval.
+
+## User outcome and starting evidence
+
+Given private local candidates and no verified registry versions, the maintainer
+can prepare both publishable archives from one reviewed commit, publish their
+retained bytes with provenance, and independently install either exact version.
+The source remains private to prevent publishing the checkout accidentally.
+
+The original installed/candidate checks passed, but those archives were private.
+Before this increment, `npm whoami` returned E401 and both names returned E404.
+After interactive login, npm identified the intended account and confirmed its
+`n8r` owner role. Both names still returned E404. These responses do not prove
+name availability or successful first publication. At that starting point, no placeholder existed.
+
+## Maintainer preparation
+
+1. Review and merge the release-preparation PR after acceptance. Merging is a
+   separate maintainer decision. The workflow must exist on the default branch.
+2. Use an authorized npm account with `n8r` organization rights and permission
+   to create the unscoped package. For this first release, the selected route is
+   a short-lived granular npm token with package **read/write (stage only)**
+   permission covering `@n8r/surface` and the new unscoped `n8r-surface`.
+   Selecting package `n8r` or scope `@injectionator` is insufficient. If npm
+   cannot select an unpublished unscoped name, temporarily use all-packages
+   coverage; organization-management permissions are unnecessary. Store it only as
+   repository Actions secret `NPM_BOOTSTRAP_TOKEN`. Never put it in a command,
+   issue, report or committed file. npm account 2FA remains enabled.
+3. Enable **Settings → General → Releases → Enable release immutability** before
+   creating the draft. An administrator may be needed; an API 404 under a
+   non-admin account is not proof the setting is disabled.
+4. Verify all required Node 22/24/26 checks on the reviewed revision. From its
+   clean checkout, create an annotated `v0.1.0-experimental.2` tag and push only
+   that tag. Never move or reuse it. Record its full commit SHA.
+
+References checked 5 November 2026: [npm token setup](https://docs.npmjs.com/creating-and-viewing-access-tokens/),
+[provenance](https://docs.npmjs.com/generating-provenance-statements/),
+[trusted publishing](https://docs.npmjs.com/trusted-publishers/), and
+[release immutability](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/prevent-release-changes).
+Trusted publishers require existing packages. npm offered stage-only tokens;
+the maintainer explicitly approved staged first publication, including the
+public `0.0.0-stage` placeholders it creates. The actual release versions require
+maintainer approval with 2FA. See [npm staged publishing](https://docs.npmjs.com/staged-publishing/).
+
+## Human check before publication
+
+Prerequisites: the PR checkout with dependencies installed, Node 22/24/26, npm,
+Git and POSIX `tar`. Staging uses npm 11.20.0 (staging requires 11.15+). Start in the repository root. These steps require no npm
+write credentials and do not alter normal settings or installations.
+
+- Create fresh publishable candidates:
+
+  ```sh
+  release_run=$(mktemp -d)
+  npm run pack:candidates -- "$release_run/packages" --publishable
+  tar -xOf "$release_run/packages/scoped/n8r-surface-0.1.0-experimental.2.tgz" package/package.json
+  ```
+
+  Expect exit 0, version `0.1.0-experimental.2`, name `@n8r/surface`,
+  `private: false`, public npm registry/access and tag `experimental`.
+  The source `package.json` must still have `private: true`.
+- Install and run the preferred archive:
+
+  ```sh
+  mkdir "$release_run/consumer"
+  cd "$release_run/consumer"
+  npm install --offline --ignore-scripts --no-audit --no-fund --package-lock=false "$release_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
+  mkdir "$release_run/home"
+  HOME="$release_run/home" USERPROFILE="$release_run/home" ./node_modules/.bin/n8r-surface </dev/null
+  echo "$?"
+  ls -A "$release_run/home"
+  ```
+
+  Expect install/import/version exits 0, `function`, and
+  `n8r-surface 0.1.0-experimental.2`. Bare startup prints setup guidance,
+  exits **1**, and leaves the isolated home empty.
+- Repeat in a new consumer and home directory using the `unscoped/` archive
+  and import `n8r-surface`. Expect identical behavior, with that installed name.
+- Report **Pass / Fail / Blocked**, both CLI outputs, Node/npm versions and
+  candidate revision/dirty flag. Unexpected version, missing imports, or home
+  writes are Fail. Missing prerequisites are Blocked. Leave the consumer and
+  remove only the temporary directory created above after retaining evidence.
+
+## Prepare and stage retained artifacts
+
+The manual [workflow](../../.github/workflows/npm-release.yml) accepts only the
+annotated first-version tag, requires it to be on `main`, and checks clean source.
+Preparation runs tests and both installed-package suites, builds both archives
+once, retains the complete build as an Actions artifact for 90 days, and stores
+the archives with `candidates.json` on a draft GitHub Release. An existing
+release prevents preparation from rebuilding. Downloads and hash validation are
+performed before any publication. Network access includes npm, GitHub and Sigstore;
+write effects are draft release assets and, only for `stage`, npm staged versions and first-package placeholders.
+
+From the repository root with GitHub CLI access:
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.2 -f operation=prepare
+gh run list --workflow npm-release.yml --limit 1
+```
+
+Inspect the run and draft assets; record the run ID and full source revision.
+Preparation must finish successfully before selecting staging:
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.2 -f operation=stage
+```
+
+The publisher reads both registry versions first. An existing version must match
+retained SHA-256 and registry SHA-512 integrity and expose provenance metadata;
+only absent versions are staged. Existing stages are downloaded and compared
+to retained SHA-256 before they are reused; duplicate stages or differing bytes
+stop the run. Non-404 lookup errors stop the run. The
+workflow never finalizes the GitHub Release and never promotes `latest`.
+Provenance metadata presence is not cryptographic verification.
+
+On partial failure, retain the draft and its exact assets. Retry **stage** only
+after diagnosing the failure; never rerun preparation or rebuild a published
+version. Existing bytes that differ require a new approved version for both
+packages. If draft creation succeeds but an upload fails, recover missing assets
+from the original run's `npm-release-COMMIT_SHA` Actions artifact. Download it
+with `gh run download RUN_ID -n npm-release-COMMIT_SHA -D NEW_DIRECTORY`, verify
+`candidates.json` revision and each archive SHA-256, and upload only missing
+assets without `--clobber`. Run `check:release` before retrying staging.
+Keep a durable independent copy before the 90-day retention expires. If the
+original bytes cannot be recovered, stop; do not regenerate them.
+
+## Approve each staged version with 2FA
+
+Open npm's **Staged Packages** page as the authorized maintainer. For each of
+`@n8r/surface` and `n8r-surface`, inspect version `0.1.0-experimental.2`, tag
+`experimental`, the workflow's stage ID and downloaded bytes. Approve each with
+2FA. Alternatively run `npm stage approve STAGE_ID` in your authenticated terminal.
+These actions publish the real versions; the placeholders are not acceptance.
+
+Then run the read-only verification operation:
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.2 -f operation=verify
+```
+
+Expect success only when both exact registry versions match retained bytes and
+expose provenance metadata. This operation cannot stage or approve anything.
+
+## Independent registry acceptance and finalization
+
+For each package, use a separate fresh consumer outside the checkout. Install
+its exact version with lifecycle scripts disabled, run `npm audit signatures`,
+read the installed name/version, import `decode`, run `--version` and the isolated
+closed-input startup above. Also exercise the two explicit one-off routes:
+
+```sh
+npm exec --yes --package=@n8r/surface@0.1.0-experimental.2 -- n8r-surface --version
+npm exec --yes --package=n8r-surface@0.1.0-experimental.2 -- n8r-surface --version
+```
+
+Both must print `n8r-surface 0.1.0-experimental.2` and exit 0. Download each
+registry tarball and compare its bytes/digests with the draft assets. Inspect
+its own provenance attestation, including source repository, full commit,
+workflow identity and subject digest; an attested dependency is insufficient.
+Record registry `dist.integrity`, publication and install results independently.
+
+After both routes pass, configure trusted publishing separately for both names:
+GitHub owner `injectionator`, repository `n8r-surface`, workflow `npm-release.yml`,
+no environment, permission to stage. Keep maintainer 2FA approval for promotion. A new configuration must succeed within
+two days; do not configure it long before its next use. Verify the configuration
+and its first actual OIDC publication before claiming it works. Remove the
+bootstrap secret and revoke its token when no longer needed. A future version
+requires a reviewed update to the deliberate first-version guards.
+
+Attach independent evidence and final release notes, then finalize the draft
+with prerelease true and latest false. Read it back with `check:release` and
+require `immutable: true`. Finalization remains blocked on failed registry,
+provenance, identity or immutability checks. Record **Pass / Fail / Blocked** with
+both package results; local rehearsals do not establish a completed release.

package/docs/n8r-surface/product-direction.md

@@ -0,0 +1,327 @@
+# Product direction: security investigation of composed AI systems
+
+Captured 11 November 2026; strategic context expanded 12 November 2026.
+Documentation scope:
+[#64](https://github.com/injectionator/n8r-surface/issues/64).
+This records the user-established direction and a proposed smallest demonstration.
+The demonstration scope below is a recommendation for review, not authorization
+to implement, deploy or test a system. No demonstration results are claimed here.
+
+The next proposed increment is the [Joe/Maya design and delivery sequence](../superpowers/specs/2026-11-14-joe-maya-proof-design.md):
+recover the existing lab, revisit the same evolving target, and connect a bounded
+policy/evaluation/observation proof to retained Surface history. Surface is the
+independently useful public node; target operations and harness authoring/execution
+belong to n8r-runtime and n8r-probe respectively, initially private Labs modules.
+Surface discovers Promptfoo, alternatives and Langfuse integrations without
+operating them. Prompt injection remains a test family within wider AI surface
+security; the original inline sidecar is deferred. Developing the integrated proof
+does not make Labs a prerequisite or release its private components.
+
+## Strategic context
+
+The agreed destination is a practical [AI Surface security assurance framework](security-assurance-strategy.md)
+and professional service: policy and assurance levels connect to controls,
+implementation guidance, static/live assessment and observable verification.
+The primary reader is the consultant advising an engineer or architect and the
+system owner. Discovery and this first demonstration are increments toward that
+destination; they do not constitute the whole framework. The strategy maps existing
+work and proposed milestones, including assessment coverage and scoring decisions.
+
+## Why and for whom
+
+People use AI to assemble software and services into agentic systems they did
+not architect and may not understand. Others inherit those systems or must make
+a release decision about them. They may not know which security questions to ask.
+Firing inputs at an interface and hoping for a useful score does not explain
+where authority is exercised, which controls exist or what downstream effects
+occurred. Experienced investigators may instead arrive with a precise question.
+
+The product direction is professional security investigation: discover enough of
+the system to identify consequential questions, establish what the evidence says,
+and help the owner make and verify a corrective change. The first value should
+be an understandable, reproducible security finding and demonstrated improvement,
+with legitimate use preserved. Findings support a release decision; they do not
+certify that an entire system is secure.
+
+The AI Surface Model makes this work traceable across components, relationships,
+configurations and revisions. It remains independently usable; security
+investigation is a product use of the model, not a restriction on its meaning.
+The installed n8r-surface skill in Codex is the discovery entry point. CLI breadth,
+a general telemetry backend and a larger schema are not outcomes in themselves.
+
+## Presentation: brief by default, explanation within reach
+
+Default to a short, at-a-glance view with colour where the host supports it,
+recognizable short names and plain-language status labels. Show the relevant
+components and connections, the main finding or question, material uncertainty
+and the next useful action. Short names must remain unambiguous within the view
+and resolve to the same full names and stable identities in expanded detail.
+
+Keep “Explain this” or “More” one click away where interactive controls are
+available, or one natural-language request away in Codex. Explain the selected
+item in context: what it means, why it matters, the supporting evidence and its
+limits. Evidence links should lead to the underlying sources or retained records.
+Expansion uses the same claims and revisions as the summary; fetching new evidence
+is a separate investigation and must be identified as such.
+
+Users who prefer a longer explanation can request it directly. Honour their
+chosen level of detail throughout the current conversation. Persistent preferences
+across chats are a later implementation choice, not an existing capability claim.
+
+Colour reinforces text and symbols; it is never the only carrier of meaning.
+Provide a readable plain-text fallback and keep labels consistent across views.
+Evidence status (possible, configured, observed, unknown) is distinct from a
+security result (for example, a demonstrated unauthorized read). Colour must not
+turn “configured” into “safe”, or a passing scoped check into whole-system approval.
+Material gaps and conditions stay visible in the compact view; longer reasoning,
+source excerpts and investigation history can sit behind expansion.
+
+## Investigations we bring to the system
+
+For broad intake, the investigator selects relevant questions from discovered
+boundaries rather than requiring the owner to identify a vulnerability first.
+A specific user question can narrow the same process. Each investigation needs
+an intended rule with a stated basis: owner policy, documented contract or an
+explicit hypothesis awaiting confirmation.
+
+| Family | Questions to investigate |
+| --- | --- |
+| Enforcement | Where is a promised rule not enforced? Where is a rule enforced in one component but only assumed in another? Which security assumptions are never checked? |
+| Dependencies and composition | Which undocumented behaviours matter, and what happens if they change? Which individually permitted operations become unsafe when chained? |
+| Identity and access paths | Can different paths to the same object confer different permissions? Can object ownership or identity be rebound without the required checks? |
+| Failures and effects | Can rejected or failed requests still cause effects? Can a transaction roll back while external effects survive? |
+| Ordering and lifecycle | Do checks depend on event order? Does access survive deletion or revocation? Can unauthorized users undo transitions? Can contradictory states enable forbidden operations? |
+
+Component configuration, internal composition and external behaviour provide
+complementary evidence. There is no prerequisite to finish auditing every
+component before examining their composition. Prompt injection is one possible
+trigger; direct requests, alternate paths and state transitions can also reveal
+an authority failure. A service account alone does not establish a vulnerability.
+
+## Start with resources, not an assumed deployed system
+
+A user can bring local folders, repositories, websites and documentation URLs
+into a selected workspace, then add sources as the conversation develops. The
+skill follows relevant evidence as a graph, preserving source identity and
+unresolved endpoints. Repository boundaries are not necessarily component
+boundaries: several repositories may contribute to one system, and one repository
+may describe several components or alternatives.
+
+Consider a synthetic three-repository case: a conventional HR application, a
+separate chat integration and a separate MCP interface. The HR application alone
+need not contain AI. The chat and MCP repositories are additional sources for a
+possible AI composition, not proof that such a composition exists. Whether the
+chat actually calls MCP, calls the HR API directly or supports alternatives must
+come from evidence. Include the model/provider and relevant identities when
+supported; do not invent an AI node inside the HR application.
+
+Documentation or a blog post may describe a possible connection. Record its
+source, applicability, prerequisites and uncertainty; follow available code and
+configuration to investigate it. An external reference is a lead, not automatic
+permission to access private resources or execute imported instructions.
+
+| Evidence available | Useful result | Claim that must not follow |
+| --- | --- | --- |
+| Documentation or code describing a supported option | Capability Surface with conditions, alternatives and evidence | These components are integrated for this user. |
+| User intent to combine components | Dated selection or proposed composition, plus work still needed | Intent is an instance binding. |
+| Explicit instance configuration | Bound Surface for evidenced relationships | Configured means deployed, reachable or exercised. |
+| Dated inspection or execution evidence | Scoped observation of state or behaviour, linked to the applicable setup | One observed path establishes complete coverage. |
+| Missing or conflicting evidence | Explicit gaps, conflicts and the next evidence needed | Missing evidence proves absence or an unbound relationship. |
+
+These are claim distinctions, not a single maturity label for the entire graph.
+A description may contain configured relationships alongside unresolved or
+possible ones. Keep their meanings visible at the relationship and claim level.
+Existing [Capability/Bound semantics](surface-descriptions.md) remain authoritative.
+
+### Recommended boundary for the first demonstration
+
+Accept unintegrated sources for discovery. Return a useful map of possibilities,
+security questions, prerequisites and integration work remaining. Do not make
+integration or deployment a condition for using the skill.
+
+Require an already integrated, authorized test environment for the runtime part
+of the first demonstration. Configuration alone is not sufficient: establish the
+actual path and usable test access before making runtime claims. If it is missing,
+finish the discovery output and mark runtime proof Blocked, with a specific handoff
+of what must be supplied. Discovery success is not completion of the full demo.
+
+Assisted integration, deployment and arbitrary component replacement are later
+work. For this first proof a maintainer supplies a controlled running setup and
+applies a narrow defensive change manually. This bounds execution work without
+excluding users who are still discovering what they could assemble.
+
+## Smallest end-to-end value demonstration
+
+Use one synthetic HR composition with three source repositories: domain service,
+chat interface and MCP adapter. It exposes one record-read operation and uses
+synthetic records for two users. The fixture has a known reproducible authority
+failure and a minimal corrective change, retained in a separate maintainer oracle.
+The investigator receives ordinary source and system access, not the expected
+finding, faulty location or fix. This demonstrates discovery on a controlled case,
+not general vulnerability detection accuracy or a finding about a real HR product.
+
+The intended policy is supplied as normal business context: each employee can
+read their own restricted record, but cannot read another employee's record.
+This provides a testable rule without supplying the security diagnosis.
+The fixture's exact technology and enforcement location are builder choices;
+choose the smallest setup that exposes the real cross-component path. A scripted
+runner or developer-written findings cannot substitute for the installed skill.
+
+**State X:** an identified installed skill in Codex, an established local workspace,
+three permitted source repositories with known revisions, and docs URLs or local
+snapshots. Initially the investigator receives the domain application source and
+business policy. Chat/MCP sources and instance evidence arrive in later turns.
+A maintainer has a running isolated composition, test identities and synthetic
+data ready for the runtime handoff; source-only discovery must not infer that fact.
+
+**Input Y:** the user asks what has been built and where its security boundaries
+might fail, then adds the other sources, configuration and permitted test access.
+They request saved output and fresh-chat continuation. The investigator proposes
+a bounded test based on its discoveries. The owner authorizes its execution on
+the fixture, and a maintainer later applies the defensive change.
+
+**Outcome Z:** the user receives an evidence-backed composition, a discovered
+security question, a reproduced unauthorized read through the composed path,
+a supported explanation of the enforcement failure and a before/after comparison
+showing denial after the change while the authorized read still works. Saved
+artifacts can be reopened without losing identities, gaps or the original result.
+
+### Demonstration task list
+
+These are proposed acceptance interactions, not rehearsed passing behaviour.
+Use the [installed-skill setup](researcher-skill.md) and
+[workspace guide](workspace.md); the maintainer supplies the fixture and access.
+
+- [ ] Open the prepared workspace in Codex with the installed skill. Ask:
+  “Explore this HR application folder and its documentation. Tell me what is
+  known about its AI connections and security boundaries. Do not assume it has
+  AI built in.” Expect a bounded account with source evidence and unknowns;
+  no invented internal AI component.
+- [ ] Add the chat and MCP repository folders and documentation URLs. Ask:
+  “Include these sources, follow the relevant links between them, and save a
+  Surface brief explaining possible integrations, security questions and what
+  remains to be configured or established.” Expect cross-source relationships,
+  prerequisites and alternatives without an unsupported deployed-system claim.
+- [ ] Supply sanitized instance configuration. Ask:
+  “Show which relationships this configuration binds, what is still unknown,
+  and which security question most needs investigation. Save a successor.”
+  Expect traceable configured relationships and an independently derived question
+  about authority, without assuming runtime use or copying credentials.
+- [ ] Supply the fixture's permitted test access and approve the proposed bounded
+  test through the separately identified execution owner. Expect a legitimate
+  read and a prohibited cross-user read to be exercised through the composed
+  interface, with actual downstream requests, decisions and results inspected.
+  A model refusal alone is not evidence that the tool did not access data.
+- [ ] Have the maintainer apply the narrow defence. Repeat the same tests against
+  the identified successor setup. Expect the prohibited fresh read to be denied
+  by effective enforcement and the legitimate read to remain available. Inspect
+  downstream evidence, not only chat wording. Use records not already disclosed
+  in conversation when checking fresh retrieval.
+- [ ] Save the evidence-linked result, then open a fresh Codex chat. Ask:
+  “Reopen this investigation. Explain what was possible, configured and actually
+  demonstrated before and after the change, and what remains unproved.” Expect
+  stable identities, distinct setup/run references, accessible evidence and
+  unchanged predecessor artifacts.
+- [ ] Inspect the default brief. Expect recognizable short names, concise text
+  labels, visible material gaps and colour where supported. Ask: “Explain this
+  connection and show its evidence.” Expect a contextual explanation tied to the
+  same identities and revisions, within one request; a UI control may provide
+  the same action. Ask for a longer explanation, then return to the brief. Expect
+  consistent claims and readable meaning without colour. Record whether both
+  presentation levels help the tester understand the finding.
+- [ ] Report **Pass / Fail / Blocked**, artifact links, failed or blocked steps and
+  whether the result explains an actionable security problem. Generated wording
+  and identifiers may vary. Unsupported integration claims, a missed seeded
+  failure, missing runtime evidence, broken legitimate access, lost history or
+  sensitive-data leakage fail this demonstration. Missing prerequisites block it;
+  they are not a passing negative security result.
+
+### Maintainer preparation and independent verification
+
+Pin fixture revisions, initial configuration and policy, installed skill bytes,
+host/model/version and test environment. Keep the oracle separate from investigator
+inputs and record everything disclosed. Fresh chats alone do not prove isolation;
+record source/tool access and any contamination. Before implementation, attempt
+this path through the current installed skill or record the exact unavailable
+prerequisite. No such attempt is claimed by this documentation change.
+
+An independent reviewer compares consequential graph claims with source locations
+and the runtime finding with the oracle and underlying evidence. Retain actual
+inputs, expected policy, observed outputs, effective identities, authorization
+decisions and downstream data access. Correlate these with run and setup identities;
+record conflicts, unavailable telemetry and inference separately from observation.
+Read saved files independently and compare predecessor hashes after continuation.
+Keep raw research and telemetry outside this public repository; publish only
+permitted sanitized summaries. Synthetic fixtures must contain no real HR data.
+
+Expected state changes are new workspace research/Surface artifacts, fixture test
+sessions and a separately recorded defensive configuration/code revision. The read
+scenario does not require business-data mutation. Preserve source and prior
+artifact bytes; record any fixture-generated audit/session state. Cleanup resets
+only owned test state after evidence retention and explicit cleanup authorization.
+Agent rehearsal, independent technical checks and human acceptance are separate.
+
+## What n8r-surface needs to support
+
+The current skill already instructs graph-first research, incremental source
+intake, evidence identity, explicit gaps and continuation. Capability/Bound
+artifacts have a bounded helper and contract. These mechanisms are foundations;
+they do not establish that this three-repository demonstration passes. Verify the
+installed path before deciding which implementation changes are necessary.
+
+| Needed outcome | Existing basis and next proof |
+| --- | --- |
+| One investigation across folders, repositories and URLs | Exercise incremental intake and follow-up through the installed skill; preserve source revisions, access limits and unresolved external links. |
+| A useful graph without an integrated system | Reuse Capability semantics; verify no invented AI inside the domain application and no promotion of docs/blog claims into bindings. |
+| Evidence of configured composition | Reuse Bound semantics and safe configuration references; verify mixed supported/configured/unknown relationships and distinct role versus instance identities. |
+| Questions selected from discovered boundaries | Demonstrate an investigator-generated authority question with rationale and policy basis, rather than a user-supplied diagnosis. This needs explicit acceptance evidence. |
+| A runtime handoff another actor can execute | Provide the relevant graph identities, policy, proposed test, required observation points and gaps. Execution remains outside the current read-only skill. |
+| Evidence-linked findings and before/after comparison | Define the smallest linkage between claims, source revisions, effective setups, runs and retained evidence. Start with readable working records where needed; do not mislabel them as validated structured Observed Surfaces. |
+| Brief and expanded explanations | Verify concise defaults, unambiguous short names, accessible status cues and one-request explanation/evidence access in the installed host. Material uncertainty must survive both views. |
+| Durable continuation | Exercise saved artifact readback and fresh-chat reopening with stable identities, predecessor history and explicit remaining work. |
+
+Observed Surface delivery is currently deferred in the
+[description contract](surface-descriptions.md). This proposal calls for a bounded
+runtime-evidence handoff and linkage, not a silent expansion of that contract or
+permission for the skill to launch tests. Before implementing this part, specify
+the execution owner and interface, evidence references, privacy/retention rules
+and any versioned contract changes. No new command or output format is introduced
+by this document. Update conversational intents and their verification together
+if behaviour is subsequently changed.
+
+## Observability and consumer boundary
+
+For this demonstration, collect only enough evidence to correlate the initiating
+user, proposed and executed tool request, effective downstream identity,
+authorization decision, returned data and relevant effects with the exact run and
+setup. A prompt/response trace alone cannot prove downstream enforcement. State
+what was not observed; missing telemetry must not become a claim of no effect.
+
+An observability sink is a candidate implementation, not yet a prerequisite.
+Evaluate existing telemetry, log references and narrow collection against this
+case before choosing adapters or storage. Langfuse and OTEL are possible integration
+directions, not evaluated compatibility claims. A general backend, continuous
+collection and broad adapter support are outside the smallest proof.
+
+n8r-surface owns discovery descriptions and the meanings needed for evidence
+handoff. Test execution, resource configuration and later component swapping
+belong to the consumer integration boundary, with n8r-labs application design
+kept in its separate repository. A Lab contains Experiments; an Experiment asks
+its Lab for setup, and the Lab owns configuration and local bindings. The first
+manual consumer rehearsal neither requires Labs automation nor establishes Labs
+compatibility. No n8r-labs implementation is specified here.
+
+## Delivery decisions and remaining work
+
+The recommended first scope is one composed path, one policy, two test identities,
+one demonstrated authority failure and one defensive change, plus a legitimate-use
+check and saved continuation. A broad audit, all investigation families, automated
+integration, component substitution and a release score are outside this increment.
+
+The next useful work is to select the permitted fixture and execution owner, then
+rehearse source intake through the installed skill and record gaps. Fix only gaps
+that block this proof; retain existing behaviour that already satisfies it.
+No target has been selected, no runtime test has been run and no implementation
+has been authorized by capturing this direction. The proposed integrated-runtime
+boundary and fixture choice remain reviewable decisions. Existing acceptance and
+release work is not automatically closed or reprioritized by this document.