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

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

@@ -0,0 +1,144 @@
+# Historical skill 0.1.12 CycloneDX verification
+
+This alongside-records rehearsal used explicitly supplied historical notes and
+model intent; it was not a neutral fresh assessment. It does not verify the revised
+BOM-authority design. See [candidate 0.1.13 evidence](skill-bom-verification.md).
+
+Issue [#68](https://github.com/injectionator/n8r-surface/issues/68), draft
+[PR #69](https://github.com/injectionator/n8r-surface/pull/69). Agent rehearsal on
+13 November 2026; human acceptance, merge and release remain separate decisions.
+
+## Revision and environment
+
+The isolated installation contains all 22 plugin files exactly matching source
+commit `da0e445221d2209fc843d0cef682606610d22ad5`, candidate 0.1.12.
+Codex CLI 0.166.0, ChatGPT sign-in, configured `gpt-6-astra`, Node 26.13.0,
+macOS. No API-key or provider/model fallback. The active everyday installation
+remained 0.1.11; this candidate used a separate host home and private workspace.
+
+The harness uses ephemeral app-server sessions with the installed skill supplied
+as a skill input. Network, memory, unrelated tools and repository instructions are
+disabled. Only the selected workspace and installed skill are accessible, apart
+from required runtime files. A filesystem probe checks that private evidence and
+unsupplied repository instructions cannot be read. Source-pack provenance, raw
+transcripts, outputs, hashes and environment receipts stay in the selected private
+vault; this public record contains no private deployment configuration.
+
+## Baseline and task
+
+State X: installed 0.1.11, supplied source pack and writable workspace. Input Y:
+inspect the installed skill/helper and determine whether checked CycloneDX export
+is available, without substituting invented findings or an external exporter.
+Observed: only native artifact operations were available; the host identified the
+missing mapping/export/validation workflow. This was a bounded capability check,
+not a failed full research run.
+
+The candidate task was to research the supplied multi-component sources, explain
+the system to a consultant advising a security engineer, preserve intended versus
+historical configuration, save native records and CycloneDX alongside them, and
+read both back. The source pack contained selected code, documentation and safe
+historical operational projections recovered from prior work. No applicable SBOM
+was supplied; network lookup was unavailable. Upstream revision, package and
+transitive coverage remain explicit gaps.
+
+## Observed initial result
+
+The installed candidate performed its own investigation and preparation. The
+developing agent supplied sources and user instructions, not prewritten findings.
+
+- Twelve recorded source hashes match their supplied files after the run.
+- Checked native Capability records contain nine nodes and nine relationships.
+- CycloneDX 1.7 contains five components and four services. It has no concrete
+  dependencies because the candidate chose Capability for this evidence scope.
+- Native snapshot equals the checked native bundle. Mapping/report retains the
+  connection meanings, evidence and uncertainty absent from the BOM view.
+- Intended model and different historical model evidence remain distinct. Source
+  control points are identified without asserting present deployment or efficacy.
+- Native brief, HTML and JSON, consultant summary and five-member exchange were
+  saved and independently reopened. The candidate corrected one inspection error
+  (`mapping.nodes` is nested inside the report), then completed readback. It did
+  not replace the successfully checked export with unchecked JSON.
+
+## Fresh-session correction
+
+A second ephemeral process confirmed that the previous thread was unavailable,
+then recovered from the saved directories and supplied sources. The rehearsal
+input added an owner decision to keep connector tools disabled in the intended
+configuration and require separate authorization/assessment for a future enabled
+path. It was explicitly design intent, not evidence of deployed configuration.
+
+The candidate saved native and exchange successors. Independent developer readback
+confirmed all ten earlier artifact files and all twelve sources were unchanged;
+all nine node identities and the prior decision were preserved. Decisions grew
+from one to two. The BOM serial stayed stable and its version advanced from 1 to
+2. Native snapshots matched both checked bundles. This is an actual installed-agent
+rehearsal, not human acceptance.
+
+## Independent consumer
+
+CycloneDX Python Library **11.12.0**, Python 3.13.1, in a separate environment:
+`JsonStrictValidator(SchemaVersion.V1_7)` returned no validation error;
+`Bom.from_json(data=json.loads(text))` deserialized the synthetic configured BOM.
+The consumer listed its application and separate services and resolved the
+selected application dependency to the concrete Atlas target rather than its
+abstract database role. The [retained synthetic exchange](../../examples/researcher/cyclonedx/configured/README.md)
+is available for inspection. The same independent consumer then validated and
+loaded both actual installed-skill BOMs: five components, four services, versions
+1 and 2, no dependency edges, as expected for this Capability projection.
+This establishes those bounded read tasks only; it
+is not lossless round-trip, general consumer or runtime compatibility.
+
+## Maintainer checks
+
+- Full suite: 208 passing on Node 22.23.2; 209 passing on Node 24.22.2 and
+  26.13.0 after adding the installation-buffer regression. Its focused 15-test
+  suite also passes on Node 22.23.2.
+- Installed package checks pass on all three Node majors, including existing
+  terminal setup/reuse/preservation interactions. Exact skill bundle and notices
+  checks pass; no runtime dependency installation is needed by either helper.
+- Twenty-four Git workflow tests and shell syntax check pass. Example JSON parses;
+  native contracts/reference checks and CycloneDX schema/reference checks are
+  bounded validation, not universal model conformance.
+- Markdown lint 0.24.0, offline links with lychee 0.24.2, citation metadata with
+  cffconvert 2.0.0 and whitespace checks are run before the final handoff.
+
+Two integration failures were found and fixed during actual checks: installed-byte
+verification exceeded its old one-MiB Git output buffer, and package smoke checks
+still expected the previous instruction version/digest. The buffer now permits
+16 MiB with a large-helper regression; the digest was independently calculated
+from the candidate source bytes. A fresh whole-branch reviewer confirmed the
+package-pin failure and found no critical projection issue. Additional tamper and
+classification boundaries were manually exercised by that reviewer; retaining
+more automated variants and clarifying the shared skill paragraph's CLI boundary
+remain minor follow-ups. The new exchange is a standalone skill capability, not
+a new product CLI command.
+
+## Human task list
+
+Prerequisites: candidate 0.1.12, Node 22/24/26, a readable source set and a writable
+disposable workspace. Open a fresh Codex chat in that workspace. Maintainers can
+install the pinned source through the normal plugin marketplace mechanism; see
+[skill installation](researcher-skill.md). Do not substitute an older installation.
+
+- [ ] Supply your source paths and say: `Use n8r-surface Researcher to explain this
+  multi-component Surface. Save checked native records and CycloneDX 1.7 alongside
+  them. Explain what the evidence establishes and what remains unknown.` Expect
+  source-backed findings and links to the native brief and exchange files.
+- [ ] Open the brief and `mapping.json`. Expect intended/historical/current state
+  to remain distinct. Open `surface.cdx.json`; expect identified components and
+  services, with only eligible explicitly selected dependencies. Capability output
+  may have none. Unknown coverage is explicit.
+- [ ] Start a fresh chat, supply saved directories and say: `Reopen these records.
+  Record this correction as a design decision, save successors and preserve all
+  earlier records and decisions.` Supply a correction. Expect stable node IDs and
+  BOM serial, incremented BOM version and links to both generations.
+- [ ] Report **Pass / Fail / Blocked**, candidate revision, interactions and output
+  paths. Missing output, invented facts, lost decisions or modified prior records
+  fail. Missing installation/source access blocks. Keep evidence for review; later
+  remove only the disposable workspace, not original sources.
+
+Values such as names, node counts and selected dependencies depend on the supplied
+sources; the nine-node rehearsal is not a required graph size. The
+[working manual](skill-manual.md) explains the user journey. Technical helper
+verification uses exit 0 for `saved-and-read-back` / `checked`; a nonzero exit is
+not success. Those commands are maintainer evidence, not required user interactions.

package/docs/n8r-surface/skill-cyclonedx.md

@@ -0,0 +1,85 @@
+# Self-contained CycloneDX Surface
+
+Skill **0.1.13** introduced the format below; candidate [0.1.14](first-use-overview.md)
+adds checked optional grouping and a connected overview without changing profile 1.
+The 0.1.13 increment replaces the 0.1.12 alongside-native exchange as the
+destination for new Surface saves. Issue [#68](https://github.com/injectionator/n8r-surface/issues/68).
+One CycloneDX 1.7 BOM carries inventory, relationships, evidence, decisions,
+uncertainties and investigation state. The brief, HTML map and Markdown journal
+are generated from it. Earlier saves remain intact and deliberately readable.
+The standalone product CLI retains its existing pair behavior; this is skill-first.
+
+## Standard fields and profile
+
+The [CycloneDX 1.7 reference](https://cyclonedx.org/docs/1.7/json/) supplies
+components/services, metadata, dependencies, annotations, external references,
+citations and properties. The [BOM-Link specification](https://cyclonedx.org/capabilities/bomlink/)
+provides version-pinned predecessor identity. We use one BOM per revision, not a
+set whose missing member could hide required investigation state.
+
+The exact [Surface profile](../../plugins/n8r-surface/skills/research/references/cyclonedx.md#profile-properties)
+and [synthetic example](../../examples/researcher/surface-bom/initial.cdx.json)
+are bundled with the installed skill. Profile version 1 uses unregistered
+`n8r:surface:` properties: objective, scope, individual relationship/evidence/entry
+records, coverage and gaps. It does not embed the native research/Surface bundle.
+
+| Meaning | Standard representation and bounded addition |
+| --- | --- |
+| Application, model, service | `components` / `services` with stable `bom-ref`; model type `machine-learning-model`. |
+| Selected dependency | Standard `dependencies`, mechanically checked against selected dependency-kind profile relationships. |
+| Supported alternative | Individual relationship property with support evidence, optionality/group, selection and conditions. Never an unconditional dependency merely because supported. |
+| Hosting, integration, data flow | Distinct relationship kinds, not interchangeable `dependsOn` edges. |
+| Dated observed use | Observation records with timestamp and observation-basis evidence; independent of support/selection. |
+| Findings, choices, disagreements | Standard annotations with subjects, annotator, timestamp and readable text. |
+| Source identity | External references with safe locator, hash, source version/capture scope in comment; profile evidence points to exact locations and applicability. |
+| Attribution | Standard citations with checked JSON Pointers and attribution references. Not a replacement for evidence. |
+| Investigation journey | Ordered entry properties: objective-driven steps, questions, findings, decisions, branches, supersession, access needs and reasons for deferral. |
+| Lifecycle | Capture context in metadata when established; never a forced whole-Surface evidence state. |
+| Revision | Stable serial, increasing version, exact predecessor BOM-Link and byte digest. |
+
+Missing configuration is unestablished selection, not absence. A placeholder is
+not a concrete binding. Safe static configuration can establish selection.
+Selection evidence distinguishes actual configuration from human design intent.
+Optionality is not a confidence score. A group alone does not assert exclusivity.
+
+## Save and recovery boundary
+
+The standalone `surface.mjs` checks official pinned schemas, profile shapes,
+references, evidence applicability and exact dependency projection. It saves one
+new private revision folder with BOM, generated views and a byte manifest.
+The BOM alone reopens; sibling files are not semantic dependencies.
+
+For directory continuation, edited generated views block ordinary save. Explicit
+reconciliation reads the proposals, retains the edited files, records an accepted
+choice/explanation and writes a successor. Predecessor BOM hashes are still checked.
+Supplying a lone BOM proves only its own structure and supplied predecessor identity,
+not that an unavailable old manifest or source is intact. No authenticity claim.
+
+The reader preserves historical annotations/source references and decision
+provenance; corrections add evidence and can supersede decisions. Nodes and
+relationship endpoints/kinds retain identity. Older revisions are never rewritten.
+Unsupported profile versions, dangling references and ambiguous projections fail.
+
+Legacy `artifacts.mjs read` and `cyclonedx.mjs read` remain available for deliberately
+supplied old saves. Migration requires reviewing and transferring their meanings
+into a fresh profile BOM, with explicit provenance/limits. No automatic lossless
+legacy conversion is claimed. No second native authority is created for new saves.
+
+## Consumer and visualization limits
+
+Generic consumers can read standard inventory and selected dependencies. They
+cannot reconstruct possible paths or investigation state without this profile.
+The helper renders those distinctions as solid selected and dashed other paths,
+with support state, evidence, observations and journal available for inspection.
+
+Sunshine at commit `beaab3faf2bab234069a8677fc627de2f0f01a3d` generated HTML from
+the synthetic 1.7 BOM, including application/model names and all four services.
+Its output omitted the profile relationship IDs, evidence and decision entries.
+It is therefore not selected as the investigation visual. This is a file-level
+consumer exercise, not a browser rendering or general 1.7 compatibility claim.
+See [Sunshine source](https://github.com/CycloneDX/Sunshine/tree/beaab3faf2bab234069a8677fc627de2f0f01a3d).
+
+The visual requires no scripts, remote assets or network. HTML escaping and a
+restrictive content policy keep saved text inert. Browser visual QA is separately
+tracked in the [verification record](skill-bom-verification.md). Validity does not
+establish research accuracy, complete inventory, deployed controls or runtime use.

package/docs/n8r-surface/skill-manual.md

@@ -0,0 +1,129 @@
+# Researcher skill: working user manual
+
+For installation and a short first trial, use the [tester guide](tester-candidate.md).
+
+Candidate 0.1.13 saves the Surface with a brief, visual map and investigation
+journal. This manual develops through actual use; the
+[verification record](skill-bom-verification.md) distinguishes exercised behavior
+from pending human acceptance. The earlier [0.1.12 rehearsal](skill-cyclonedx-verification.md)
+used historical material and a different save format; it was not a neutral fresh
+assessment.
+
+## Start with what you have
+
+Candidate 0.1.16 can begin with a short description or deployment document.
+Researcher should show a provisional map, then help you provide one useful next
+source. You do not need to prepare a Lab, repository or SSH connection first.
+See [first-use examples and checks](first-use-access.md). A web Project can hold
+uploaded sources; it does not automatically connect a laptop folder. Saving and
+live access depend on the tools available in the current chat.
+
+## Start with your question and sources
+
+Open a fresh chat with the Researcher and explicitly supply a checkout, source
+pack or permitted documentation. You do not need to classify the Surface.
+
+> Explain the AI-relevant components and paths in this source for a security
+> engineer. Save the Surface in this folder and maintain an investigation journal
+> as we go. Show me what is known, what remains uncertain and useful next steps.
+
+Expect a useful initial plan and a shallow map, then evidence-driven investigation.
+The Researcher uses this chat's supplied sources. It should not search old chats or
+vault research automatically. If the host supplies recognizable historical context,
+it should disclose that context; ask it to exclude it when inappropriate. This
+is not a promise that the host has no memory.
+
+## Start with an existing system
+
+If your question concerns a running composition, identify the instance and the
+read-only access you permit. Supply relevant remote repositories, documents or
+URLs through tools available in your Codex/ChatGPT host. A URL alone does not
+provide private access, and a local checkout may describe only one component.
+Candidate 0.1.15 follows this [instance-first workflow](instance-first-research.md).
+
+> Understand this running system using the host access I have provided. Explain
+> its components and connections, what is configured, what has been observed and
+> what remains untested. Keep inspection read-only and save the Surface here.
+
+Expect partial progress when an integration cannot be inspected. Researcher does
+not start a service, sign in for you or send a test prompt to complete the graph.
+On a later visit, it distinguishes actual target changes from newly learned facts
+and missing access. The existing source-only workflow remains available.
+
+## Inspect the developing Surface
+
+Open the latest brief for the current explanation, the HTML map for paths and
+expandable evidence, and the journal for the investigation journey. The Researcher
+should provide the working folder and absolute file links without changing projects.
+The journal retains scope, available evidence, findings, choices, questions,
+diversions, deferred paths and reasons. Each next step explains its purpose and
+needed access. You can inspect the whole map, redirect or stop at any time.
+
+A supported database is a possibility; it is not necessarily the selected target.
+Safe static configuration may establish selection, while a placeholder cannot.
+Missing configuration means unknown selection. Solid paths are selected; dashed
+paths require inspecting their support/selection details. Dated observed use is
+separate. Optional does not mean weak evidence.
+
+## Redirect and save
+
+> Pause this path and investigate authentication first. Keep the deferred work,
+> explain what access would help, and save the updated Surface.
+
+Expect the choice and its reason in the journal, useful next options and a new
+numbered revision. Previous files remain unchanged. Saving generates a brief,
+map and journal from the same Surface; there is no separate native data authority.
+The technical file is CycloneDX 1.7 with a bounded Surface profile. Ordinary users
+need not choose that format or ask for a separate export.
+
+## Return in a fresh chat
+
+Supply the latest `surface.cdx.json` and selected sources. The BOM alone retains
+relationships, evidence, choices, uncertainty and the investigation journey.
+
+> Continue this Surface. What did I choose, what remains uncertain, and what
+> should we investigate next? Keep earlier decisions and revisions.
+
+The Researcher reads the supplied Surface, re-establishes access and tells you
+when evidence cannot be refreshed. A new observation does not rewrite old ones.
+If you edit a generated journal, supply that edited folder and ask to reconcile
+it. The Researcher treats edits as proposals, records accepted changes in a new
+revision and preserves the edited original. It must not silently overwrite it.
+
+Old native/exchange saves remain readable when deliberately supplied. Migration
+requires reviewing their evidence and recording limits; no automatic lossless
+conversion is claimed. See the [format details](skill-cyclonedx.md).
+
+## What the fresh rehearsal showed
+
+The installed Researcher saved an initial plan before inspecting sources, then a
+second revision with the partial graph and next options. It worked from the
+explicitly supplied checkout, without the old operational notes. It reported that
+Git inspection was unavailable in its session and used inspected-file hashes.
+That is a useful distinction: source identity can be bounded without pretending
+the entire checkout or deployment has been verified.
+
+A scripted user diversion successfully moved the investigation to authentication.
+The journal kept the tool/document paths as deferred, with reasons, and retained
+the choice as a rehearsal decision. Earlier files were unchanged. The agent's
+presentation check initially missed a setting name because Markdown escaped its
+underscores; it normalized that escaping and completed readback. If a check fails,
+ask what failed and how readback was verified, rather than accepting a bare success
+claim.
+
+The fresh continuation received only a copied BOM and source access. It recovered
+the authentication-first choice and deferred work, proposed two next steps with
+access requirements, and saved another revision. Earlier files, relationships and
+source evidence remained intact. This exercises the ordinary “continue this
+Surface” interaction; human visual review and acceptance remain separate.
+
+## Report your check
+
+Pass when the brief is useful, evidence is inspectable, choices survive reopening
+and earlier files remain intact. Fail for invented relationships, lost decisions,
+missing state or unsupported claims of observed use. Blocked means a prerequisite
+such as source access or Node is unavailable. Return the interaction and relevant
+file paths without secrets. Agent rehearsals do not substitute for your acceptance.
+
+The Researcher describes and investigates; it does not deploy, attack, certify or
+score the target. A schema check is not evidence that a selected connection works.

package/docs/n8r-surface/skill-surface-artifacts.md

@@ -0,0 +1,234 @@
+# Standalone installed-skill Surface artifacts
+
+Issue [#51](https://github.com/injectionator/n8r-surface/issues/51) adds a standalone
+artifact helper, now bundled in candidate skill 0.1.11. The host researches sources and prepares
+JSON; the bundled helper checks it, renders research HTML and a brief, and saves
+a new revision directory. It never invokes the `n8r-surface` CLI, reads source
+configuration, connects to a model or makes network requests.
+
+## Task and implementation boundary
+
+**Given:** the installed candidate, Node.js 22/24/26, an authorized workspace and
+permitted source evidence. **When:** the user requests a saved Capability or Bound
+Surface. **Then:** the host provides openable brief, research HTML and 0.3 JSON,
+with pinned dependency artifacts and a hash manifest. A fresh chat can read the
+saved directory and save a checked successor while preserving the predecessor.
+
+The current [relationship contract](surface-relationships.md) supplies validation,
+evidence references and revision rules. The helper reuses that implementation;
+JSON decoding retains the existing strict codec. A development-only esbuild step
+bundles the helper and its YAML parser dependency into one offline Node module.
+The parser's licence is retained alongside it. There is no runtime dependency
+installation. The library reader accepts both presentation generations; the CLI persistence output remains unchanged.
+
+`npm run build:skill` regenerates the retained bundle; `npm run check:skill`
+checks exact reproducibility and runs in `npm test`. The helper entrypoint is
+`plugins/n8r-surface/skills/research/scripts/artifacts.mjs`; its host-facing
+[procedure](../../plugins/n8r-surface/skills/research/references/artifacts.md)
+and synthetic examples ship together. Bundled examples illustrate shapes, not
+findings. No helper is allowed to invent research or infer instance bindings.
+
+Save creates a new directory exclusively. Existing directories and symlink
+ancestry are refused. Parent directories must already exist. Files use private
+permissions. An I/O failure can leave an incomplete directory for inspection;
+it is never reported as success or overwritten on retry. Stable directory topology
+is required during synchronous operations; this is not a hostile-filesystem sandbox.
+The manifest detects accidental changes, not an attacker able to rewrite all
+files and hashes. No source file, service, credential or predecessor is modified.
+
+Privacy starts before source intake: use permitted sanitized projections and
+never print or stage raw settings. The helper rejects recognizable URLs, addresses,
+credential assignments and private paths, with fixed diagnostics that omit input
+values. This is defense in depth, not a guarantee that arbitrary names or opaque
+secrets can be recognized. Human/source review remains necessary. Safe configuration
+owner/key/location and product/role identity remain useful without setting values.
+
+## Baseline evidence
+
+On 8 November 2026, installed skill 0.1.9 was invoked through Codex CLI 0.166.0
+app-server with a synthetic assistant source and this request:
+
+> Use product.md to create a Capability Surface. Save the brief, research HTML and
+> checked structured Surface in this workspace. The skill must work standalone
+> without invoking n8r-surface CLI.
+
+It produced provisional brief/HTML/JSON/check files, explicitly reporting that
+contract validation was unavailable because no validator was bundled. This is
+an actual installed baseline, not an inferred test failure. Raw receipts and
+source/output bytes are retained privately in the selected vault's run folder.
+
+## Candidate rehearsal and checks
+
+A local marketplace installed candidate 0.1.10 in an isolated test home. Codex
+CLI 0.166.0 app-server used fresh ephemeral sessions, the existing ChatGPT sign-in
+model `gpt-6-astra` and Node 26.13.0. The first candidate run reached the existing workspace runner's
+120-second deadline while correcting a draft; no success was claimed. The
+follow-up used the same Host harness with a private 600-second turn deadline.
+This is agent rehearsal, not a new public acceptance-runner mode or desktop proof.
+
+The installed host then produced Capability, Bound and fresh-chat Bound-successor
+artifacts from supplied synthetic sources. It used the bundled helper without the
+product CLI. Independent readback checked saved bytes, source hashes, possible
+versus configured states, concrete targets, pinned Capability, stable identities,
+parent digests and retained human deferral. Prior files remained byte-identical.
+Synthetic sensitive URL/address/username/password sentinels were confined to the
+owned raw source fixture; scanning generated files and retained receipts found no
+copies. The host selected only permitted fields before retaining configuration.
+
+The synthetic fixture supplements the human task below with `instance.json`
+containing `instance`, `revision`, `modelService`, `configured` and sensitive
+sentinel fields. The interaction explicitly permits only the first four fields.
+The raw fixture is test input, not a retained production evidence store. The
+second source changes the model service identity; no researcher findings were
+prewritten by the developing agent.
+
+Focused checks cover standalone execution outside the checkout, Capability/Bound
+readback, missing references, orphan revisions, collisions, symlinks, edited HTML,
+privacy refusals, lost decisions, rewritten pinned dependencies, duplicate JSON
+members and value-free errors. Three independent review findings gained failing
+then passing regressions. A final error-path regression prevents the exported
+digest helper from echoing unsafe property names. All opaque extensions are
+refused in this bounded host; the general library's earlier contracts remain intact.
+
+The final installed candidate also saved a further fresh-chat successor selecting
+Model Service C. Independent checks confirmed source hashes, both parent digests,
+unchanged prior artifacts and the retained decision. All 20 installed files matched
+the candidate source. Final instruction digest:
+`sha256:a3480402aef42c93cb4d7e77fbf157b33dab6eaedb6b97f8ef1db1022cfaa58b`.
+Standalone helper SHA-256:
+`aec2dc355b5d33661ff7c3250a1a3edb3e31bf4ea22e614816c9593da37d3019`.
+The final sentinel scan covered 72 generated/retained files, excluding the owned
+raw source fixture and the initial isolated installation cache, with zero matches.
+
+Private run records retain installation/source file digests, interaction receipts,
+independent readback and preservation inventories. The final PR identifies the
+exact source revision and final test counts. Neither the first timed-out attempt
+nor fixture/package checks are reported as human acceptance. The broader
+unrelated-product journey and human acceptance remain #52.
+
+## Human verification task list
+
+Maintainer preparation: identify the installed 0.1.11 candidate and file digests,
+record Codex/model/Node versions, and supply an empty writable workspace containing
+`product.md` with this synthetic source. Use the
+[isolated installation procedure](workspace-installation.md) with the candidate's
+commit and version; it does not replace the normal desktop installation. A tester
+needs the identified skill available in their selected host.
+
+```text
+# Synthetic assistant
+Revision: fixture-1
+The assistant can send prompts to an OpenAI-compatible model API using HTTPS.
+MODEL_ENDPOINT is documented in config/example.env.
+No instance configuration is supplied.
+```
+
+- [ ] Open the prepared workspace in Codex, invoke the installed Researcher, and
+  ask: “Use product.md to create a Capability Surface. Save the brief, research
+  HTML and checked structured Surface in capability-001.” Open all returned
+  links. Expect the supported model-API connection, explicit gaps and no selected
+  instance target. There must be actual saved files and successful readback.
+- [ ] Supply a permitted summary: “For synthetic instance demo, configuration
+  revision 1 selects Model Service A for the model API. This establishes only
+  configuration, not runtime use.” Ask: “Save a Bound Surface in bound-001 using
+  this summary and the saved Capability. Record my decision to keep runtime
+  verification deferred.” Expect the same role relationship, a separate concrete
+  target, source evidence for configuration, and a separate human decision.
+- [ ] Start a fresh chat with the same workspace. Supply: “Configuration revision
+  2 changes that model API target to Model Service B.” Ask: “Reopen bound-001
+  and save a successor in bound-002 reflecting this change.” Open both revisions.
+  Expect stable role/component identities, updated binding, preserved decision,
+  exact predecessor reference and unchanged prior files.
+- [ ] Report **Pass / Fail / Blocked**, output links and the failing step if any.
+  IDs, dates and wording may vary. Broken links, unsupported bindings, leaked
+  values, lost decisions/history or success after a failed check are failures.
+
+Technical evidence checks belong to the maintainer: read each directory with the
+installed helper, verify source digests and consequential claims independently,
+compare predecessor/source hashes and scan all outputs and receipts for synthetic
+sensitive sentinels. Exit 0 plus `checked`/`saved-and-read-back` is required;
+exit 1 is failure. Retain owned trial outputs for review. Cleanup is a separate
+user decision and must never delete borrowed sources.
+
+This bounded agent rehearsal is distinct from human acceptance. Issue #52 retains
+the broader two-product journey, human corrections, usefulness and host acceptance.
+
+## Human-readable presentation (candidate 0.1.11)
+
+The 0.1.10 rehearsal exposed a usefulness failure: HTML listed contract fields,
+and the brief directed readers elsewhere for evidence. Candidate 0.1.11 renders
+a shared narrative in both formats: current picture, what changed, why it
+matters, evidence locators, human decisions and remaining unknowns. Impact is
+limited to the connection's documented purpose and configured selection; it does
+not invent business outcomes or runtime success. Conflicting claims remain visible.
+
+A previous target is compared only when the exact parent research record is in
+the bundle. Otherwise the report says that the comparison is unavailable. Full
+records, source coverage and hashes remain accessible in expandable HTML details.
+The report uses local styles, no scripts, remote fonts or network resources.
+
+Saved bundles now use manifest version 2 and HTML presentation 1. Research and
+Surface contracts and canonical digests do not change. The reader still accepts
+unchanged manifest-1 bundles and their original brief/HTML. Both presentations
+reject visible edits; updating a manifest hash alone cannot legitimize prose that
+disagrees with the embedded data. New HTML also checks its embedded Surface and
+dependency context against the accompanying files. Older 0.1.10 helpers cannot
+read the new presentation; install 0.1.11 before continuing it.
+
+### Short human check
+
+Prerequisite: the identified 0.1.11 candidate and an existing checked Bound
+successor and its predecessor, produced by the task list above. Keep the original
+files. In the same workspace, ask the Researcher:
+
+> Read bound-002 and its predecessor bound-001 using the bundled helper. Save the
+> same checked bundle with the new readable presentation in bound-002-readable.
+> Preserve all research and Surface data, decisions and original files. This is
+> a presentation copy, not another research revision. Show the HTML and brief.
+
+- [ ] Open the returned HTML. The configured target should be the first useful
+  statement. “What changed” should name the previous and current targets when
+  the exact parent research is retained.
+- [ ] Read “Why it matters” and “Evidence”. Expect the documented connection
+  purpose/integration, configuration-versus-runtime limit and source locators.
+  No new source findings or business/security assurances should appear.
+- [ ] Read decisions and unknowns, then expand technical details. The deferred
+  decision, unresolved questions and original checked data must remain available.
+- [ ] Open the brief. Expect the same substantive explanation without needing to
+  decode identifiers or open the JSON to discover the conclusion.
+- [ ] Report **Pass / Fail / Blocked**, the two output links and any unclear
+  wording. Visual usefulness requires human review, separate from data checks.
+
+Maintainer evidence: helper save/read must exit 0; compare canonical research,
+Surface and dependency data and byte hashes of all original files. Only HTML,
+brief and their new manifest may differ in the presentation copy. Retain the
+copy for review; no cleanup or registry publication is part of this task.
+
+### Presentation evidence and limits
+
+The copied standalone 0.1.11 helper re-rendered the previously generated Bound
+successor without new research. Save and independent read exited 0. Research,
+Surface and dependency data compared equal; Surface/dependency JSON bytes were
+identical, and all 29 files present before the presentation copy were unchanged.
+The new brief identifies the old/current targets, source locators and retained
+deferral. Raw receipts remain private. This is helper rehearsal, not a fresh
+installed-skill conversation or human usefulness acceptance. Browser policy
+blocked the local-file preview, so no screenshot or visual acceptance is claimed.
+
+Six presentation regressions cover data preservation, legacy reopening, visible
+edits, manifest downgrade, equal-label target identities and conditional/exclusive
+Capabilities. Independent review found the latter three issues before fixes;
+regressions demonstrated each failure, then passed. The complete suite has 201
+checks. Package preparation exposed stale version/digest expectations; those were
+corrected. Concurrent cross-runtime tests collided on a shared temporary build
+file; sequential rerunning passed. Broad usefulness remains the two-product
+skill journey in #52, followed by CLI integration and separate Labs work.
+
+## Two-product usefulness result
+
+The [installed-skill usefulness check](skill-usefulness-verification.md) exercises
+Capability, Bound and fresh-session revision on two pinned public source packs.
+Both passed independent readback and preservation checks on 0.1.11 without skill
+code changes. The record includes the initial test-instruction blocker and the
+corrected retry. The user accepted this bounded skill verification on 8 November 2026; acceptance
+is distinct from the agent rehearsal and does not imply an additional human run.