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

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.

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

@@ -0,0 +1,84 @@
+# Verify a Skeleton Surface and its successor
+
+This tests a compact security-focused Markdown brief through the installed
+Researcher. An interception point is a place to inspect or intervene in a call;
+a binding maps a described role to a selected resource. No live service is needed.
+
+## Prerequisites and preparation
+
+Use installed Researcher **0.1.8**, a local host with file access and a writable
+vault. Reuse the [installation guide](researcher-skill.md#research-01-investigate-and-continue).
+Choose a fresh `runs/skeleton-check/` folder within your vault; use another name
+if it exists. Copy the two files from the
+[synthetic source pack](../../examples/researcher-vault/interception-service/system.md)
+into its `source/` folder. Create an empty `output/` folder alongside `source/`.
+Keep repository originals unchanged. No accounts, credentials, services or Lab
+installation are required. The pack is documentation, not executable software.
+
+State X: installed skill, the two revision-1 source files, an empty output folder.
+Input Y: the prompts below, separated by a deliberate source declaration change.
+Outcome Z: two readable briefs with stable identities, evidence and gaps; the
+first is preserved and the second distinguishes declarations from runtime facts.
+Only trial outputs and the disposable settings copy should change.
+
+## Tester steps
+
+- [ ] **SKELETON-01 — create the brief.** Open a fresh chat with the trial folder
+  available and select n8r-surface Researcher. Ask:
+
+  > Create a security-focused skeleton Surface from the supplied source folder.
+  > I want to know where a security integration could intercept LLM and actual
+  > tool calls, with its powers and coverage gaps. Keep the brief compact and link
+  > supporting evidence. Save it in the output folder. Stop before installation
+  > or configuration.
+
+  Open the returned file. Expect **Skeleton Surface v0.1**, a particular draft
+  revision, stable graph identities, source references and explicit unknown
+  bindings. It should distinguish backend inference from actual MCP execution,
+  the chat hook's allow/deny powers, the worker's bypass of that hook, and the
+  browser-direct inference route. The audit companion must not gain blocking
+  power merely because it is a companion process. No vendor compatibility or
+  working interception should be claimed. A short table is sufficient; no fixed
+  word/node count or detailed research appendix is required.
+- [ ] **SKELETON-02 — change declarations outside the Lab.** Keep a preservation
+  copy of the first output. In the disposable `source/settings.txt`, replace the
+  first comment and the two indicated empty values with:
+
+  ```text
+  # Synthetic setup declaration, revision 2. No process has loaded these values.
+  MONGODB_URL=mongodb://database.example.test:27017/cedar
+  MODEL_BASE_URL=https://model-proxy.example.test/v1
+  ```
+
+  Leave the other fields unchanged. These reserved addresses are fictional; do
+  not connect to them. Open the first output again: it should remain unchanged.
+  Start a fresh chat with the trial folder and skill, supply that output and ask:
+
+  > Reconcile this saved skeleton with the current source folder and save a
+  > successor in the same output folder. Explain the changes and retain the
+  > security interception view. Stop before installation or configuration.
+
+  Open both outputs. Expect the same profile version, stable identities for the
+  database/inference roles and retained interception gaps. The successor should
+  identify the new database and inference target declarations with their source,
+  preserving the first output. It must not claim a process loaded them, a proxy
+  intercepted traffic, a specific proxy product was identified, or the database
+  works. The source pack cannot establish when any real change took effect.
+- [ ] Report **Pass / Fail / Blocked**, skill/app versions, links to both outputs
+  and the step/evidence for any failure. Wording, IDs and unused file numbers may
+  vary; identities must remain stable between outputs. Missing files/evidence,
+  overwritten predecessors, lost bypasses or unsupported runtime claims fail.
+  These are chat interactions with no process exit code. Keep the trial folder
+  for review; optional cleanup removes only that folder after review.
+
+## Maintainer evidence checks
+
+Record the exact candidate commit, installed skill/package digests and host
+version separately from tester steps. Independently read the saved bytes, verify
+source references/hashes, compare stable IDs and confirm unchanged predecessor
+bytes. Check that neither source file changed during each research interaction.
+The deliberate settings edit happens between interactions, not inside research.
+
+Record actual results in [versioned verification](researcher-skill-verification.md#skeleton-surface-018).
+An agent rehearsal is not human acceptance, Work UI lifecycle validation, runtime
+enforcement, a Lab recording implementation or validated structured output.