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

package/docs/n8r-surface/recreation-handoff.md

@@ -0,0 +1,117 @@
+# From a Surface description to another user's Lab
+
+**Status: proposed consumer contract, not an implemented Lab adapter.** A Surface
+can supply a reusable structural description: component roles, connections,
+interfaces, selected configuration, constraints and required bindings. A recipient
+supplies their own resources, accounts and credentials. Successful research or
+import does not establish that the recipient's setup works.
+
+There is one AI Surface Model. A **Lab contains Experiments**; an **Experiment
+owns its desired setup** and requests resource configuration directly from its
+Lab. The Lab owns configuration authority and local bindings. See the
+[concepts](../../spec/README.md) and [host contract](host-contract.md).
+
+## What travels and what stays local
+
+| Material | Portable content | Recipient responsibility |
+| --- | --- | --- |
+| Product guide | Applicable product/fork/revision, capability map, source navigation and gaps. | Check applicability; alternatives are not automatic selections. |
+| Research | Evidence, scoped decisions, contradictions, coverage and lineage, where publication is permitted. | Preserve inherited evidence as inherited; recheck what the new task needs. |
+| Selected definition | Exact revision, stable graph IDs, directed connections, interfaces, constraints and requirements. | Select or explicitly adapt the composition; preserve the original and record changes. |
+| Recreation material | Versioned artifact/recipe references, prerequisites, clean-data initialization and supported checks. | Establish availability and adapter support before applying anything. |
+| Local bindings | Requirement names can travel; secret values, original accounts, deployment addresses and resource identities do not. | Allocate local identities and resolve each requirement under the recipient Lab's authority. |
+| Observations and Runs | Permitted historical evidence can travel with its original attribution. | Produce new effective-setup and Run evidence; source success is not recipient proof. |
+
+Do not publish private research merely because a product guide would be useful.
+A reusable guide can be derived from publishable product sources independently.
+An unknown value stays unknown; a withheld value is redacted. Neither means absent.
+
+## A concrete partial LibreChat composition
+
+This table is a **synthetic planning example**, not a generated validated Surface
+or a claim about a particular deployment. It describes requirements rather than
+copying another user's bindings.
+
+| Stable role | Connection or constraint to retain | Recipient input or unresolved decision |
+| --- | --- | --- |
+| Chat application | Identified LibreChat artifact/configuration revision; user request and response path. | Compatible artifact, host resources, private access and local application identity. |
+| Account store | Selected local-account sign-in path and required authorization boundaries. | Fresh accounts and secrets; account policy; evidence of the selected path. |
+| Conversation store | Application persistence through a compatible MongoDB connection. | Recipient database/resource, least required authority, private binding and clean-data policy. |
+| Inference route | Application → any required connector/service → selected model; retain protocol and behavior constraints. | Identify the complete route, compatible service/model, local authorization and adapter. A product/subscription label alone is insufficient. |
+| Optional RAG service | If selected, file-processing connection and required service interface. | Real endpoint, compatible service, authentication, embedding/index/storage choices and caller permissions. An example URL supplies none of these. |
+
+The [controlled reconciliation trial](researcher-reconciliation-trial.md) changes
+one RAG endpoint declaration. It cannot fill the rest of this table. Even a
+nonempty URL leaves effective loading, overrides, authorization, reachability and
+successful use unproved. Removing that declaration does not remove RAG from the
+product's supported capabilities.
+
+Shared services retain one resource identity with separate dependency edges.
+A dependent Lab must not acquire lifecycle ownership merely by using a service.
+Internal API roles need not become separate deployed processes. New recipient
+instances get local identities linked to the reusable definition's stable roles.
+
+## Proposed n8r-labs handoff
+
+1. **Intake:** preserve the exact supplied bytes, format/version, revision and
+   lineage. Identify whether the input is research, a selected definition or an
+   observation. Reject unsupported interpretations; retain opaque material.
+2. **Assess:** map supported meanings to the named consumer version. Report each
+   requirement as satisfiable, unresolved, unsupported or deliberately adapted.
+   Missing mandatory information blocks applying the affected setup, while the
+   partial description remains useful for review.
+3. **Bind:** the recipient chooses their own accounts, credential references,
+   resource identities and compatible alternatives. Prepare an inspectable plan
+   naming resources to reuse, create or configure and expected effects.
+4. **Prepare:** the Experiment requests its exact saved setup revision from its
+   Lab. The controller checks ownership, resource authority, concurrent work and
+   revision freshness, then dispatches only supported adapter operations.
+5. **Verify:** independently read back effective nonsecret configuration and
+   attribute actual interactions to recipient resources and definition revision.
+   Record failures and gaps without silently replacing the intended composition.
+
+This is a requirements sequence, not a list of implemented commands. The
+Researcher remains an investigator; imported prose and recipes do not grant
+operational authority. No new runner, provisioning engine or credential-copying
+mechanism is introduced here.
+
+## Format and adapter decisions still needed
+
+The current skill emits Markdown research. The separate experimental
+[`n8r.surface/0.1` contract](contracts.md#selected-surface-definition) can express
+selected graph nodes, declared relationships and secret/resource/configuration
+requirements. Its validators check bounded structure and references, not source
+truth or a consumer's understanding. Deployment bindings and Run formats are
+outside that profile.
+
+Before claiming n8r-labs support, identify the consumer revision and implement a
+versioned mapping for the chosen vocabulary. Preserve unsupported nodes, edges,
+attributes, requirements and evidence or report explicit losses. A consumer that
+can retain JSON bytes or understand a narrow endpoint/model setting has not thereby
+understood the full graph. Do not silently relabel one format as another.
+
+Still required: shared vocabulary/profile selection; supported artifact and recipe
+references; recipient binding and authority rules; configuration precedence;
+missing-resource behavior; clean-data initialization; effective-setup readback;
+and clear handling of substitutions. Existing helpers can satisfy individual
+steps only after their actual scope is checked.
+
+## Smallest meaningful consumer proof
+
+For a named consumer build, begin with a permitted saved definition, an identified
+recipient Lab/Experiment, suitable resources and the recipient's own authorization.
+Record the exact user interaction and setup revision. Import/inspect must leave
+resources unchanged, expose unsupported meanings and retain the source bytes.
+
+Then resolve bindings and run the proposed preparation through the Lab. For the
+selected chat path, obtain an actual response through the recipient application,
+read back the saved conversation where persistence is required, and retain the
+route, effective setup and result evidence. If RAG is selected, exercise a bounded
+synthetic file-processing/retrieval case separately. Confirm the original setup
+and evidence remain intact; clean up only trial-owned resources.
+
+Wording, generated IDs and response text may vary. Wrong target attribution,
+missing mandatory bindings, silent graph losses, copied source credentials or
+claims based solely on successful parsing fail the proof. If prerequisites or
+adapters are unavailable, record the exact blocked step. No such consumer trial
+is claimed by this documentation increment.

package/docs/n8r-surface/researcher-discovery.md

@@ -0,0 +1,157 @@
+# Researching an AI Surface graph
+
+The graph is the primary result: AI-relevant components, connections, evidence
+and gaps. Inspect configuration to establish or explain those connections,
+not to inventory every setting in an application. The shared
+[skill discovery guide](../../plugins/n8r-surface/skills/research/references/discovery-map.md)
+contains the navigation rules and product-knowledge approach.
+
+Use the [short installation and first-trial route](researcher-skill.md#research-01-investigate-and-continue).
+These instructions describe candidate 0.1.8; see the
+[verification record](researcher-skill-verification.md) for exercised paths and
+unverified live inspection. No Lab or new runner is required.
+
+The [controlled LibreChat trial](researcher-reconciliation-trial.md) supplies a
+repeatable baseline/change/readback check. The [recreation handoff](recreation-handoff.md)
+explains how a selected description can guide recipient-owned Lab setup and what
+still needs consumer verification.
+
+## Three related views
+
+There is one AI Surface Model. The Researcher distinguishes three useful views
+of a system rather than treating every discovered possibility as a running edge:
+
+| View | Question | Typical evidence |
+| --- | --- | --- |
+| Possible connections | What can this product/version support, and where should we look? | Product guide, applicable docs and implementation evidence; alternatives remain alternatives. |
+| Declared setup | Which components/connections does this particular composition select? | Identified repository/build/configuration, intended choices and a selected Surface definition. |
+| Observed running graph | Which instances and connections are actually configured/enabled here? | Dated deployment binding and applicable effective settings/observations; stored settings alone have a narrower meaning. |
+
+For a synthetic example, a product supports 50 possibilities, a setup selects 25,
+and a running deployment enables 10. The repository may still contain the code for
+all 50; configuration selection is distinct from implementation support. Which
+of the enabled connections were actually exercised needs its own evidence.
+Do not turn an enablement read into a successful connection or usage claim.
+
+The generic discovery guide is broader than any product: it supplies questions
+and navigation, not a giant selected Surface containing every possible edge.
+Reusable product knowledge narrows it to applicable capabilities. A selected
+definition describes a composition; deployment observations remain linked,
+dated evidence and do not rewrite that definition. These views often narrow the
+possibilities, but plugins, external configuration or services may also introduce
+connections outside the supplied checkout. This is not guaranteed set inheritance.
+
+Component identity and evidence connect the views. The model's existing
+[definition/observation distinction](../../spec/README.md#configuration-and-evidence)
+continues to apply; no new schema or hierarchy is introduced here.
+
+## Skeleton brief and linked evidence
+
+Ask for **Skeleton Surface v0.1** when the useful result is a brief of key nodes
+and relationships. Its security focus is where an integration could intercept
+LLM and actual tool calls, with what powers and gaps. The
+[bundled procedure](../../plugins/n8r-surface/skills/research/references/skeleton-surface.md)
+defines what stays in the brief and what belongs in linked evidence. It works
+from source-only capabilities or supplied setup evidence; bindings are not a
+prerequisite. The larger research descriptions are not minimum-size templates.
+
+This is a named Markdown working profile, not a universal schema or a new CLI
+command. Detailed and recreation profiles remain future work. Follow
+[SKELETON-01 and SKELETON-02](researcher-skeleton-check.md) to exercise the brief
+and a successor after a declaration change through the installed skill.
+
+## Revision lifecycle
+
+1. **Research the available sources.** Save a scoped description of capabilities,
+   roles and relationships, with evidence and gaps. A required database role or
+   supported MCP/vector-store connection need not have a selected instance.
+2. **Configure through a Lab in a later task.** An Experiment selects its desired
+   setup and asks the Lab to configure resources. The intended consumer behavior
+   is to record successor setup/binding revisions as changes happen, with the
+   request, result and effective-state evidence distinguished. Failed or partial
+   configuration must not be recorded as successful. Automatic recording belongs
+   to future Lab integration, not this skill or an implemented API in this repo.
+3. **Reconcile changes made outside the Lab explicitly.** Saved descriptions do
+   not watch external changes. Run the Researcher against current identified
+   sources/settings and the prior description; save an authorized successor with
+   the differences and their evidence. A changed settings file establishes a
+   declaration, not that a running process loaded it or a connection succeeded.
+
+For example, a later setup may bind a required database role and route inference
+through a selected proxy. Retain the role IDs and record resource mappings in
+linked binding records, keeping secrets outside research. A successor can refer
+to the same definition with new bindings; changes to composition or intended
+settings require a successor definition. A newly described proxy may itself need
+an identity and relationships. Do not disguise a topology change as just an address.
+
+Profile version changes when output rules change. Surface/setup revisions change
+when the described composition, knowledge or bindings change. Preserve predecessors
+and the exact definition/effective setup used by earlier Runs. Discovery time does
+not prove when an external change took effect. The Researcher describes and
+reconciles; it does not install or reconfigure the target.
+
+## Graph discovery, reconciliation and live evidence
+
+Use the same installation and notes convention. These are conversational intents,
+not new CLI commands. The skill supplies instructions; each host supplies actual
+file, web, API and computer access. A missing capability remains a visible gap.
+
+**DISCOVER-01: start with the available material.** In a local chat with a selected
+source folder (or supplied docs), select the skill and ask:
+
+> Map the AI-relevant components and connections in these sources. Reuse any
+> applicable guides, research or Surface definitions I supplied. Start with a
+> shallow graph and follow its useful gaps. Include configuration only when it
+> explains the graph. Save working notes and show me the result.
+
+Expect a graph or edge table, scope/revision, source references, separate supported
+alternatives and selected connections, and missing evidence. Code-only, docs-only,
+prior-model-only and mixed inputs are valid starts. A bounded finding of no AI
+relevance is valid; inventing an AI node or treating a package list as the Surface
+is a failure. Open the note and follow a representative edge's source reference.
+
+**RECONCILE-01: compare a supplied Surface.** Provide the prior JSON/notes and the
+current identified sources, then ask:
+
+> Compare this Surface with the current sources. Preserve the original. For its
+> AI-relevant nodes and connections, show supported agreements, differences,
+> additional discoveries and unknowns with evidence. Separate capabilities,
+> intended setup, declared settings and runtime observations. Save the comparison.
+
+Expect claim-by-claim research, including unsupported format/vocabulary meanings,
+without a silent rewrite or universal validation claim. For example, code that
+supports OIDC does not prove it is enabled; a current staging file declaring it
+disabled is not evidence that a live process loaded it. Missing model fields do
+not mean absent capabilities. Open the comparison and confirm the original bytes
+are unchanged. Validated generated Surface JSON remains outside this increment.
+
+**LIVE-01: inspect an available admin page/API.** Prerequisites: a user-selected
+test environment and admin location, an appropriate account, supported host tools
+and permitted read access. Use the host's supported sign-in handoff if required;
+enter credentials directly there, not in chat. Then ask:
+
+> Inspect the selected environment's identity settings read-only. Establish
+> whether OIDC is enabled and which identity service it connects to. Record
+> nonsecret evidence for that graph edge; do not reveal credentials, change
+> settings or test the connection. Save a dated observation in my working notes.
+
+Expect the actual environment, time, page/section or API operation, nonsecret
+enablement and target where visible, and explicit unknowns elsewhere. Read the
+relevant view/fields again to verify the observation and open the saved note.
+Distinguish stored settings from runtime-effective settings. Do not treat masked
+credentials as valid credentials or a settings read as successful OIDC login.
+No product is assumed to expose all settings in an admin UI. A missing tool,
+blocked route or unavailable field is a blocker/limit, not permission to bypass
+access or an assertion that the connection is disabled.
+
+For these chat interactions there is no process exit code. Success is the
+specified visible result plus saved-byte readback; wording and identities vary.
+No target settings should change. Keep notes; no target cleanup is expected.
+Inspect only graph-relevant fields, avoiding secret reveals, raw config exports
+and screenshots containing credentials. Real admin UI/API acceptance must be
+recorded separately from synthetic cases or source-only trials.
+
+ChatGPT Work access depends on the actual browser/session and account permissions;
+it does not inherit all sign-ins automatically. See the official
+[Work browser/session boundaries](https://learn.chatgpt.com/docs/enterprise/chatgpt-work-local-security#browser-sessions-and-existing-sign-ins),
+reviewed 4 November 2026. The skill cannot grant or broaden host access.

package/docs/n8r-surface/researcher-prepared-check.md

@@ -0,0 +1,117 @@
+# Try the prepared example
+
+Test whether Researcher can describe an AI system, save its findings and notice a
+small change while preserving earlier work. This uses fictional documents and a
+pretend configuration; no application needs to be installed or started.
+
+## Before you start
+
+Open your local vault in your file browser. You need a local chat app
+with **n8r-surface Researcher 0.1.7 already installed**, access to the prepared example in this repository,
+and permission to save files in your vault. If access or the skill is missing, record
+**Blocked** and what is missing. You do not need to diagnose the installation.
+Follow the [fresh-context guidance](researcher-vault.md#start-with-fresh-context) before
+the first prompt in each test chat.
+
+## Tasks
+
+- [ ] **1. Make your working copy.** In the `n8r-surface` repository, open
+  `examples/researcher-vault/`. Copy the whole `chat-service` folder into `runs/`
+  in your local vault (create `runs/` if needed) and rename the copy `check-001`. If that
+  name already exists, choose the next unused number and use it throughout these
+  steps. Open the copy: it should contain `scope.md`, `system.md` and `current.env`.
+
+  **Look for:** `DOCUMENT_SEARCH_URL=` in your copy of `current.env`, with nothing
+  after the equals sign. Leave the shared files in `examples/researcher-vault/` unchanged.
+
+- [ ] **2. Start the investigation.** Open a fresh local chat in your
+  vault folder and select **n8r-surface Researcher**
+  (`n8r-surface:research`). Paste this, adjusting `check-001` if needed:
+
+  > Use only scope.md, system.md and current.env in runs/check-001 as source
+  > material. Describe the main AI-related components and connections. Explain
+  > what the product supports, what the supplied settings say, and what is still
+  > unknown about a running system. Cite the files you used. Save your findings
+  > as a new numbered note under runs/check-001/notes and give me a link to
+  > open it. Create the notes folder if needed.
+  > Use the installed skill; do not consult other chats, memories, projects,
+  > the web or the test walkthroughs.
+
+  **Look for:** a readable map or connection table, source references, unknowns
+  and an openable saved note. Open the note and confirm it matches the chat. It
+  should connect the browser, chat application, model gateway and conversation
+  store, and describe optional document search. The supplied settings give no
+  document-search address; they do give a model-gateway address. Running services,
+  the language model and authentication details remain unverified or unknown.
+
+  Check **Recommended next steps**: each item names the next investigation, why
+  it matters and a source location or missing evidence from which to resume.
+
+  Make a copy of this first note named `first-note-backup.md` directly in your
+  `check-001` folder. Keep the original in `notes/` for the next chat.
+
+- [ ] **3. Change one setting.** Open your working copy of `current.env` in a text
+  editor. Change `DOCUMENT_SEARCH_URL=` to
+  `DOCUMENT_SEARCH_URL=https://search.example.test`. Save and reopen the file.
+  Leave every other line and file unchanged. This is a placeholder address;
+  do not visit it or run the settings file.
+
+  **Look for:** the new address in your working copy. The shared example should
+  still have the empty value.
+
+- [ ] **4. Ask Researcher to compare.** Start another fresh local chat in your
+  vault folder and select Researcher again. Give it the original saved note from
+  `notes/` by attaching the file or pasting its path, then paste:
+
+  > Read the saved recommendations and continue within these supplied sources.
+  > Compare my saved findings with scope.md, system.md and current.env in
+  > runs/check-001. Tell me what changed, what stayed the same and what is
+  > still unknown, with references to the evidence. Save the comparison as a new
+  > numbered note under runs/check-001/notes and give me a link. Keep the
+  > original note unchanged.
+  > Use the installed skill and these supplied sources only; do not consult
+  > other chats, memories, projects, the web or the test walkthroughs.
+
+  **Look for:** a second file with a different name. Open it: document search
+  should now have a declared target of `https://search.example.test`. The model
+  gateway address, other components and unresolved questions should carry forward.
+  Whether any service is running or working remains unknown. A claim such as
+  “document search now works” fails this check. Reopen the first note and compare
+  it with `first-note-backup.md`; its contents should be unchanged. The successor
+  should update **Recommended next steps**, explaining resolved items or blockers
+  and where to resume. It must not silently copy recommendations made obsolete by
+  the changed settings.
+
+- [ ] **5. Check the setup explanation.** In the chat, ask:
+
+  > In the current AI Surface Model, who owns an Experiment's desired setup,
+  > and who prepares the resources it needs?
+
+  **Look for:** the Experiment owns its desired setup and asks its Lab directly;
+  the Lab configures resources and supplies local bindings. The current chain is
+  **Lab → Experiment → Setup**.
+
+## Report the result
+
+Keep the run folder for review. Record this for yourself, or send it to the person
+who assigned the test:
+
+> Result: Pass / Fail / Blocked
+>
+> App used and Researcher version shown in the chat:
+>
+> Run folder, first note and comparison note:
+>
+> Task number and what happened, if anything differed:
+
+**Pass:** every task produced the expected result. **Fail:** a task ran but gave a
+wrong result, lost earlier work or failed to save a file. **Blocked:** missing
+access or setup prevented a task. Different wording, supported extra findings
+and different note numbers are fine. Copy the relevant response or error; you
+need not diagnose it. These are chat interactions, so there are no command exit
+codes to check.
+
+This is a document-based rehearsal of the workflow. It does not establish code
+discovery, a working service or Lab recreation. For real source exploration,
+[try another repository](researcher-repository-check.md), or use the deeper
+[LibreChat declaration trial](researcher-reconciliation-trial.md).

package/docs/n8r-surface/researcher-reconciliation-trial.md

@@ -0,0 +1,149 @@
+# Controlled LibreChat declaration reconciliation
+
+This procedure tests whether the installed Researcher can find a graph-relevant
+configuration difference, preserve prior research and distinguish declarations
+from runtime evidence. It uses **Markdown research**, not validated Surface JSON.
+The configuration fixture is synthetic; the inspected implementation is actual
+LibreChat source. No target application or service is changed or started.
+
+## Teammate checklist
+
+For a first check with the skill already installed, start in the
+[local vault guide](researcher-vault.md). It contains a prepared fictional
+example and a walkthrough for investigating another chat-system repository.
+Each run keeps its working files and saved notes under `runs/` in the selected vault.
+
+This page retains the deeper **LibreChat source** trial. Its recorded evidence
+applies to the source revision below, not to the vault's fictional example.
+
+## Preparation for the LibreChat trial
+
+Use an installed skill, a permitted LibreChat checkout and a fresh test folder.
+The first shell block below creates the three configuration input files. Keep
+expected results outside Researcher's source folder, and record versions and
+file-preservation checks alongside the saved outputs. The earlier agent rehearsal
+and hashes are in the [verification record](researcher-skill-verification.md#controlled-declaration-trial-014).
+Human acceptance remains separate from that rehearsal.
+
+## State X and expected outcome
+
+Prerequisites: the [installed skill](researcher-skill.md), persistent local files,
+Python 3, and a permitted LibreChat checkout. The exercised source revision was
+`e1dfc10449ff713faffacd60273fddcfe2c0a698`. Identify any other revision and recheck
+its semantics before using the same expectation. Existing private/dirty files
+remain excluded. Prior graph research may be supplied, with its scope preserved.
+
+The selected trial composition is `trial:librechat-rag-declaration`. Its initial
+partial file explicitly sets `RAG_API_URL=`. The sole changed value becomes
+`https://rag.example.test`. Both are declarations that are never loaded into a
+process. Other settings and deployment overrides remain unknown.
+
+The expected graph difference is a declared target for the existing RAG role.
+Product support stays unchanged. Neither the empty value nor the example URL
+establishes deployed enablement, reachability, embedding or successful retrieval.
+Keep this expectation separate from the Researcher's task input.
+
+The source documents the key in
+[`.env.example`](https://github.com/LibreChat-AI/LibreChat/blob/e1dfc10449ff713faffacd60273fddcfe2c0a698/.env.example#L802-L814).
+The [file-processing implementation](https://github.com/LibreChat-AI/LibreChat/blob/e1dfc10449ff713faffacd60273fddcfe2c0a698/api/server/services/Files/VectorDB/crud.js#L20-L95)
+checks the URL before requests and uses it for `/embed` and `/documents` operations.
+These are source claims at that revision, not observed application calls.
+
+## Baseline, change and readback
+
+From the **LibreChat checkout root**, record identity and prepare a disposable
+input folder. Commands below do not load the environment files or contact a URL.
+
+```sh
+git rev-parse HEAD
+git status --short
+codex --version
+codex plugin list --marketplace n8r-surface --json
+trial_dir=$(mktemp -d "${TMPDIR:-/tmp}/n8r-rag-trial.XXXXXX")
+python3 - "$trial_dir" <<'PY'
+from pathlib import Path
+import sys
+root = Path(sys.argv[1])
+text = '# Task-owned partial LibreChat declaration; never loaded into a process.\nRAG_API_URL=\n'
+(root / 'baseline.env').write_text(text)
+(root / 'current.env').write_text(text)
+(root / 'scope.md').write_text(
+    'Composition: trial:librechat-rag-declaration. current.env is its selected '
+    'partial declaration; baseline.env retains initial bytes. Neither is loaded. '
+    'Other settings, overrides and runtime state are unknown. Do not source '
+    'these files or contact their targets. Prior research is separately scoped.\n'
+)
+print(root)
+PY
+```
+
+Expected: exit 0 for each command, one enabled candidate and the printed trial
+folder. Version 0.1.4 was used for both recorded passes; current 0.1.5 corrects the
+model's ownership reference without changing this reconciliation method.
+
+In a fresh local chat, select `n8r-surface:research`, supply the checkout, printed
+trial folder and any applicable prior notes, then ask:
+
+> Establish an AI Surface graph baseline for the composition in scope.md using
+> current.env and this LibreChat checkout. Reuse the supplied research after
+> checking applicability. Separate product possibilities, the declared trial
+> setup and observed deployment. Retain identities, human choices and unknowns.
+> Save the next numbered graph-reconciliation note and read back its bytes.
+
+Open the saved note and follow its claim-bearing source references. Record its
+exact filename and SHA-256. The baseline must exist **before** changing the file.
+The host must show its resolved absolute save destination; do not accept a claimed
+save without a readable file.
+
+In the same terminal, change the one value and inspect the actual bytes:
+
+```sh
+python3 - "$trial_dir" <<'PY'
+from pathlib import Path
+import hashlib, sys
+root = Path(sys.argv[1])
+old = (root / 'baseline.env').read_bytes()
+assert (root / 'current.env').read_bytes() == old
+new = old.replace(b'RAG_API_URL=\n', b'RAG_API_URL=https://rag.example.test\n')
+assert new != old
+(root / 'current.env').write_bytes(new)
+for name in ('baseline.env', 'current.env'):
+    data = (root / name).read_bytes()
+    print(name, hashlib.sha256(data).hexdigest())
+    print(data.decode(), end='')
+PY
+```
+
+Expected exit 0 and only that value changed. Baseline digest is
+`5e060fa66a8c986f418149ff5c8aceba7f4e3b4b090456bb1a1e4bf0299c3161`;
+changed digest is `facfff7d29f57690ba6bb2dc5127a2a249e581bf27f0e3bb9106f4761ab3b638`.
+
+In another fresh local chat with the same installed skill and source access,
+supply the baseline note and trial folder, then ask:
+
+> Compare this saved graph with the current sources and supplied declaration.
+> Show evidenced agreements, differences, additional discoveries, conflicts and
+> unknowns for relevant nodes and connections. Preserve the original, identities,
+> scoped decisions and unresolved claims. Separate capabilities, declarations
+> and observations. Save a numbered successor and read back its bytes.
+
+Independently open the successor and verify the one declared target change,
+unchanged capability/identities and retained unknowns. Rehash the baseline note
+and earlier notes to confirm preservation. Inspect the cited source lines and
+file hashes. Check `git status --short` again; research must not change the source
+checkout. Chat interactions have no process exit code.
+
+Graph wording, next note number and additional scoped source findings may vary.
+An unsupported runtime claim, lost predecessor, unrelated selection change,
+unexplained identity replacement or missing saved file fails the check. Source
+reading cannot demonstrate whether a process loaded this declaration; a later
+live trial needs separate effective-configuration and interaction evidence.
+
+Retain the notes and input snapshots together when preserving evidence. Otherwise
+remove only the disposable trial folder after review; no application cleanup or
+setting restoration is needed. Do not remove earlier research.
+
+See [recorded evidence](researcher-skill-verification.md#controlled-declaration-trial-014)
+and the proposed [Lab recreation handoff](recreation-handoff.md). An agent
+rehearsal establishes the bounded recorded outcome, not human acceptance or
+implemented Lab recreation.

package/docs/n8r-surface/researcher-repository-check.md

@@ -0,0 +1,95 @@
+# Try another chat-system repository
+
+Choose a different chat-system project and see whether Researcher can build a
+useful description from its actual sources. This is an exploratory test: the
+answers depend on the project you choose, so inspect the evidence it cites.
+
+## Before you start
+
+Download or clone a repository you are permitted to investigate into your usual
+projects folder. Keep it separate from this vault. Use a local chat app with
+**n8r-surface Researcher 0.1.5 already installed** and access to both that source
+folder and your local vault. You do not need to install or run the
+chosen application. Use public source files without credentials or private data.
+
+Pick a short run name, such as `another-chat-001`. Choose an unused name for each
+new investigation; existing runs stay available for comparison.
+Follow the [fresh-context guidance](researcher-vault.md#start-with-fresh-context) before
+the first prompt in each test chat.
+
+## Tasks
+
+- [ ] **1. Introduce the project.** Start a fresh local chat in your local vault
+  folder and select **n8r-surface Researcher** (`n8r-surface:research`). Give
+  it the location of the other repository by adding that folder to the chat's
+  accessible sources or pasting its full path. Name it as the source. In the prompt
+  below, replace `another-chat-001` with your chosen run name, then paste:
+
+  > Investigate the other chat-system repository I supplied. Start by confirming
+  > which project and source revision you can actually read. Describe how user
+  > input reaches AI processing, which model or inference services are supported,
+  > and how tools, stored data and authentication connect where the evidence
+  > supports them. Cite the source files behind the connections and identify
+  > important unknowns. Keep supported options distinct from a selected or running
+  > setup. Read source files only; do not install dependencies, start services or
+  > read credentials. Save a new numbered note under
+  > runs/another-chat-001/notes in this vault, creating the
+  > folder if needed, and give me a link to open it.
+  > Use the installed skill and the supplied sources only. Do not consult other
+  > chats, memories, projects, the web or the test walkthroughs.
+
+  **Look for:** the correct project, a readable connection map and actual source
+  references. If the chat cannot read the other folder, record **Blocked** rather
+  than accepting a description based only on the project's name. A downloaded
+  archive may lack a Git revision; that limitation should be stated, with the
+  inspected files identified instead.
+
+- [ ] **2. Inspect the saved findings.** Open the note from its link. Pick two or
+  three connections you care about and open the files it cites. Read the cited
+  sections to see whether they support the description. A Mermaid diagram may
+  appear as text in some editors; its relationships should still be readable.
+
+  **Look for:** findings about this project, not a generic chat architecture.
+  Optional integrations should stay optional unless configuration selects them.
+  Missing information should remain unknown. Source code alone should not become
+  a claim that an endpoint is reachable or a service works. Record any claim you
+  cannot verify as **Needs review**, with the claim and its cited file.
+
+- [ ] **3. Continue in a fresh chat.** Start a new local chat in your vault,
+  select Researcher, and supply the same source folder and saved note. Paste:
+
+  > Continue from this saved note. Trace one supported conversation path from
+  > incoming user text to the model request and back to the response. Identify
+  > which files support each part and where the evidence runs out. Retain the
+  > earlier component identities and open questions. Save a new numbered note
+  > alongside the first and leave the first unchanged.
+  > Use the installed skill, this note and the supplied repository only. Do not
+  > consult other chats, memories, projects, the web or the test walkthroughs.
+
+  **Look for:** a deeper explanation grounded in actual files, a second saved
+  note, and clear remaining gaps. It should build on the first investigation and
+  distinguish newly learned details from changes to the source. Reopen both files.
+
+## Record what happened
+
+> Result: Pass / Fail / Blocked / Needs review
+>
+> Project and source revision, or archive/version supplied:
+>
+> App and Researcher version:
+>
+> Saved notes:
+>
+> Connections checked against source:
+>
+> Surprising findings, unsupported claims or unanswered questions:
+
+**Pass** means the notes saved and reopened, the sampled claims matched the source,
+and continuation retained earlier work. **Fail** means you found a wrong claim,
+lost work or a failed save. **Blocked** means access or setup prevented the test.
+**Needs review** means you could run it but cannot yet assess a substantive claim.
+Wording and graph size may vary; a partial map with explicit gaps is useful.
+
+Keep the run for review. This checks a sampled source investigation and
+continuation; it does not establish complete coverage, runtime behavior or
+compatibility with a Lab. See the [vault guide](researcher-vault.md) for storage and cleanup.