@n8r/surface 0.1.0-experimental.2 → 0.1.0-experimental.5

package/docs/n8r-surface/surface-descriptions.md

@@ -0,0 +1,173 @@
+# Capability and Bound Surface delivery
+
+Agreed intent, 8 November 2026. The contract layer is implemented separately;
+these installed-skill outcomes remain planned, not evidence of product acceptance.
+Parent: [#17](https://github.com/injectionator/n8r-surface/issues/17).
+
+## Intent and names
+
+The installed Researcher uses artifacts in a selected workspace, supplemented by
+authorized research, to produce and revise useful evidence-backed descriptions.
+It preserves sources, component identities, human decisions, gaps and history.
+There is one AI Surface Model; the following are descriptions within it, not
+separate models. Size and depth are independent of these distinctions.
+
+| Description | Question answered | Evidence boundary |
+| --- | --- | --- |
+| Capability Surface | What connections and capabilities can this product support? | Docs/code establish possibilities, without asserting instance bindings. |
+| Bound Surface | Which relationships are configured for this instance? | Explicit instance configuration is enough to mark a relationship bound. Runtime use need not be proved. |
+| Observed Surface | What configuration and state were observed for an instance at a particular time? | Dated instance inspection; any runtime claim needs runtime evidence. Deferred from this delivery. |
+
+For example, a Capability Surface may describe support for OIDC authentication
+and MongoDB. A Bound Surface may identify OIDC and MongoDB Atlas as the configured
+authentication and database relationships. These examples are illustrative, not
+findings about an inspected deployment. Actual setting values are outside this
+increment. Configured does not mean reachable, exercised or successfully deployed.
+
+Missing evidence means unknown, not unbound. Supported alternatives remain
+separate from selected bindings. Conflicting evidence remains visible rather than
+being silently resolved. Definitions and instance bindings retain separate
+identity/revision meaning; later evidence cannot rewrite prior descriptions or Runs.
+
+## Shared component and relationship structure
+
+Capability and Bound descriptions both contain component nodes and identified,
+typed relationship edges. Relationships carry purpose (why), integration mechanism
+(how), configuration references (owner, setting names and safe documented locations),
+and evidence for each detail. Unknown or conflicting details remain explicit.
+The Bound description retains this useful context and adds configured-target
+claims; it is not merely a list of targets detached from their integrations.
+
+Configuration references describe where/how settings are defined, never their
+actual values. Role endpoints and concrete bound targets have distinct identities;
+a successor can change the target without changing the relationship's purpose or
+rewriting its predecessor. The [bounded representation](surface-relationships.md)
+keeps earlier contracts readable and describes compatibility limits.
+
+## Outputs and privacy
+
+On an authorized save, provide a concise readable Surface brief, a research HTML
+record and checked structured Surface output in JSON, with openable file links.
+Working Markdown notes remain useful intermediate artifacts. The brief may be
+included in the readable record; an additional file is not mandatory. Outputs
+identify their description type, scope, evidence, gaps and recommended next step.
+
+For a Bound Surface, retain the target's useful role/product identity and the
+fact of its configured relationship. Omit or mask sensitive URLs, IPs, usernames,
+passwords and keys. Do not put those values in generated notes, HTML, JSON,
+filenames, validation errors or retained evidence. Use opaque identities that do
+not encode sensitive values; do not copy a raw value merely to redact it later.
+An inability to inspect a source safely is a coverage limit, not permission to
+collect secrets. Existing workspace/source secrets are not copied into output.
+
+No raw-secret store is required or introduced. Credentials remain in their
+existing stores. Recoverable exact settings and secure storage would require a
+separate future design. Observed Surface is deferred, including actual settings
+capture and live/runtime inspection; no continuous synchronization is promised.
+
+## Contract boundary and implementation choices
+
+The [current experimental contract](contracts.md) represents selected definitions
+and leaves deployment bindings outside its profile. This document does not
+silently extend that contract or relabel existing definitions as Bound Surfaces.
+The [shared relationship contract 0.3](surface-relationships.md) defines the
+representation and versioning for #50; installed artifact production remains #51.
+Capability alternatives have an explicit representation; mutually exclusive possibilities must not be flattened
+into a selected composition. Preserve shared identities and exact evidence links.
+
+Reuse existing codecs, validators, HTML rendering and revision checks where
+suitable. The builder selects file layout, helper/API integration and the bounded
+representation, documenting compatibility limits and checking them against the
+agreed meanings. JSON is the first structured representation. YAML expansion,
+other hosts, Lab integration, deployment changes and release work are deferred.
+The first supported acceptance environment is the installed skill in Codex.
+The skill is standalone: it must not invoke or depend on the `n8r-surface` CLI.
+Artifact production and checks must work through the host and bundled skill
+resources independently of that executable.
+
+## Intent and verification
+
+**State X:** an identified installed skill, a selected supported workspace and
+accessible, permitted docs/code artifacts with recorded source identity. Begin
+with no instance binding evidence. Reuse established workspace setup; record any
+missing prerequisite as Blocked. Before implementation, attempt the current
+installed path and retain actual behavior or its prerequisite blocker.
+
+**Input Y:** ask for a Capability Surface and saved artifacts; then supply permitted
+instance configuration, a human correction and a second source, and request a
+Bound Surface. In a fresh chat, reopen the saved artifacts and revise one binding.
+
+**Outcome Z:** useful readable and checked structured outputs, supported
+capabilities separated from configured relationships, traceable claims and gaps,
+privacy-preserving output, and a successor retaining identities and history.
+Only authorized workspace artifacts change. Source files and prior outputs remain
+unchanged; no configuration, services, credentials or runtime are modified.
+
+### Maintainer preparation and technical evidence
+
+- Identify the installed candidate revision/digests, host/model, source revisions
+  and initial workspace inventory. Use the established installation procedure in
+  [the skill guide](researcher-skill.md).
+- Prepare permitted source packs for two unrelated products, including incomplete
+  evidence, a second source and a known configuration change. Synthetic sensitive
+  sentinels allow exact leak detection without using real secrets.
+- Exercise the actual installed skill; do not seed findings and claim the
+  Researcher produced them. Independently read saved bytes, sample consequential
+  claims against sources, run contract/reference/successor checks and compare
+  prior-file hashes. Scan all generated files and retained evidence for sentinels.
+- Keep source transmission within authorized access. Retain private evidence
+  outside the public repository; publish only sanitized summaries and fixtures.
+- Leave malformed data, reference failures, failed saves and preservation cases
+  to focused automation. Fixture checks do not prove research quality or host
+  acceptance. Record expected, observed, verified and unproved outcomes separately.
+
+### Human verification task list
+
+These are the target interactions, to be exercised against the installed candidate
+once implemented. They have not been rehearsed as passing product behavior by
+this documentation increment. The maintainer supplies the selected workspace and
+source pack; the tester does not need to choose a schema or run validators.
+
+- [ ] Open the prepared workspace in Codex and select the installed Researcher.
+  Ask: “Use the supplied docs/code to create a Capability Surface. Save the brief,
+  research HTML and structured Surface in this workspace.” Open the returned
+  links. Expect supported possibilities and explicit gaps, without asserted
+  instance bindings; the files must exist and answer the question.
+- [ ] Supply the prepared instance configuration and second source. Ask: “Create
+  a Bound Surface from this evidence. Configuration is sufficient to mark a
+  relationship bound. Omit sensitive setting values.” Expect the evidenced
+  targets, such as OIDC and MongoDB Atlas, with no runtime-use claim or leaked
+  synthetic sensitive values. Missing/conflicting evidence must stay visible.
+- [ ] Give the prepared human correction. Expect a scoped decision/correction
+  without erasure of contrary source evidence. Authorize a saved successor.
+- [ ] Start a fresh chat with the same workspace and the saved artifact selected.
+  Supply the prepared changed-binding evidence. Ask: “Reopen this Surface and
+  save a successor reflecting this binding change.” Expect retained component
+  identities, a clear change and predecessor reference, and unchanged old files.
+- [ ] Repeat the bounded journey with the unrelated source pack. Expect the same
+  meaningful distinctions without product-specific implementation or user repair.
+- [ ] Report **Pass / Fail / Blocked**, the output links, which step failed or was
+  blocked, and whether the outputs were useful and understandable. Wording,
+  timestamps and generated IDs may vary; unsupported bindings, secret leakage,
+  lost decisions/history, broken files or false success claims are failures.
+
+Agent rehearsal and human acceptance are separate records. Fresh chats do not
+prove enforced memory/tool isolation. Retain owned trial artifacts for review;
+cleanup is a separate authorized action and must not touch borrowed source data.
+
+## Three delivery tasks
+
+1. [#50 — Descriptions and contract](https://github.com/injectionator/n8r-surface/issues/50):
+   capture this intent, then define bounded representations, versioning and
+   synthetic examples with meaningful checks. See the implemented
+   [contract and human check](surface-relationships.md).
+2. [#51 — Installed-skill artifact production and revision](https://github.com/injectionator/n8r-surface/issues/51):
+   implement generation, validation, privacy, saving and fresh-chat continuation
+   using workspace evidence. Depends on #50.
+3. [#52 — Installed-workflow acceptance](https://github.com/injectionator/n8r-surface/issues/52):
+   exercise both products, inspect outputs independently, fix observed failures
+   and record human acceptance. Depends on #51.
+
+Creating these tasks authorizes neither their implementation nor review readiness,
+merge or release. Broader #17 host/live/consumer scope remains separately visible;
+finishing this bounded delivery does not automatically complete the parent issue.

package/docs/n8r-surface/surface-relationships.md

@@ -0,0 +1,231 @@
+# Shared Surface relationships contract 0.3
+
+Capability and Bound Surfaces describe one graph vocabulary: **component nodes
+and identified relationship edges with their own data and evidence**. A connection
+must explain why it exists, how it integrates and where configuration is defined,
+as far as the sources establish. Size/depth remains independent of description kind.
+
+This is the revised bounded #50 contract, following human verification of the
+[earlier 0.2 increment](surface-description-contract.md). It implements a reusable
+structure, not a universal ontology or a real-product integration claim. The
+[synthetic examples](../../examples/researcher/relationships/README.md) are fictional;
+their setting names and data purposes are not findings about LibreChat.
+
+## Common graph and relationship data
+
+Both kinds use `contract: "n8r.surface/0.3"`, the existing envelope, `records`,
+`vocabularies`, `nodes`, `relationships`, `coverage` and `gaps`. Nodes remain
+`{id, label, type: {vocabulary, term}}`. A shared component retains the same ID.
+Relationships can share endpoints, form cycles or connect a node to itself.
+
+Every relationship has these required fields:
+
+| Field | Meaning |
+| --- | --- |
+| `id` | Stable identity of the integration relationship. |
+| `from`, `to` | Local component IDs identifying source and target integration roles. |
+| `type` | `{vocabulary, term}` giving the relationship's meaning, such as `persists-data` or `authenticates-via`. |
+| `purpose` | Why the source uses the target; which task or data requires this integration. |
+| `integration` | How it connects: driver, API, protocol or other evidenced mechanism. |
+| `configuration` | Safe references identifying who owns the configuration, its mechanism, setting names and documented locations. |
+| `basis` | Research finding references establishing support for this relationship. |
+| `conditions`, `note` | Material conditions, applicability and remaining limits. |
+
+`purpose`, `integration` and `configuration` each have the same detail shape:
+`{state, claims, note}`. Each claim is `{value, basis}` with nonempty basis entries
+`{record, revision, items}`. Purpose/integration values are nonempty text;
+configuration values are arrays of configuration references. This keeps evidence
+on the fact it establishes rather than implying that one citation proves every
+property of an edge.
+
+| Detail state | Claims |
+| --- | --- |
+| `known` | Exactly one agreed value, supported by known findings. |
+| `conflicting` | At least two distinct sourced claims with differing values or known-versus-absent assertions; no selected answer. |
+| `absent` | Exactly one sourced, scoped absence claim; the note explains what is absent. |
+| `unknown`, `omitted`, `redacted`, `out-of-scope` | No values; the note explains the knowledge boundary. |
+
+A detail finding's `subject` is the relationship ID, `property` is exactly
+`purpose`, `integration` or `configuration`, and its claim value matches the
+corresponding detail claim. All competing values in cited findings must remain
+visible. Known/absent details must agree with the finding state. A conflicting
+detail can cite conflicting findings, multiple known findings with differing
+values, or known and absent findings. Opposed known/absent assertions can use the
+same value; keep separate claims/basis links so the source states remain visible.
+Two agreeing known sources do not establish conflict. Reference verification also checks uncited findings for the same
+relationship/property in the description's referenced research, preventing a
+contradiction from disappearing through selective basis links. Unknown details
+can remain conservative without asserting absence.
+
+A type vocabulary supplies the meaning of its terms; it does not substitute for
+purpose, mechanism or configuration evidence. Unknown terms remain opaque, as in
+prior profiles. A broader ontology and executable constraint language are not
+required to represent these relationship facts.
+
+## Safe configuration references
+
+A configuration reference is `{owner, mechanism, key, location}`:
+
+- `owner` resolves to a local component node; configuration belongs to that
+  component, not implicitly to whichever endpoint a reader guesses.
+- `mechanism` is `environment-variable`, `file-key`, `argument`, `admin-setting`
+  or `code` in this bounded vocabulary.
+- `key` identifies the setting or entry, such as the fictional `CHAT_STORE_URI`.
+- `location` is a safe relative documentation/source location, such as
+  `config/assistant.env.example`. For an environment variable or admin setting,
+  this can point to the source documenting where it is configured.
+
+Locations cannot be absolute paths, URLs, traversal paths or contain query/fragment
+syntax. Use the research source locator for a section/line/key within the document.
+A location is descriptive metadata, not authority to access a file or proof that
+it exists on a user's deployment. Its source finding links to the exact research
+revision, source digest and locator; a host resolves the supplied source context.
+If the owner/name/location cannot be described safely, retain an unknown/redacted
+configuration detail and explain the limit.
+
+There is **no actual setting value** field. A known configuration detail says where
+and how configuration is defined; it does not mean the instance is configured.
+Passwords, connection strings, IPs, private deployment paths and account names
+must not appear in fields, prose, filenames or retained evidence. The checker
+rejects unknown setting-value fields and unsafe location syntax, but is not a
+secret detector. Producers remain responsible for safe collection and output
+inspection. No raw-secret store is introduced.
+
+## Capability and Bound distinctions
+
+A Capability relationship adds `state` using the existing possible/unknown/omitted/
+redacted/absent/out-of-scope/conflicting support states. Support basis retains
+[0.2's subject/property/target rules](surface-description-contract.md#capability-surface).
+`exclusiveGroups` now names relationship IDs. Knowing why/how to integrate does
+not assert that any instance selected that relationship.
+
+A Bound Surface pins one Capability revision and identifies one opaque `instance`.
+Every included relationship uses the same ID, `from`, `to` and `type` as its pinned
+Capability edge. It repeats the useful relationship details with its own exact
+research references, so the Bound file can answer why/how/where without forcing
+a reader to reconstruct another document. Details may reflect instance-specific
+facts or corrections when separately evidenced; the pinned Capability stays intact.
+
+Instead of `state`, each Bound relationship has a `binding` annotation:
+`{state, claims, decisions, note}`. These retain [0.2 binding semantics](surface-description-contract.md#bound-surface):
+one configured target, multiple conflicting targets, or no claims for unknown/
+omitted/redacted/out-of-scope. Claims are `{target, basis}`; targets resolve to local
+nodes. Decisions refer separately to human decisions, never substitute for source
+configuration evidence, and cannot erase contradictions. Missing evidence is not
+unbound. Configuration evidence is sufficient; no runtime-use claim follows.
+
+**Role endpoint versus configured target:** a database relationship's `to` may
+identify the MongoDB component role, while `binding.claims[].target` identifies
+MongoDB Atlas for this instance. Both are explicit local component nodes. The
+relationship keeps its identity and purpose when a successor changes the binding
+target to self-hosted MongoDB. A renderer must show the binding annotation/target;
+drawing only `from`/`to` shows the role graph, not the full configured view. Unknown
+or conflicting bindings must not be rendered as selected concrete edges.
+
+A Bound file may include only the relevant subset of Capability relationships;
+omission means unspecified, never absent. A configured binding requires a possible
+Capability relationship. Exclusive groups still prevent selecting incompatible
+options together. Same-ID nodes must retain their type across the linked graphs.
+
+## Versioning, checking and revision limits
+
+This shape is explicitly `0.3`, not a silent alteration of `0.2`. Existing `0.1`
+selected definitions and `0.2` descriptions remain readable with unchanged shapes
+and retained fixtures. `0.3` readers reject top-level `capabilities`/`bindings` and
+require the shared `relationships` representation. Older readers reject `0.3`.
+There is no automatic conversion or downgrade: invented metadata, dropped
+property-level evidence and flattened conflicts would be losses. Preserve the
+original and review any projection separately. These remain descriptions within
+one AI Surface Model, not separate models.
+
+Use the existing APIs: `validateArtefact`, `encode`/`decode` (JSON only),
+`verifyReferences` and `verifySuccessor`. Local validation checks fields, states,
+node endpoints, config owners and declared research references. Reference checks
+require the exact research/Capability revisions and digests, evidence roles and
+matching values. No network access or filesystem writes occur. Passing checks
+cannot establish that source prose is true or complete.
+
+Successors retain node types and relationship endpoints/type for retained IDs.
+Description kind, instance identity and Capability-artifact identity cannot change.
+Metadata can gain evidence or corrections in a successor; earlier bytes must remain
+unchanged. Changing a concrete binding target does not change role endpoints.
+Two-snapshot checks do not enforce corpus-wide identity retention or persistence;
+hosts must preserve history and prevent reusing retired IDs for different things.
+The existing 2 MiB/depth-64 codec limits, empty extensions and privacy boundaries
+remain in effect. Observed Surface and actual settings capture remain deferred.
+
+## Human verification task list
+
+Open [the new relationship fixtures](../../examples/researcher/relationships/README.md).
+No CLI, inference, credentials or live instance is required for this contract check.
+
+- [ ] Open `capability.json`, then find `urn:cap:database` in `relationships`.
+  Expect Assistant → MongoDB, type `persists-data`, purpose “Persist conversation
+  history and user profiles”, and a MongoDB driver/wire-protocol mechanism.
+- [ ] Inspect that edge's `configuration`. Expect owner `urn:node:app`, mechanism
+  `environment-variable`, key `CHAT_STORE_URI`, and location
+  `config/assistant.env.example`. Open that supplied file: it documents the name
+  and owner without a connection string. Follow the configuration claim's basis
+  to `research-r1.json`, then its source/locator. Expect the config source, while
+  purpose and integration cite the separate explanatory source pack.
+- [ ] Open `bound-r1.json` and find the same relationship ID. Expect the same
+  endpoints and useful integration details plus a **configured** Atlas binding.
+  Authentication still has **conflicting** targets and a separate human preference;
+  inference purpose/mechanism/configuration and binding remain **unknown**.
+- [ ] Compare `bound-r2.json` and `research-r2.json`. Expect the same relationship,
+  role endpoints and purpose, new self-hosted MongoDB target and exact predecessor
+  references. The old files retain Atlas. No settings values should appear.
+- [ ] Report **Pass / Fail / Blocked**, filenames and any missing explanation,
+  incorrect configuration reference, lost conflict or exposed value. These are
+  developer-authored fixtures, not installed Researcher or human acceptance evidence.
+
+### Maintainer preparation and runnable readback
+
+From the repository root, use Node.js 22, 24 or 26 and npm. `npm ci` and
+`npm run build` must exit 0; installation uses the registry. Then run:
+
+```sh
+node --input-type=module <<'JS'
+import {readFileSync} from 'node:fs';
+import {decode, verifyReferences, verifySuccessor} from './dist/index.js';
+const read = name => decode(readFileSync(
+  `examples/researcher/relationships/${name}.json`, 'utf8'), 'json');
+const context = ['research-r1', 'research-r2', 'capability'].map(read);
+const before = read('bound-r1'), after = read('bound-r2');
+verifyReferences(context[2], context);
+verifyReferences(before, context);
+verifyReferences(after, context);
+verifySuccessor(before, after);
+const edge = before.relationships[0];
+console.log(edge.purpose.claims[0].value);
+const config = edge.configuration.claims[0].value[0];
+console.log(`${config.owner}: ${config.key} at ${config.location}`);
+console.log(`${edge.binding.claims[0].target} -> ${after.relationships[0].binding.claims[0].target}`);
+JS
+```
+
+Expect exit 0 and exactly:
+
+```text
+Persist conversation history and user profiles.
+urn:node:app: CHAT_STORE_URI at config/assistant.env.example
+urn:target:atlas -> urn:target:mongodb
+```
+
+Readback changes no files and needs no cleanup. Different output or a nonzero exit
+fails. `npm test` additionally covers missing/mismatched metadata evidence,
+contradictions, local endpoints/config owners, unsupported fields, privacy,
+revision integrity and the preserved earlier contracts.
+
+## Baseline and acceptance boundary
+
+Human inspection of #50 at `18478d7` found the generic `uses` edge insufficient.
+Library readback of its retained `0.2` fixtures confirmed no structured purpose or
+configuration and no Bound `relationships` array. The `0.3` fixtures exercise that
+same task: identify a relationship and read its purpose, mechanism, configuration
+reference and evidence in both descriptions, then read back a revised binding.
+
+The installed skill 0.1.9's previously recorded artifact-generation blocker remains
+unchanged. #51 must implement production/checking through the standalone skill,
+without invoking or depending on the `n8r-surface` CLI. #52 owns installed-workflow
+and human acceptance. Library/package checks are not evidence of those outcomes.

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

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