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

package/docs/n8r-surface/workspace-verification.md

@@ -0,0 +1,350 @@
+# Workspace verification status
+
+Issue [#41](https://github.com/injectionator/n8r-surface/issues/41) adds identity
+and safeguards to expected README-based baseline behavior. Code/test success is
+not closure: installed-product scenarios now pass within the recorded limits;
+overall PM acceptance, review readiness, merge and release remain separate.
+
+## Installed 0.1.8 baseline — 8 November 2026
+
+Two separate local desktop chats exercised setup and readiness. The installed
+plugin's files matched source commit `3effc41bf7e8466651722b7b4c64035f862b1901`;
+exact installation provenance was unknown. SKILL.md SHA-256:
+`cd38dcd85f67ca962f06d86178009308aea527c9783fa0e0a3f834f783f1ebf4`.
+Host version was 26.1023.51421, build 22530. The PM reported GPT-6 Astra medium;
+the chat API did not independently expose the per-run model.
+
+Create took one turn and about 36 seconds. It created README and a research
+placeholder, with no identity record or research. PM feedback: “No problems.”
+Fresh-chat readiness took one turn and about 30 seconds, recovered saved purpose,
+accurately stated that no findings existed and offered useful next actions without
+research. No separate reopen satisfaction rating was supplied. Content bytes were
+unchanged; a host Git checkpoint subtree appeared. The destination already had
+`.git` at its first product listing, so a strictly empty initial state is unproved.
+
+The future identity contract was absent, as expected in 0.1.8, not a regression.
+Outcome against that new contract was not met; useful interaction and saved-context
+continuation were observed strengths. Other baseline scenarios were untested.
+Fresh chats were observed, but enforced denial of history/filesystem access was
+not established. Private transcripts and machine paths are retained outside this
+public repository; this summary contains only sanitized observations.
+
+## Candidate 0.1.9
+
+Source changes implement the helper and skill guidance. All planned product
+scenario outcomes passed: empty/missing creation, repeat, fresh-chat recognition,
+both adoption choices, all refusals and moved identity. The chronological entries
+below preserve earlier incomplete attempts and their status at the time.
+No PM product acceptance, merge or release is claimed. Normal installation was
+subsequently replaced with explicit PM authorization, as recorded below. CLI/Labs workspace integration and other hosts remain unverified.
+
+## Scenario and evidence mapping
+
+| Canonical scenario | Deterministic supporting evidence | Product/experience evidence |
+| --- | --- | --- |
+| Create; missing/empty | `tests/workspace.test.mjs`: actual files, record readback and no scaffolds | Candidate empty and missing destination creation passed |
+| Repeat with note | Same suite: byte-preserving reuse and unknown fields | Candidate PM repeat passed; independent hashes unchanged |
+| Fresh reopen; moved identity | Same suite: separate process and moved folder inspection | Fresh-chat reopen passed after destination clarification; independent moved-folder chat passed |
+| Adoption question and both choices | Same suite: no-write refusal, in-place and alternative destination | Both adoption choices passed |
+| Malformed/conflicting/unsupported | Same suite: complete before/after snapshots | All three installed-product refusal trials passed |
+| Interrupted setup | Same suite: publication failure and no-overwrite guard | Technical evidence only |
+| Installed helper availability | Same suite: copied helper with no checkout dependencies; package smoke | Installed 0.1.9 reads and helper execution verified in product chats |
+
+Run `node --test tests/workspace.test.mjs` or the full `npm test` from the repo
+root. These tests own temporary folders and remove them. Publication failure is
+injected at the filesystem boundary; this is not a real machine crash trial.
+The [human checklist and rubric](workspace-human-check.md) retain exact prompts,
+readback, ownership and separate outcome/experience reports. All canonical
+Gherkin is in [the feature file](../../tests/acceptance/skill-workspace.feature).
+
+## Implementation checks
+
+On macOS with Node.js 26.13.0, the full `npm test` passed 139 tests, including
+nine workspace checks. `npm run check:package` passed both legacy archive names
+and their offline installed-command rehearsals. The expanded installed helper/terminal checks passed on Node 22.23.4, 24.22.2
+and 26.13.0 for both legacy archive names. The full 139-test suite also passed
+on Node 22 and 24. An initial parallel matrix run collided on the existing
+`dist/obsolete-candidate-check.js` fixture in two Node 24 distribution tests;
+the serial rerun passed. No product fix was required for that orchestration error.
+Markdownlint 0.24.0, lychee 0.24.2 offline links/fragments, cffconvert 2.0.0,
+Python fixture/workflow tests (24), shell syntax and skill frontmatter validation
+passed. A fresh independent code review found no actionable findings and reran
+the nine helper tests. These are technical checks, not PM acceptance.
+
+The initial helper test failed because it was absent; eight behavioral checks
+then failed against placeholder exports before implementation. The first full
+implementation exposed a macOS temporary-directory alias in executable detection;
+using the real script path fixed the copied-helper check. Failed test output remains in the implementation chat evidence. No fixture was silently repaired to claim a product pass.
+
+## Identified installed candidate — 8 November 2026
+
+Candidate commit: `3cb08f59a4a932121bdd1c742fbac724d12a6d74`, plugin `0.1.9`,
+[draft PR #42](https://github.com/injectionator/n8r-surface/pull/42).
+Codex CLI 0.166.0 fetched this exact commit through the Git repository marketplace.
+Clean installation and upgrade from baseline `3effc41` were exercised in separate
+isolated homes. Every one of the 14 plugin files matched the committed source by
+relative filename and SHA-256. Both manifests and the installed list reported
+`0.1.9`, enabled. A synthetic workspace outside the installations remained
+byte-for-byte unchanged. The normal registration/configuration and baseline
+plugin bytes were unchanged during these isolated trials.
+
+The PM then explicitly authorized switching the normal installation to this
+pinned candidate. Its original registration details were retained privately;
+marketplace removal, pinned registration and plugin installation all exited 0.
+The normal installed entry is enabled `0.1.9`, and all 14 files again match the
+candidate. This is installed-byte evidence; desktop fresh-chat loading was pending at installation; the create trial below now verifies it.
+
+SKILL.md SHA-256: `91abc353f4e0dea663a81decd5eaba6d72470c32b432b904e684c1a3b1092b3b`.
+Complete file-map SHA-256: `de5d16d92f714f2f8ea900266078db8e113f6116d78ee4c98e68dcab8a696180`
+(sorted relative-path → SHA-256 JSON, compact separators, UTF-8). The full map,
+Git/CLI receipts, original registration, test logs and retained baseline evidence
+are stored in the private task inventory, outside tracked files.
+
+The prepared fixtures began as empty destinations or explicit synthetic
+adoption/refusal inputs. No successful workspace was seeded for the creation
+trial. The PM created the product chats; the implementation agent inspected their
+receipts and independently read saved files. All planned outcomes have now been
+exercised. The first reopen attempt omitted its target and is retained below;
+explicit-target continuation passed, followed by an independent moved-folder chat.
+Overall PM acceptance remains separate from these observations. Fixtures and a
+final private evidence copy are deliberately retained; no cleanup, merge or release.
+
+## PM create trial — 8 November 2026
+
+**Outcome: Pass for the observed create operation. Experience: Pass.** The PM
+reported “Worked fine.” One fresh product chat completed in one turn (18.978
+seconds) without questions or technical rescue. Its tool receipts show reads of
+the installed `0.1.9` skill and workspace reference, then the installed helper's
+`setup` invocation with the supplied destination and purpose; exit 0. The helper
+path was in the installed plugin cache, not the developer checkout. All 14
+installed file hashes still match the identified candidate.
+
+The prepared destination was empty before the trial. Independent readback found
+only `.n8r/workspace.json`, with exact format `n8r.workspace/1`, a valid generated
+UUID v4, folder-derived nonempty name and supplied purpose. All pre-existing
+fixture entries and file hashes were unchanged. The final response linked the
+actual workspace, identified format/ID and purpose, accurately separated app
+attachment, and offered a next research action without starting it. The visible
+tool trace contains no source fetch, credential request or global-setting write.
+A complete global-settings before/after snapshot was not collected for this trial.
+
+| Experience criterion | Verdict and observed evidence |
+| --- | --- |
+| Orientation | Pass: final response links location and identifies completion and next action. |
+| Necessary questions | Pass: no repeated authorization or unnecessary setup questions. |
+| User effort | Pass: one prompt, no schema choice, manual setup or technical rescue. |
+| Honest boundaries | Pass: completion matches independent files; attachment explicitly separate. |
+| Scope | Pass: setup only; no research in the tool trace or saved output. |
+
+This verifies loaded installed bytes and the create interaction, not the complete
+issue. The chat's working directory was an existing user folder while the prompt
+explicitly selected the separate empty destination; the requested boundary was
+honored. A separate chat does not prove enforced history/filesystem isolation.
+Host/model were not independently remeasured for this trial. Private chat receipts,
+full metadata, hashes and PM feedback are retained in the task evidence inventory;
+no raw transcript or machine path is published here.
+
+After create readback, the coordinator added the documented synthetic user note
+exclusively and captured a new before-inventory for repeat setup. That preparation
+is distinct from product output. Repeat, fresh reopen, move, missing destination,
+both adoption choices and refusal product trials remain pending. No repair,
+cleanup, merge or release occurred.
+
+## PM repeat-setup trial — 8 November 2026
+
+**Outcome: Pass. Experience: Pass.** The PM reported “Looks good.” In the same
+product chat, the user selected the installed Researcher and asked to set up the
+same workspace again. One turn completed in 10.978 seconds. The tool receipt
+shows the installed `0.1.9` helper invoked against the original destination;
+exit 0. No repeated confirmation or technical rescue was required.
+
+The response recognized the same saved ID, format, name and purpose, linked the
+workspace, and kept research and app attachment separate. Independent comparison
+against the inventory captured after synthetic-note preparation found exact
+agreement: no added/deleted entries and no changed file hashes, including both
+identity metadata and the note. This verifies preservation, not merely an
+assistant statement that files were unchanged.
+
+All five experience criteria pass for this turn: clear orientation, no unnecessary
+questions, no user repair burden, accurate completion/attachment statements and
+setup-only scope. The private evidence inventory retains the full tool receipt,
+before/after hashes and PM judgment. A read-only snapshot has been retained for
+the next fresh-chat reopen trial. Reopen, move, missing destination, adoption and
+refusal product trials remain pending; the issue and PR remain open/draft.
+
+## Additional same-chat readiness check — 8 November 2026
+
+The user supplied a readiness response matching the saved identity and purpose.
+Its actual tool receipt belongs to the original setup chat, so this does **not**
+exercise fresh-chat reopen. Retain it as a successful read-only readiness check;
+the fresh-session scenario remains pending, not a product failure.
+
+One turn completed in 12.477 seconds. The installed `0.1.9` helper ran `inspect`
+against the selected workspace and exited 0. Independent full inventory/hash
+comparison found no changes to metadata or the synthetic note. The response
+identified readiness, accurately separated attachment and offered a next action
+without research. Visible experience criteria were met; no separate PM satisfaction
+rating was supplied for this turn. The private receipt and verdict retain the
+same-chat limitation explicitly. No repair or fixture reset was performed.
+
+## Fresh-chat attempt without the target location — 8 November 2026
+
+A distinct product chat received the readiness question without the prepared
+workspace path. Its current folder was the earlier user-selected baseline folder,
+not the candidate workspace. The installed `0.1.9` skill/reference were loaded;
+the helper inspected that current folder and returned exit 3 (nonempty,
+unrecognized). The assistant reported that state and asked for a destination
+choice. No mutation command appears in the receipt.
+
+Fresh reopen is **Blocked for this attempt: the intended workspace was not made
+available as the selected target**. This is not evidence that the saved identity
+could not be recognized. Independent readback confirms the actual candidate
+workspace and synthetic note remain byte-for-byte unchanged. The 21.996-second
+trial and missing-location precondition are retained privately rather than
+silently relabeled as a pass. No fixture repair or product change was made.
+The new chat can receive the explicit target and perform read-only recognition;
+creation in the unrelated current folder is not needed for this scenario.
+
+## Fresh-chat reopen after destination clarification — 8 November 2026
+
+**Outcome: Pass for fresh-chat recognition with the explicit destination.** In the
+separate readiness chat, the user supplied the saved workspace path and requested
+inspection without initialization. No setup conversation or expected identity was
+supplied. The installed `0.1.9` helper ran `inspect` on that exact destination;
+exit 0. This turn took 12.697 seconds. The earlier missing-location attempt remains
+part of the trial evidence; this was not a successful first-turn reopen.
+
+The response recovered the original ID, format, name and purpose from the saved
+workspace. It offered a useful next research action while distinguishing readiness
+from source access, prior findings and app attachment. Independent complete
+inventory/hash comparison confirms unchanged metadata and synthetic note, with
+no added/deleted entries. No initialization, research or technical repair occurred.
+The visible experience criteria were met after destination clarification; the PM
+supplied the response but no separate satisfaction rating for this turn.
+
+The create → repeat → fresh-chat recognition path now has installed-helper tool
+evidence and independent state readback. A distinct chat is observed; enforced
+denial of broader history/filesystem access remains unproved. Host/model limits
+remain as recorded above. This does not complete issue #41: moved-folder identity,
+missing destination, both adoption choices and malformed/conflicting/unsupported
+product refusal trials are still pending, as is overall PM acceptance. Automated
+coverage for those cases is supporting evidence, not a substitute. PR remains
+draft; no merge, release or cleanup.
+
+## PM missing-destination creation — 8 November 2026
+
+**Outcome: Pass. Experience: Pass.** The PM reported “looks good.” A separate
+product chat loaded installed `0.1.9` and its workspace reference, then ran the
+bundled helper's `setup` at the explicitly supplied missing destination; exit 0.
+One turn took 20.101 seconds, without additional questions or technical rescue.
+
+The preparation inventory recorded this destination as absent. Independent
+readback now finds only `.n8r/workspace.json`: exact supported format, a valid
+UUID v4 distinct from the first workspace, folder-derived name and supplied
+purpose. The final response matches that readback, links the location and keeps
+research and attachment separate. Existing first-workspace metadata and note
+hashes remain unchanged. The five visible experience criteria are met. Private
+receipts, inventories and PM feedback are retained. Adoption fixtures were also
+rechecked: each still contains only its unchanged synthetic note. Their product
+trials, refusal cases and moved-folder recognition remain pending.
+
+## PM in-place adoption — 8 November 2026
+
+**Outcome: Pass. Visible experience criteria met; no separate PM rating supplied.**
+The installed `0.1.9` helper first returned exit 3 for the nonempty unrecognized
+fixture. The assistant asked for the destination choice. Independent inspection
+before the PM answered found exactly the original note, with unchanged bytes and
+no metadata. That first turn took 21.636 seconds.
+
+After the PM said “Initialize here,” the installed helper ran `setup --adopt`
+against the same destination; exit 0, 11.461-second turn. Independent readback
+verified the reported UUID v4, supported format, folder-derived name and supplied
+purpose. Only `.n8r/workspace.json` and its parent directory were added; the
+original note is byte-for-byte unchanged. The response links the location and
+separates research/attachment. No repeated permission or technical rescue occurred.
+Both turn receipts and the before-choice/after-choice inventories are retained
+privately. The alternative-choice fixtures remain untouched and inventoried for
+the next trial. Alternative adoption, refusal and move trials remain pending.
+
+## PM alternative-folder adoption — 8 November 2026
+
+**Outcome: Pass. Visible experience criteria met; no separate PM rating supplied.**
+The installed helper returned exit 3 for the second nonempty unrecognized fixture;
+the assistant asked for a destination choice (18.840-second turn). Before the PM
+answered, independent comparison confirmed the original note/folder unchanged and
+the alternative destination still empty.
+
+The PM chose the alternative path. The installed `0.1.9` helper ran ordinary
+`setup` there without `--adopt`, exited 0, and completed in 10.476 seconds.
+Independent readback verified the reported UUID v4, supported format,
+folder-derived name and retained purpose. Only identity metadata was created in
+the alternative; the original folder and note remain exactly unchanged. The
+response identifies the chosen destination and keeps research/attachment separate.
+Both receipts, choice-boundary inventory and final readback are retained privately.
+All three refusal fixtures were rechecked against their initial inventories and
+remain unchanged for independent product trials. Refusals and moved-folder
+recognition remain pending; no merge, release or cleanup.
+
+## PM refusal trials — 8 November 2026
+
+**Outcome: Pass for each expected refusal. Visible experience criteria met;
+no separate PM satisfaction ratings supplied.** Each independent product chat
+loaded the installed `0.1.9` skill/reference and invoked its bundled helper with
+an ordinary setup request at the selected fixture. All returned exit 2:
+
+| Fixture | Observed explanation | Turn duration |
+| --- | --- | --- |
+| Malformed JSON | Invalid workspace JSON; another folder or separate repair assessment. | 19.458 seconds |
+| Conflicting `.n8r` file | Metadata conflict; another folder or separate repair assessment. | 23.887 seconds |
+| Unsupported format | Unsupported workspace format; another destination or repair assessment. | 17.353 seconds |
+
+Independent before/after comparisons found exact agreement for every directory
+entry and file hash in all three fixtures. No initialization, repair, migration,
+downgrade or deletion occurred; the assistant made no success or research claim.
+These are passing refusal scenarios, not blocked test runs. Receipts, inventories
+and criterion-level verdicts are retained in the private evidence inventory.
+
+For the final move trial, the coordinator renamed the inventoried disposable
+first workspace to a new folder name, preserving all metadata and note bytes.
+The old path is absent and the new path is recorded privately. This is fixture
+preparation, not product behavior; installed-product recognition after the move
+remains pending. No borrowed/user-owned baseline folder was moved or changed.
+
+## PM moved-folder recognition — 8 November 2026
+
+**Outcome: Pass. Visible experience criteria met; no separate PM rating supplied.**
+A new product chat received the moved destination, with no original ID or setup
+conversation supplied. It loaded installed `0.1.9` and the workspace reference,
+then ran the installed helper's `inspect` against that path; exit 0. One turn
+took 20.379 seconds. The response recovered the original identity and saved name,
+retained the purpose/format, linked the new location, and offered a concrete next
+research prompt. It separated metadata readiness from prior research, configured
+targets and app attachment.
+
+Independent complete inventory/hash comparison with the pre-move snapshot
+confirms unchanged metadata and note bytes; the old path remains absent. All 14
+installed plugin files still match candidate `3cb08f5`. Private receipts,
+criterion verdicts, snapshots and a final fixture copy are retained with explicit
+ownership; the live disposable fixtures are deliberately retained too. No user
+baseline folder or Labs work was moved or cleaned up.
+
+## Completion boundary and current checks
+
+All planned product scenario outcomes passed within this host/environment scope.
+The PM explicitly rated creation, repeat and missing-destination interaction
+positively. Later responses meet the observable experience rubric, but supplying
+those responses is not recorded as blanket acceptance. Overall PM acceptance and
+review readiness are still pending; PR #42 remains draft and issue #41 open.
+
+Known limits remain: fresh chats do not prove enforced denial of history or broad
+filesystem access; host/model were not remeasured per candidate run; global-state
+preservation is supported by tool traces rather than a complete system snapshot.
+Interruption is covered by injected filesystem failures, not a machine crash.
+Other hosts and CLI/Labs workspace integration remain unverified.
+
+Local Markdown, pinned offline link/anchor and diff checks passed after evidence
+updates. In CI run `42470396419`, all three Node jobs, fixtures/tooling and Markdown
+passed; the local-links job failed downloading the pinned checker (curl exit 22)
+before checking any links. Its release asset exists. This is not a passing CI
+link check; the final branch run must be checked separately. No workflow or product
+change was made to conceal the failed download.

package/docs/n8r-surface/workspace.md

@@ -0,0 +1,83 @@
+# Surface workspace v1
+
+The issue #41 candidate adds standalone workspace setup and read-only recognition
+to the existing Researcher skill. A workspace is a user-owned folder with only
+`.n8r/workspace.json` initially. It needs no vault, Git repository, source checkout,
+Lab, credentials or app attachment. Research and content folders are lazy.
+
+The [bundled workspace reference](../../plugins/n8r-surface/skills/research/references/workspace.md)
+defines the record and interaction rules used by the installed skill. The
+[shared module](../../plugins/n8r-surface/skills/research/scripts/workspace.mjs)
+is the authoritative validator and filesystem implementation. Plugin removal or
+upgrade does not own or remove user workspaces.
+
+## Public consumer boundary
+
+Import the bundled ESM module using Node.js 22, 24 or 26. It uses built-ins only:
+
+```js
+import { inspectWorkspace, setupWorkspace, validateWorkspace }
+  from './plugins/n8r-surface/skills/research/scripts/workspace.mjs';
+
+const state = inspectWorkspace(selectedDirectory); // read-only
+// Only after an explicit setup request; adopt only after an initialize-here choice.
+const created = setupWorkspace(selectedDirectory, { purpose: 'Investigate LibreChat' });
+const validation = validateWorkspace(JSON.parse(savedText));
+```
+
+`selectedDirectory` and `savedText` are supplied by the host. The return value has
+`status`, `message`, `directory` when available, and `record` only for supported
+metadata. The helper's [result table and script interface](../../plugins/n8r-surface/skills/research/references/workspace.md#interpret-the-result)
+apply equally to importers. Imports do not run the script interface. There is no
+npm export alias or new `n8r-surface` CLI command for this module in this slice.
+
+Host adapters must preserve the distinction between inspection and authorized
+setup, and between an explicit setup request and consent to adopt a nonempty
+folder. They must consume this module rather than reimplement filesystem rules.
+The module cannot verify conversational authorization: that is the caller's duty.
+CLI/Labs integration and compatibility are not verified.
+
+## Persistence and limitations
+
+Identity uses `n8r.workspace/1`, a generated UUID v4, a nonempty display name and
+optional purpose. The exact supported record is distinct from plugin and AI
+Surface Model versions. Unknown fields confer no authority and are preserved by
+read-only reuse. Rename/move preserves ID; copying a workspace copies its ID and
+is not a new-identity operation. No rename, copy, repair or migration API is added.
+
+Setup writes a complete temporary record, flushes it, publishes it with an atomic
+no-overwrite hard link, removes that temporary link, and reads the result back.
+If publication fails, setup reports failure and retains staging evidence; a
+later request refuses incomplete `.n8r` contents. An interruption after publication
+may leave a complete valid identity and staging file; recognition reads the
+identity and never deletes the staging file. It cannot accept partial JSON.
+
+This targets ordinary local macOS/Linux filesystems supporting hard links.
+Unsupported filesystems report an I/O failure, without a weaker overwrite fallback.
+Destination and metadata symlinks/nonregular files are refused. Ancestor aliases
+may resolve normally; this is not an adversarial filesystem sandbox. Concurrent
+writers, malicious path replacement and power-loss durability are outside scope.
+No network, credentials or global settings are used. Read-only here means no
+intentional writes; operating-system access times and host checkpoints are separate.
+
+## Intent and evidence
+
+**State X:** an identified installed skill, a selected writable destination and a
+fresh product chat. **Input Y:** “Help me set up an n8r workspace here for
+investigating LibreChat. Set it up only; do not start researching yet.”
+**Outcome Z:** one valid identity record, a useful next action, no research or
+unrelated configuration; repeat and fresh-session inspection preserve identity
+and all existing bytes.
+
+[Canonical Gherkin](../../tests/acceptance/skill-workspace.feature),
+[human walkthrough](workspace-human-check.md) and
+[verification status](workspace-verification.md) distinguish deterministic checks,
+installed-product rehearsal and PM acceptance. Gherkin is manually runnable; no
+framework is installed.
+
+Skill instructions, helper and references ship together in plugin `0.1.9`; both
+manifests match. The repository marketplace points to that same subtree and has
+no separate version field. The npm package version remains unchanged. The existing
+CLI instruction-bundle revision guard is aligned so packaging does not break;
+its restricted runner gains no workspace tools. Future consumer releases must
+identify the bundled helper revision and rerun the same contract checks.

package/examples/researcher/README.md

@@ -0,0 +1,100 @@
+# Synthetic Researcher acceptance cases
+
+These fictional products and documents exercise the
+[experimental 0.1 contracts](../../docs/n8r-surface/contracts.md). They are not
+LibreChat findings, AI-generated discovery results or a working integration.
+No inference, credentials, network access or running target is needed to check them.
+
+Lumen Desk is a fictional AI support-summary application. Harbor Archive is an
+independent fictional document/event archive. A synthetic human selects a proposed
+composition after researching both. The sources establish possible interfaces;
+payload compatibility and effective configuration remain unverified.
+
+| File | Case |
+| --- | --- |
+| [Lumen guide](sources/lumen-guide.md), [settings](sources/lumen-settings.md) | Conflicting batch limits of 10 and 25; inference model unknown. |
+| [Lumen r1](lumen-r1.research.html) | Initial research; archive/identity selected, callback deferred. |
+| [Pending manual edit](lumen-manual-edit.pending.html) | Deliberately invalid visible edit; embedded data remains r1. |
+| [Lumen r2](lumen-r2.research.html) | Human-reviewed callback selection, preserving findings and opaque extension data. |
+| [Harbor interface notes](sources/harbor-api.md) | Independent product with unknown authentication. |
+| [Harbor r1](harbor-r1.research.html) | Useful incomplete research from one source. |
+| [Harbor authentication note](sources/harbor-auth.md) | Second supplied source establishes an OIDC option. |
+| [Harbor r2](harbor-r2.research.html) | Continuation keeps the authentication finding's identity and records a human selection. |
+| [Selected JSON](composed.surface.json), [selected YAML](composed.surface.yaml) | Same partial graph, referencing the exact r2 records. |
+
+Open a research HTML file in a browser to read its findings and inspect its embedded
+data. The data owns all facts; rendering is a derived view. These checked fixtures
+are inert, but arbitrary imported HTML must be validated before trusted rendering.
+
+The separate [Capability and Bound examples](descriptions/README.md) exercise the
+JSON-only `0.2` description contract. They do not convert these selected `0.1`
+definitions into deployments.
+
+For the revised #50 inspection, use the [shared relationship 0.3 examples](relationships/README.md).
+They put purpose, integration mechanism, safe config references and evidence on
+the edges in both Capability and Bound descriptions.
+
+## Selected composition
+
+```mermaid
+flowchart LR
+    Lumen[Lumen Desk] -->|documents| Harbor[Harbor Archive]
+    Lumen -->|audit events| Harbor
+    Harbor -->|callback| Lumen
+    Lumen -->|uses identity| Identity[Shared identity service]
+    Harbor -->|uses identity| Identity
+    Lumen -->|uses inference| Inference[Inference service]
+```
+
+The graph has shared identity, a cycle, identified parallel edges and node/edge
+attributes. All edges are declared only. The identity service's product and
+inference version remain unknown. Configuration/secret requirements are explicit
+local references without credential values. Attributes exercise known, unknown,
+omitted, redacted, absent and out-of-scope states. The conflicting batch limit is
+unknown in the selected definition and points back to both research claims.
+
+The example vocabulary `urn:n8r:vocabulary:researcher-example` version `0.1` has
+node terms `application`, `service`, `inference-service` and relationship terms
+`sends-documents`, `sends-audit`, `notifies`, `uses-identity`, `uses-inference`.
+These mean precisely the labeled roles/connections above, with no hidden protocol
+or lifecycle behavior. They are not a general ontology or a consumer capability.
+
+## Manual-edit case
+
+The pending file changes only the visible callback-decision reason. Its original
+embedded decision remains deferred. `readResearchHtml` must reject it as an
+HTML/data conflict. It must not silently choose the old embedded data or assume
+that visible prose establishes a structured decision.
+
+The synthetic review resolves the intended change: include callbacks in the desired
+composition, while retaining compatibility gaps. Lumen r2 records that selection,
+its author/time/reason and a human note, then regenerates the visible projection.
+Its parent digest pins r1; both earlier and pending files remain available.
+This demonstrates a reviewed result, not an implemented automatic reconciliation
+or persistence command.
+
+## Run the checks
+
+From the repository root, with a supported Node.js and npm:
+
+```sh
+npm ci
+npm test
+```
+
+Dependency installation uses the npm registry. The tests themselves are offline.
+They check source-byte hashes, internal references, exact external revisions,
+HTML/data agreement, rejection of the pending edit, successor lineage, unknown
+values and JSON/YAML equality. Semantic assertions verify the competing limits,
+new authentication evidence and selected graph structure. These checks do not
+verify an AI Researcher, facts about a real product or Lab compatibility.
+
+The future #17 runner and external skill must use these same cases, including a
+second source and human correction, and compare facts/choices/gaps rather than
+exact generated wording. Later Lab import/continuation must retain incomplete
+records, IDs, versions, provenance and extensions, and report unsupported meanings.
+
+Machine-readable fixtures and their rendered research HTML use
+[Apache-2.0](../../LICENSE). The synthetic source documents and this guide use
+[CC-BY-4.0](../../LICENSE-DOCS); credit AI Surface Model contributors. All material
+was created for these fixtures; no third-party product documentation is included.