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

package/docs/n8r-surface/npm-release.md

@@ -0,0 +1,188 @@
+# First public npm release
+
+The maintainer authorized publication of both `@n8r/surface` and `n8r-surface`
+at **0.1.0-experimental.2** on 5 November 2026. This procedure is release
+preparation, not evidence that publication succeeded. Both packages use the
+explicit `experimental` tag. No `latest` promotion is included.
+
+The `.1` preparation run built and retained both archives but failed remote-tag
+verification before any npm staging. Its permanent tag and draft assets remain
+for diagnosis. The maintainer approved `.2` after the verifier was corrected to
+read the exact Git reference and dereference annotated tag objects. No `.1`
+package or placeholder was staged or published by that run.
+
+## User outcome and starting evidence
+
+Given private local candidates and no verified registry versions, the maintainer
+can prepare both publishable archives from one reviewed commit, publish their
+retained bytes with provenance, and independently install either exact version.
+The source remains private to prevent publishing the checkout accidentally.
+
+The original installed/candidate checks passed, but those archives were private.
+Before this increment, `npm whoami` returned E401 and both names returned E404.
+After interactive login, npm identified the intended account and confirmed its
+`n8r` owner role. Both names still returned E404. These responses do not prove
+name availability or successful first publication. No placeholder was published.
+
+## Maintainer preparation
+
+1. Review and merge the release-preparation PR after acceptance. Merging is a
+   separate maintainer decision. The workflow must exist on the default branch.
+2. Use an authorized npm account with `n8r` organization rights and permission
+   to create the unscoped package. For this first release, the selected route is
+   a short-lived granular npm token with package **read/write (stage only)**
+   permission covering `@n8r/surface` and the new unscoped `n8r-surface`.
+   Selecting package `n8r` or scope `@injectionator` is insufficient. If npm
+   cannot select an unpublished unscoped name, temporarily use all-packages
+   coverage; organization-management permissions are unnecessary. Store it only as
+   repository Actions secret `NPM_BOOTSTRAP_TOKEN`. Never put it in a command,
+   issue, report or committed file. npm account 2FA remains enabled.
+3. Enable **Settings → General → Releases → Enable release immutability** before
+   creating the draft. An administrator may be needed; an API 404 under a
+   non-admin account is not proof the setting is disabled.
+4. Verify all required Node 22/24/26 checks on the reviewed revision. From its
+   clean checkout, create an annotated `v0.1.0-experimental.2` tag and push only
+   that tag. Never move or reuse it. Record its full commit SHA.
+
+References checked 5 November 2026: [npm token setup](https://docs.npmjs.com/creating-and-viewing-access-tokens/),
+[provenance](https://docs.npmjs.com/generating-provenance-statements/),
+[trusted publishing](https://docs.npmjs.com/trusted-publishers/), and
+[release immutability](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/establish-provenance-and-integrity/prevent-release-changes).
+Trusted publishers require existing packages. npm offered stage-only tokens;
+the maintainer explicitly approved staged first publication, including the
+public `0.0.0-stage` placeholders it creates. The actual release versions require
+maintainer approval with 2FA. See [npm staged publishing](https://docs.npmjs.com/staged-publishing/).
+
+## Human check before publication
+
+Prerequisites: the PR checkout with dependencies installed, Node 22/24/26, npm,
+Git and POSIX `tar`. Staging uses npm 11.20.0 (staging requires 11.15+). Start in the repository root. These steps require no npm
+write credentials and do not alter normal settings or installations.
+
+- [ ] Create fresh publishable candidates:
+
+  ```sh
+  release_run=$(mktemp -d)
+  npm run pack:candidates -- "$release_run/packages" --publishable
+  tar -xOf "$release_run/packages/scoped/n8r-surface-0.1.0-experimental.2.tgz" package/package.json
+  ```
+
+  Expect exit 0, version `0.1.0-experimental.2`, name `@n8r/surface`,
+  `private: false`, public npm registry/access and tag `experimental`.
+  The source `package.json` must still have `private: true`.
+- [ ] Install and run the preferred archive:
+
+  ```sh
+  mkdir "$release_run/consumer"
+  cd "$release_run/consumer"
+  npm install --offline --ignore-scripts --no-audit --no-fund --package-lock=false "$release_run/packages/scoped/n8r-surface-0.1.0-experimental.2.tgz"
+  node --input-type=module -e 'import {decode} from "@n8r/surface"; console.log(typeof decode)'
+  ./node_modules/.bin/n8r-surface --version
+  mkdir "$release_run/home"
+  HOME="$release_run/home" USERPROFILE="$release_run/home" ./node_modules/.bin/n8r-surface </dev/null
+  echo "$?"
+  ls -A "$release_run/home"
+  ```
+
+  Expect install/import/version exits 0, `function`, and
+  `n8r-surface 0.1.0-experimental.2`. Bare startup prints setup guidance,
+  exits **1**, and leaves the isolated home empty.
+- [ ] Repeat in a new consumer and home directory using the `unscoped/` archive
+  and import `n8r-surface`. Expect identical behavior, with that installed name.
+- [ ] Report **Pass / Fail / Blocked**, both CLI outputs, Node/npm versions and
+  candidate revision/dirty flag. Unexpected version, missing imports, or home
+  writes are Fail. Missing prerequisites are Blocked. Leave the consumer and
+  remove only the temporary directory created above after retaining evidence.
+
+## Prepare and stage retained artifacts
+
+The manual [workflow](../../.github/workflows/npm-release.yml) accepts only the
+annotated first-version tag, requires it to be on `main`, and checks clean source.
+Preparation runs tests and both installed-package suites, builds both archives
+once, retains the complete build as an Actions artifact for 90 days, and stores
+the archives with `candidates.json` on a draft GitHub Release. An existing
+release prevents preparation from rebuilding. Downloads and hash validation are
+performed before any publication. Network access includes npm, GitHub and Sigstore;
+write effects are draft release assets and, only for `stage`, npm staged versions and first-package placeholders.
+
+From the repository root with GitHub CLI access:
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.2 -f operation=prepare
+gh run list --workflow npm-release.yml --limit 1
+```
+
+Inspect the run and draft assets; record the run ID and full source revision.
+Preparation must finish successfully before selecting staging:
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.2 -f operation=stage
+```
+
+The publisher reads both registry versions first. An existing version must match
+retained SHA-256 and registry SHA-512 integrity and expose provenance metadata;
+only absent versions are staged. Existing stages are downloaded and compared
+to retained SHA-256 before they are reused; duplicate stages or differing bytes
+stop the run. Non-404 lookup errors stop the run. The
+workflow never finalizes the GitHub Release and never promotes `latest`.
+Provenance metadata presence is not cryptographic verification.
+
+On partial failure, retain the draft and its exact assets. Retry **stage** only
+after diagnosing the failure; never rerun preparation or rebuild a published
+version. Existing bytes that differ require a new approved version for both
+packages. If draft creation succeeds but an upload fails, recover missing assets
+from the original run's `npm-release-COMMIT_SHA` Actions artifact. Download it
+with `gh run download RUN_ID -n npm-release-COMMIT_SHA -D NEW_DIRECTORY`, verify
+`candidates.json` revision and each archive SHA-256, and upload only missing
+assets without `--clobber`. Run `check:release` before retrying staging.
+Keep a durable independent copy before the 90-day retention expires. If the
+original bytes cannot be recovered, stop; do not regenerate them.
+
+## Approve each staged version with 2FA
+
+Open npm's **Staged Packages** page as the authorized maintainer. For each of
+`@n8r/surface` and `n8r-surface`, inspect version `0.1.0-experimental.2`, tag
+`experimental`, the workflow's stage ID and downloaded bytes. Approve each with
+2FA. Alternatively run `npm stage approve STAGE_ID` in your authenticated terminal.
+These actions publish the real versions; the placeholders are not acceptance.
+
+Then run the read-only verification operation:
+
+```sh
+gh workflow run npm-release.yml --ref v0.1.0-experimental.2 -f operation=verify
+```
+
+Expect success only when both exact registry versions match retained bytes and
+expose provenance metadata. This operation cannot stage or approve anything.
+
+## Independent registry acceptance and finalization
+
+For each package, use a separate fresh consumer outside the checkout. Install
+its exact version with lifecycle scripts disabled, run `npm audit signatures`,
+read the installed name/version, import `decode`, run `--version` and the isolated
+closed-input startup above. Also exercise the two explicit one-off routes:
+
+```sh
+npm exec --yes --package=@n8r/surface@0.1.0-experimental.2 -- n8r-surface --version
+npm exec --yes --package=n8r-surface@0.1.0-experimental.2 -- n8r-surface --version
+```
+
+Both must print `n8r-surface 0.1.0-experimental.2` and exit 0. Download each
+registry tarball and compare its bytes/digests with the draft assets. Inspect
+its own provenance attestation, including source repository, full commit,
+workflow identity and subject digest; an attested dependency is insufficient.
+Record registry `dist.integrity`, publication and install results independently.
+
+After both routes pass, configure trusted publishing separately for both names:
+GitHub owner `injectionator`, repository `n8r-surface`, workflow `npm-release.yml`,
+no environment, permission to stage. Keep maintainer 2FA approval for promotion. A new configuration must succeed within
+two days; do not configure it long before its next use. Verify the configuration
+and its first actual OIDC publication before claiming it works. Remove the
+bootstrap secret and revoke its token when no longer needed. A future version
+requires a reviewed update to the deliberate first-version guards.
+
+Attach independent evidence and final release notes, then finalize the draft
+with prerelease true and latest false. Read it back with `check:release` and
+require `immutable: true`. Finalization remains blocked on failed registry,
+provenance, identity or immutability checks. Record **Pass / Fail / Blocked** with
+both package results; local rehearsals do not establish a completed release.

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).