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

package/docs/n8r-surface/first-use-overview.md

@@ -0,0 +1,262 @@
+# First-use security overview, candidate 0.1.14
+
+Related to [#72](https://github.com/injectionator/n8r-surface/issues/72).
+This skill/plugin increment follows merged 0.1.13. It does not change the npm
+package version or authorize publication. Human acceptance remains pending.
+
+## Changed behavior
+
+A broad first source investigation should produce a brief that explains the
+application, its major areas and external integrations, consequential findings,
+coverage gaps and the next useful decision. The skill asks for evidence-backed
+findings and distinguishes supported options from intended choices, configuration
+and observed behavior. Narrow questions remain narrow.
+
+The HTML starts with a connected graph: each identified node appears once, with
+its directed relationships. Explicit, checked presentation hints group nodes
+inside the application, externally or as unclassified. Grouping records placement with its evidence basis (including user intent),
+not proof of deployed trust boundaries. Full edge
+conditions, exceptions, observations, evidence and investigation history remain
+below the overview. The brief links to that detail instead of repeating every
+relationship's generic uncertainty.
+
+The [hint contract](../../plugins/n8r-surface/skills/research/references/cyclonedx.md#overview-presentation-hints)
+is optional node metadata within Surface profile 1. Missing hints produce
+Unclassified placement; the renderer never guesses placement from inventory type.
+Older readers may ignore hints. Older saved BOMs remain readable, and no prior
+files are regenerated in place. The BOM remains the sole saved authority.
+
+The record is an architecture/research BOM, not a comprehensive dependency SBOM.
+Generic consumers may omit the profile's research state and possible paths.
+No runtime assessment, deployment automation or consumer compatibility is implied.
+
+## Baseline and verification status
+
+The supplied 0.1.13 first-use evaluation identified an opening dominated by storage
+mechanics, mixed inventory, repeated relationship rows/caveats and buried security
+implications. Read-only inspection of the retained private brief and renderer
+confirmed those presentation failures. The earlier product assessment is supplied
+baseline evidence; this increment does not claim to have repeated its research.
+Original private outputs are preserved and are not public fixtures.
+
+Focused regression checks failed against the previous renderer and now cover
+checked placement evidence, old/empty inputs, each identity and directed edge,
+cycles/parallel relationships, disconnected nodes, full names, linked findings,
+retained exceptions and inert source text. These checks establish bounded rendering
+and reference behavior, not the quality or truth of an investigation.
+
+The user-led 0.1.14 rehearsal and follow-up candidate checks are recorded
+[below](#follow-up-rehearsal), with exact identity limits. Browser visual acceptance
+remains pending. A prior local-file browser-policy refusal remains a blocker for
+that route; it must not be bypassed.
+
+## Human verification task list
+
+Maintainer preparation: provide the exact candidate commit and install it using
+[the tester setup](tester-candidate.md#install-the-pinned-codex-candidate), substituting that
+commit and expecting 0.1.14. Provide readable selected sources, Node 22/24/26 and
+a new writable output folder outside the source checkout. Keep earlier research
+out of the fresh chat; retain its bytes separately for comparison. The everyday
+installation need not be replaced for an isolated candidate rehearsal.
+
+- [ ] In a fresh chat with the candidate and source folder, ask:
+
+  > Explain this application's AI-relevant architecture and security implications.
+  > Save an initial Surface overview in the supplied output folder. Keep the first
+  > pass useful and bounded, and show me what to do next.
+
+  Expect simple links to the brief, map and journal, plus a useful continuation.
+  The first output may be a plan; inspect the latest completed research revision.
+- [ ] Open the brief. In your own words, explain what the app does, its major
+  internal areas and external integrations, a few consequential observations,
+  important unknowns and the next planning decision. Expect source/deployment
+  scope near the opening, with storage mechanics underneath. Missing evidence
+  must be explicit rather than replaced with plausible findings.
+- [ ] Open the HTML in a permitted browser. Expect a connected overview before
+  relationship details, each node once, readable names and visible arrow direction.
+  Follow a path to its details and a finding to its evidence. Inspect a condition
+  or exception; the summary must not hide its consequence. Unclassified placement
+  is acceptable where evidence is missing. Report blocked access without bypassing
+  host policy. The text inventory/details remain an alternative reading path.
+- [ ] Check coverage of identity, authorization, data handling, storage, secrets,
+  exposure and observability. Expect researched scope or explicit gaps, not an
+  assertion that every control is effective. Supported authentication options must
+  be distinguished from a chosen identity service, or honestly marked unresearched.
+- [ ] Ask:
+
+  > I want to describe an intended installation next. Help me choose model
+  > connections, identity, stores and enabled tools; record choices as intentions
+  > and tell me what configuration evidence would be needed later.
+
+  Expect useful choices/questions with no invented deployment or runtime results.
+  After making a choice, request a saved successor. Supply only its BOM and source
+  access to another fresh chat and ask “Continue this Surface.” Expect choices,
+  evidence and unresolved questions to recover, with earlier files unchanged.
+- [ ] Report **Pass / Fail / Blocked**, the candidate commit, output links, your
+  short explanation and any unclear/misleading part. Fail for fabricated findings,
+  lost evidence or nodes, unreadable graph or changed predecessors. Blocked means
+  access/runtime/browser prerequisites prevented the task. Names, graph size and
+  exact findings vary with the source. Retain outputs for review; cleanup only
+  the disposable trial folder after review, never the source or baseline.
+
+## Maintainer technical checks
+
+From the repository root with dependencies installed:
+
+```sh
+npm test
+npm run check:package
+```
+
+Both must exit 0. The package check installs temporary offline consumers and
+removes them; it does not publish. For a quick legacy-input compatibility check:
+
+```sh
+node plugins/n8r-surface/skills/research/scripts/surface.mjs check examples/researcher/surface-bom/initial.cdx.json
+```
+
+Expect exit 0, `checked`, five relationships and three entries. This is structure
+validation of synthetic input, not the tester's task or human acceptance.
+
+## Follow-up rehearsal
+
+The 13 November 2026 user-led chat with installed skill 0.1.14 exercised initial
+source research, Python-tool authority follow-up, requested deployment inspection
+and a runtime availability recheck. Private artifacts and transcript were reviewed
+without publishing them. The source was pinned; this was not a runtime security
+assessment. Candidate version was observed in the installed path and transcript;
+that version string alone does not establish an exact PR commit or bundle digest.
+
+The first completed brief contained 1,138 whitespace-delimited words; after the
+follow-ups it contained 2,651. Useful findings distinguished loading from calling
+Python tools, browser/backend network origins and retrieval data handling. The
+successors nevertheless retained an obsolete daemon blocker and retry action
+beside newer reachable-daemon evidence. Deployment-oriented next steps preceded
+confirmation that any deployment existed. A broad runtime inventory exposed
+unrelated metadata in tool output, although the saved evidence was aggregated.
+The user's final source-only clarification was interrupted before a save; it is
+unfinished work, not a failed save or ignored completed request.
+
+Readback found matching predecessor digests across six transitions and no broken
+internal HTML anchors in four completed-result views. These are bounded integrity
+checks, not source-claim validation, rendered-map acceptance or human approval.
+
+The follow-up keeps profile 1. Current views exclude superseded entries, while
+journals retain history. The brief bounds lists (12 nodes, 5 findings, 7 coverage
+items, 7 gaps, 1 action), links all additional items and preserves complete text
+for each displayed finding. Findings use reverse record order, not severity;
+actions prefer active entries, then record order. Guidance asks the researcher to
+consolidate overlapping findings, reconcile scope/gaps and choose one active
+source action. The 400–700-word target is editorial, not a truncation rule.
+Runtime filtering is agent guidance, not a new automatic redaction tool.
+
+### Successor results and exact candidate
+
+At code commit `92c1c0bca1e2adfcc2b134b0259ed8856f337bce`, Node 26.13.0:
+241 tests, exact skill bundle check, offline installed package/terminal rehearsal,
+Markdown lint 0.24.0, local links/fragments with lychee 0.24.2, citation validation
+with cffconvert 2.0.0 and diff whitespace checks passed. All 18 JSON example files
+parsed. Two new renderer regressions failed before implementation and passed after.
+The full suite caught omitted inventory types/IDs during shortening; restoring
+those fields passed the suite. Package verification first rejected the obsolete
+instruction digest; the reviewed digest was updated and the full package check
+passed. These checks do not establish research accuracy.
+
+A fresh-context agent invoked an isolated standalone candidate copy against a
+private copy of the prior BOM and the same source checkout. It received the
+source-only continuation task below, reread source entry points itself, reconciled
+scope and journal states, and saved revision 8. No live runtime was accessed.
+Independent readback found one active source action, deployment settings still
+unverified, matching predecessor digest and every prior annotation retained.
+Old runtime blockers/actions remained historical rather than current requirements.
+
+The agent's copied helper preceded the type/ID restoration (SHA-256
+`b7a1572bb6fee44093bb5dad4a9867001a864f506394c4d5e07ece15573b854f`).
+Its generated brief was 928 words. The exact committed helper was then copied
+independently, used to save the same agent-authored BOM against the same predecessor
+in a new directory, and read back: 976 words, no missing internal HTML anchors,
+same predecessor digest and retained annotations. Its SHA-256 is
+`3087fad27e2f38bde37a251e762cdead220dab2d3b30e07a1c37e7226613b79b`.
+No developer-prewritten findings were presented as Researcher output. The 976-word
+brief is substantially shorter than 2,651, but exceeds the editorial 400–700-word
+aim; list bounds alone do not ensure that target. Human readability acceptance
+remains open. This was isolated candidate invocation and helper readback, not a
+fresh installation into the user's everyday plugin registry.
+
+A separate fresh-context agent read a synthetic two-resource runtime response
+inside a local process and emitted only the selected target identity and an
+allowlisted state. Its command and readback were reviewed; unrelated names,
+images and paths were absent from tool output and the saved result. This checks
+one guidance scenario, not automatic redaction or all live runtime failure modes.
+No actual Docker daemon was accessed for this follow-up.
+
+The source rehearsal encountered the existing privacy guard's false positive on
+a paragraph separator serialized inside entry text, then an empty authored reason.
+It retained the historical text with spaces and supplied the missing reason;
+validation and save then succeeded. No guard was disabled or bypassed. Broader
+privacy-guard ergonomics are outside this increment. Private prompts, candidate
+file hashes, predecessor copy, agent outputs and readback reports remain in the
+local rehearsal vault, not in this public repository.
+
+These are agent rehearsals, not human Pass acceptance. Rendered browser usability,
+the intended-setup continuation and end-to-end runtime control behavior remain
+unproved. Keep the PR draft and issue #72 WIP.
+
+### Follow-up human tasks
+
+Maintainer preparation: install the exact updated PR candidate using the setup
+above. Supply a copy of an existing source-based Surface with historical blockers,
+its source checkout and a new disposable output directory. Retain the predecessor
+bytes. Do not supply credentials or use a production deployment for this check.
+
+- [ ] In a fresh chat, provide the saved BOM and source and ask:
+
+  > It is just a source checkout. Record that in the Surface, keep deployment
+  > settings marked as unverified, and show me the most useful source-level
+  > security investigation to do next. Save the successor in the supplied folder.
+
+  Expect a source-level next action without daemon startup or runtime inventory.
+- [ ] Open the new brief. Expect a concise current scope and one recommended
+  action. An old unavailable-daemon statement must not remain a current blocker
+  after newer evidence resolves it. Follow the history link to the old observation;
+  expect its original wording and provenance to remain. Deployment settings stay
+  unverified. Follow any additional-items link to the full detail.
+- [ ] For a separate synthetic inspection check, supply a JSON inventory with
+  one named target and one unrelated resource. Ask: “Using only this supplied
+  synthetic response, report whether the named target is running.” Expect only
+  the target's safe identity/status in tool output and saved evidence. Unrelated
+  names, images and paths must never appear in output. Do not access a live daemon.
+- [ ] Report **Pass / Fail / Blocked**, exact candidate commit, output links and
+  any confusing or stale text. Fail for lost evidence, changed predecessor bytes,
+  stale current blockers, mandatory runtime setup for source work, or unrelated
+  metadata in tool output. Blocked means missing source, candidate or output access.
+  Retain outputs until review; cleanup is limited to the disposable trial folder.
+
+Maintainer evidence check: independently compare predecessor bytes and generated
+manifest hashes. A helper validation exit 0 is required, but it is not human
+acceptance. Browser visual acceptance and the separate intended-setup journey
+remain pending until explicitly exercised.
+
+### User retest readback — 13 November 2026
+
+The user reported liking the outputs after the everyday marketplace installation
+was pinned to `6d68b9c4c717fb2c5efc78d02f16cf094c538a6d`. The installation
+record identifies all 25 plugin files and helper SHA-256
+`3087fad27e2f38bde37a251e762cdead220dab2d3b30e07a1c37e7226613b79b`.
+Positive feedback is recorded as given; it is not a formal Pass for every task.
+
+Independent readback of the private retest found two saved revisions. The final
+brief has 867 whitespace-delimited words, source-only scope, unverified deployment
+settings and one active source-level next action. Resolved runtime blockers are
+superseded and other deployment actions deferred. Both manifests match all four
+saved-file hashes; both predecessor digests match the supplied preceding BOM.
+Inherited annotations and component/service identities remain present, and both
+HTML files have no missing internal anchors. The candidate profile checker accepts
+the final BOM with 22 relationships and 57 journal entries under Node 26.13.0.
+These checks establish retained structure and current presentation text, not
+independent validation of every source claim or proof of all tool activity.
+
+The 867-word brief still exceeds the editorial 400–700-word aim. Browser visual
+acceptance, intended-setup continuation and runtime behavior remain unproved by
+this readback. No new research was performed or findings authored for this check.
+Private source details, outputs and installation paths remain outside this record.

package/docs/n8r-surface/getting-started.md

@@ -0,0 +1,74 @@
+# Research with n8r-surface
+
+The current local candidate opens a conversation. From the project folder you
+want to investigate, run:
+
+```sh
+n8r-surface
+```
+
+Tell it what you want to know. For example:
+
+```text
+Which AI services does this project connect to, and what is still unclear?
+```
+
+You can ask follow-up questions, correct a finding, or change the emphasis.
+There is no required research sequence. `/source PATH` at the opening prompt
+selects another local folder or file; otherwise it uses the current folder.
+Before research starts, you confirm sending source text and messages to OpenAI
+through your existing Codex ChatGPT sign-in. Source files stay unchanged.
+
+When you want to keep the result, type:
+
+```text
+save
+```
+
+The command prepares and checks the saved Surface, preserves your decisions and
+unknowns, and shows where to open it. You can keep talking afterward. Type `exit`
+when you want to leave.
+
+Next time, run `n8r-surface` again. Choose your saved work by its displayed number.
+The command remembers its source and model, opens a fresh conversation and checks
+for changed source evidence. Ask whatever comes next. Saving creates a successor
+and keeps earlier files intact.
+
+## Installation
+
+The conversation-first experience is a local candidate, not yet a public npm
+release. Follow the [local candidate installation](npm-release.md) or use the
+candidate already installed by your maintainer. Check the command in the same
+terminal where you will use it; npm global commands belong to the active Node
+installation.
+
+Prerequisites are Node.js 22, 24 or 26 and Codex CLI 0.166.0 signed in with
+ChatGPT. The command uses your configured Codex model. Existing vault settings
+are reused; a new installation asks where to save research once. Installation
+and upgrades preserve existing settings and research.
+
+The historical registry version `@n8r/surface@0.1.0-experimental.2` does not include
+this opening conversation. See the [release record](npm-release.md#verified-scoped-release).
+
+## Other ways to work
+
+Existing explicit commands remain available:
+
+```sh
+n8r-surface discover . --model gpt-6-astra
+n8r-surface --help
+```
+
+`reopen SAVED_FILE --source SOURCE` opens an existing note or Surface by path,
+including older files. Those placeholders represent your selected files; ordinary
+continuation through the opening saved-work list does not require them.
+
+`/save note` saves a Markdown working note. The explicit `discover` and `reopen`
+commands retain their original `/save` Markdown behavior; plain `save` saves a
+Surface. `/save surface` saves a current preview. A save request in the opening
+conversation can prepare the Surface for you, without a separate preview command.
+
+If a source has moved, select its new location with `/source PATH` before choosing
+saved work. If saved bytes were edited or damaged, the command preserves them and
+reports the conflict. Older saves without a recent-work entry can still be opened
+with `reopen`; saving them adds them to the list.

package/docs/n8r-surface/guided-journey-verification.md

@@ -0,0 +1,137 @@
+# Installed skill: freeform component exploration
+
+Related to [#17](https://github.com/injectionator/n8r-surface/issues/17).
+The user starts with a main component and brings other sources into the
+conversation as useful connections emerge. Suggestions help exploration; they
+are not mandatory steps or a component-selection wizard.
+
+## Task and boundary
+
+**Given:** an installed Researcher and only a selected LibreChat source folder.
+**When:** the user asks what connects to it, chooses a different branch from the
+recommendation, introduces Atlas and connector sources, saves Capability/Bound
+descriptions, then reopens and corrects their scope.
+**Then:** useful suggestions have source evidence, supported possibilities remain
+separate from selections and verified configuration, and saved successors retain
+identities, decisions, unknowns and exact predecessor references.
+
+The skill has no built-in knowledge of the user's Lab or repository layout. It
+may inspect only sources the user introduces. The test's connector files become
+available in a later turn; the originating repository is inaccessible to the
+Researcher. Shared source implementation does not establish a shared runtime.
+No service operation, provisioning, live API request or CLI/Labs implementation
+is part of this trial.
+
+## Installed 0.1.11 rehearsal
+
+Agent rehearsal on 9 November 2026 used the installed 0.1.11 plugin, byte-matched
+across all 20 files to merged commit
+`5eed2ac9a31933caa2ae306e4b407e327d147bf7`. Host: Codex CLI 0.166.0 app-server,
+ChatGPT sign-in, configured `gpt-6-astra`, Node 26.13.0, macOS. Fresh ephemeral
+sessions and explicit file permissions denied earlier receipts and the separate
+Lab repository. No inference credentials were copied.
+
+Initial input contained only the same pinned LibreChat README, database and
+OpenID source copies used in the [accepted two-product trial](skill-usefulness-verification.md).
+Later input added a limited historical operator excerpt and selected private
+connector source files. Their provenance and hashes remain in the private run
+inventory. The developing agent supplied conversational test-user choices and
+source copies; the installed Researcher produced the findings and saved bundles.
+This is an agent rehearsal, not a human rerun or a current deployment inspection.
+
+Observed sequence:
+
+1. Asked for LibreChat connections without naming other components. The reply
+   offered model, storage, identity, document/tool and telemetry branches, with
+   a suggested next investigation. It saved nothing when asked not to save.
+2. Chose storage instead of the recommended document path and reported Atlas.
+   The reply followed that direction and distinguished a user statement from
+   configured and exercised connections.
+3. Challenged source-read claims whose events appeared missing. Explicit Node
+   reads and hashes followed. Subsequent raw-transcript diagnosis established
+   that the event stream was incomplete; see the recording limit below.
+4. Introduced a historical storage note and private connector sources, then
+   switched to inference. The reply traced the connector/app-server boundary,
+   retained Atlas and deferrals, and excluded a separate assistant connection.
+5. Requested Capability and Bound bundles in successive turns. Both saved and
+   passed independent helper readback. User selections did not become verified
+   current bindings.
+6. Reopened in a fresh process, narrowed the Atlas selection to chat records
+   rather than uploaded files, and named retention/access controls as next work
+   without authorizing investigation. The saved successor retained those limits.
+
+Independent readback checked all three bundles, 36 source-hash references,
+8 stable nodes, 5 stable relationships, exact parent references and the exact
+Capability pin. All 24 files present before reopening remained unchanged.
+
+### Recording and runner limits
+
+The command-event stream omitted some nested shell calls. Initial review therefore
+mistook missing events for unsupported inspection. A fresh diagnostic using the
+same installed 0.1.11 retained a raw tool transcript: six shell calls and their
+returned results appeared there, while the event stream recorded only four. The
+raw transcript includes actual source reads. Missing command events alone cannot
+establish that a source was unread or that the Researcher invented an earlier read.
+The original ephemeral sessions cannot supply complete raw history retrospectively;
+that per-turn coverage limit remains explicit. Later recorded targeted reads and
+independent source checks substantiate the saved findings.
+
+The first reopen attempt reached the runner's 120-second limit without saving a
+successor. A fresh retry with a 600-second allowance completed and passed
+independent readback. The timeout is retained as Blocked, not artifact success or
+a skill defect. This allowance changed only a private copy of the existing runner.
+An optional full-thread read was unavailable for ephemeral sessions; the focused
+recording diagnosis used a fresh persistent session instead. The runner also
+warned that injected skill text was truncated; installed-file reads are recorded,
+and no complete injected-prompt claim is made.
+
+## Result and remaining limits
+
+**Agent rehearsal: Pass for the bounded journey and saved-output checks. Human
+acceptance: pending.** The skill offered evidence-backed branches, followed user
+redirection, incorporated later sources, preserved selections and deferrals, and
+saved/reopened checked artifacts. The developer did not supply its findings.
+
+No skill-code gap was established. Distributed skill 0.1.11 and its artifact
+helpers remain unchanged; no new version or release is proposed for delivery.
+The recording and timeout findings change how this rehearsal is interpreted, not
+product behavior. Keep complete tool transcripts when investigating read-coverage
+claims; event summaries alone are insufficient for a negative claim.
+
+This trial does not verify arbitrary APIs, current deployment settings, running
+connections, ChatGPT Work lifecycle, broad host compatibility or CLI/Labs
+integration. The Bound artifact appropriately keeps current bindings unknown
+while recording the user's Atlas and connector selections. Sources, private
+component identities, prompts, tool receipts, snapshots and readback results stay
+in the selected private vault; no private source bundle is published here.
+
+## Human verification task list
+
+Prerequisites: the identified installed 0.1.11 skill in a local Codex chat, Node.js
+22/24/26, readable user-selected sources and a writable research destination.
+Use the [installation guide](researcher-skill.md) for the pinned accepted revision. Record the installed version and host.
+
+- [ ] Start with only your main component folder. Ask: “Use n8r-surface Researcher
+  to explore LibreChat from this folder. What connects to it, and where would it
+  be useful to explore next? I have not chosen other components. Don't save yet.”
+  Expect optional evidence-backed branches, explicit unknowns and no save.
+- [ ] Choose a different branch from its recommendation: “Leave documents and
+  tools aside. We use Atlas for chat storage. What does that add, and what remains
+  unverified?” Expect a useful response without restarting a fixed questionnaire.
+- [ ] Introduce permitted connector sources: “Now explore inference from these
+  files. Retain the storage choice and deferred topics. The separate assistant
+  connection is outside this Surface.” Expect source-based connections and limits,
+  with no operation or search through unselected repositories.
+- [ ] Ask: “Save checked Capability and Bound descriptions here. Separate supported
+  possibilities, my choices, configuration evidence and unknown runtime use.
+  Read them back and show me the briefs.” Open both briefs and their evidence;
+  expect actual files and helper readback, not only a claim of success.
+- [ ] In a fresh chat, supply the Bound bundle and say: “Atlas is selected for chat
+  records only, not uploaded files. Retention/access controls are next, but don't
+  investigate yet. Keep my other choices and deferrals. Save a checked successor
+  without changing earlier files.” Expect the correction, retained identity and
+  history, and the requested stopping point.
+- [ ] Report **Pass / Fail / Blocked**, skill revision/host, the unclear or
+  unsupported claim if any, and links to the saved briefs. Keep private sources
+  and receipts private. Retain the research after the trial; no service cleanup
+  is needed because the task operates no services.

package/docs/n8r-surface/host-contract.md

@@ -0,0 +1,176 @@
+# Researcher host contract 0.1
+
+This is the integration boundary for the future shared Researcher instructions,
+not an implemented runner or Lab adapter. It builds on the
+[artefact contracts](contracts.md) and [shared cases](../../examples/researcher/README.md).
+The existing chat harness was the first skill host. The standalone CLI now has a
+bounded conversation adapter with [Markdown save/reopen support](save-reopen-verification.md).
+The current candidate additionally stages and saves one linked structured research/Surface
+pair; [its evidence](surface-revisions-verification.md) bounds that workflow. Lab adaptation remains later work. A Lab is optional, and AI runner selection is
+independent of the destination for results.
+
+## Version negotiation
+
+A host must identify its adapter version, the exact Researcher instruction
+revision, supported artefact contract versions and understood vocabulary/extension
+versions. The bundled #17 skill is version `0.1.8`, with
+[bounded package and behavioral evidence](researcher-skill-verification.md).
+It produces working notes, not validated contract artefacts. Broader host support
+requires the applicable trial; applications consume that revision
+rather than maintaining a separate copy of discovery knowledge.
+
+Reject unsupported core versions before modification. Report unrecognized
+vocabulary/extension meanings while retaining their data. Successful parsing does
+not imply that the host understands or can operate the selected composition.
+Use a separate migration with explicit losses when a host cannot preserve data.
+The original artefact remains recoverable.
+
+The proposed `urn:n8r:researcher:provenance` extension may record the instruction
+revision and adapter version used for a new revision. It must contain no credentials,
+local paths or copied chat history. Until #17 implements it, this is a reserved
+extension convention rather than a required field or proof of AI execution.
+
+## Capabilities supplied by a host
+
+The following operations specify behavior and inputs/outputs, not API/MCP method
+names. A host can implement them as local functions, attachment tools or application
+services. Missing capabilities must be explicit; the core must not fabricate
+access or a successful save.
+
+The Researcher's primary result is an AI Surface graph, not an application-wide
+configuration inventory. Source access includes user-selected code, documents,
+websites, prior research/definitions and permitted live observations. The
+[shared discovery guide](../../plugins/n8r-surface/skills/research/references/discovery-map.md)
+defines discover, continue and reconcile behavior across these combinations.
+Product libraries provide reusable navigation/evidence where available; no Lab
+or registry connection is required or implied.
+
+| Capability | Input | Result and required behavior |
+| --- | --- | --- |
+| Describe capabilities | No source inspection | Versions, available operations, bounded sizes, inference destination and save/download mode. |
+| Establish source scope | Explicit supplied directory/file/attachment selection | Opaque scope ID and allowed material; no ancestor traversal or implicit corpus scan. |
+| List/read source | Scope ID, relative reference, requested range | Text, exact source/version/digest, inspected range and excluded/unreadable/truncated coverage. No source execution. |
+| Find related knowledge | Explicitly available library and product/source scope | Applicable guides, research and definitions with identity/revision/coverage; no implicit scan or union of different deployment selections. |
+| Read web/live evidence | Selected URL/system/environment and graph question | Available connector/API/browser/computer observations with location, time and nonsecret results. Host-supported human sign-in, read-only inspection, no credential copying or bypass of denied access. |
+| Invoke inference | Selected runner/model, instructions, bounded conversation/tool outputs | Response/tool proposals or explicit unavailable/error; no silent account/provider fallback. |
+| Ask human | Consequential question with current evidence/options | Answer, deferred answer or unavailable interaction; unresolved work stays in the record. |
+| Read artefact | Explicit artefact/revision selection | Original bytes, parsed contract status and exact byte-conflict token; do not render unvalidated imported HTML. |
+| Create artefact | Valid new artefact and explicit destination | Created identity/revision and actual location/download, or conflict/error; never overwrite an existing identity silently. |
+| Revise artefact | Proposed successor and expected byte token | Recheck current bytes, validate parent, retain previous bytes and commit atomically; reject conflicts. |
+| Continue | Accepted record plus newly established source access | Preserve IDs, findings, decisions, questions and extensions; record new evidence in a successor. |
+| Export selection | Reviewed selected definition and encoding | JSON/YAML preserving supported meaning, or explicit rejection; no implicit deployment or publication. |
+
+Reading is not permission to upload. Before inference, the host identifies the
+provider and source transmission scope and obtains the user's authorization for
+that discovery session. The implemented bare-startup overview does not inspect or transmit sources;
+future source selection must have a specified scope. No status subcommand is planned.
+The runner sees only authorized source extracts and context selected by the host;
+source instructions are data, and tool arguments remain subject to deterministic
+path, version, size and operation checks.
+
+Live inspection uses existing host capabilities; this contract adds no browser,
+admin client or runner. Inspect enablement and connection targets needed by the
+graph, not all settings. The user completes private authentication directly.
+Stored configuration, observed effective configuration, reachability and exercised
+behavior remain separate. Record access/identity limits and sanitized evidence;
+do not manufacture a source digest when the host provides no stable source bytes.
+An authorized settings read does not authorize a configuration change or a
+connection test. Document each real host path before claiming it was verified.
+
+## Continuation and persistence
+
+The current standalone increment uses numbered Markdown working notes and an
+experimental host metadata footer. It requires `/save`, preserves predecessor
+bytes, and reacquires explicit source/transmission permission on `reopen`.
+This is a bounded implementation of working-note continuity, not the structured
+HTML/Surface contract below. See [SAVE-01](command-outcomes.md#save-01-save-reopen-and-continue).
+
+A portable continuation needs the current accepted HTML record, exact referenced
+source identities/revisions, and the intended output or selected definition.
+The record carries inspected coverage, findings, alternatives, human decisions,
+notes and open questions. A new host must reacquire actual source access; a saved
+source locator or prior conversation does not grant it.
+
+A host unable to read a referenced source must retain its evidence and mark the
+new inspection as unavailable. It cannot claim to have rechecked that evidence.
+A host unable to persist returns downloadable artefacts and says so. It must not
+claim that they were saved to a corpus or Lab.
+
+Use byte hashes for optimistic concurrency, including edits that leave logical
+data unchanged. Parent logical digests bind the accepted revision's meaning.
+Keep both the edited bytes and accepted predecessor during reconciliation. A
+successful write reports the actual revision/location; a failed or interrupted
+write must leave recoverable work. The local persistence implementation is #16.
+
+A host can have a mutable draft and deliberate named baselines in addition to
+artefact snapshots. It must map these explicitly: an artefact snapshot is not
+necessarily a product release or named Surface version. Import identity collisions
+require exact-match reuse or an explicit fork/migration; do not merge by label.
+
+## Candidate structured pair host
+
+The restricted `surface_draft` tool stages content in memory. The host fills
+revision envelopes and exact research references, validates both artefacts and
+shows a deterministic preview. `/save surface` publishes exactly that preview as
+`research.html`, `surface.json` and `manifest.json` in a new numbered directory
+under `surfaces/<source-slug>/`. The manifest is host storage/provenance metadata,
+not a model contract. Its hashes detect byte edits; they do not authenticate authors.
+
+Either saved member reopens the pair after validation and renewed transmission
+consent. The complete context is bounded to 512 KiB independently of individual
+file limits. Original notes and accepted pair revisions remain unchanged. Source
+availability comparisons retain historical evidence. Manual HTML/data edits fail
+closed; this increment does not implement automatic reconciliation or arbitrary
+multi-record imports. Directory topology must remain stable during synchronous
+operations. See [SURFACE-01](command-outcomes.md#surface-01-generate-save-and-revise-a-partial-surface).
+
+## Lab requirements review
+
+The #15 review compared this boundary with the separate application's relevant
+saved-definition, discovery, revision and import/continuation requirements.
+This public report records alignment and integration obligations only; private
+application prompts, code, operational data and internal source locations are
+not reproduced. No application implementation or compatibility trial was run.
+
+| Requirement | Contract decision | Later consumer work or gap |
+| --- | --- | --- |
+| Offline saved work independent of equipment | Research and selected definitions need no Lab or running target. | Adapt application storage and selection without applying setup. |
+| Explicit context/ownership | Artefact IDs carry no authority to create/configure Lab resources. | Map application ownership explicitly; do not infer it from graph containment or rewrite this model's Lab/Experiment semantics. |
+| Sources and attachments | Opaque scopes plus versioned evidence; portable locators grant no access. | Supply attachment/source adapters and permission checks. |
+| Human-guided research | Decisions/questions are durable; unsupported interaction remains visible. | Implement session questions and compare behavior on shared cases. |
+| Stable identity and immutable evidence | Exact revisions/digests, stable finding/node/edge IDs, separate runtime evidence. | Map local snapshot and deliberate version labels; retain prior Run references. |
+| Partial import and continuation | Unknowns/conflicts/opaque extensions are preserved; no operational readiness claim. | Build an importer that previews limitations and rejects unsupported loss. |
+| Reuse of one Researcher core | Version negotiation includes instruction and artefact versions. | Consume #17's identified instruction revision and run both discovery and import cases. |
+
+The application may use different persistence and ownership conventions. This
+profile describes component graphs. The current model has Lab → Experiment →
+Setup ownership: the Experiment requests setup directly from its Lab, which owns
+resource configuration and local bindings. Historical ownership records remain
+historical. Consumer lifecycle/authority mapping remains an explicit integration
+obligation, not something passing JSON/YAML tests resolves. See the proposed
+[recreation handoff](recreation-handoff.md).
+
+## Acceptance for later adapters
+
+Use the [command outcome specification](command-outcomes.md) to define initial
+state, actual human interaction, state changes and independent readback. The
+cases below must be exercised through the relevant host, not fulfilled by the
+developing agent outside it. The installed CLI's complete path is E2E-01;
+LibreChat requires its own E2E-02 rehearsal before a product-support claim.
+
+1. Research Lumen and Harbor separately from the supplied sources, keeping the
+   10/25 conflict and unknown authentication/model facts.
+2. Ask the human about selection; do not turn every supported option into an edge.
+3. Import the incomplete Harbor r1 record without inventing authentication or
+   requiring a deployed system. Establish access to the second source and continue
+   the same finding into a new revision.
+4. Detect the edited Lumen HTML, preserve it, resolve the human correction and
+   produce a successor without changing the old record or losing extensions.
+5. Produce the selected graph, retaining shared components, cycles, parallel edges,
+   requirement references, decisions and exact research revision links.
+6. Import/continue the result in a named Lab version and document supported meanings,
+   unsupported data and any losses. Compare facts and decisions, not prose wording.
+
+Steps 1–5 require real runner/harness trials in #17 beyond #15's deterministic
+fixtures. Step 6 is later application work. Until those trials run, alignment is
+a design review and byte/value checks are only contract verification.