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

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

@@ -0,0 +1,161 @@
+# STARTUP-01 verification record
+
+**Result:** specified, implemented and verified for the read-only bare-startup
+increment. This does not complete #16 or verify setup, status, discovery or an AI
+conversation. [Settings, parser decisions and limits](startup.md) define the
+implemented boundary. [PR #25](https://github.com/injectionator/n8r-surface/pull/25)
+carries the increment originally developed on #15. This record preserves the
+pre-integration verification revision and does not claim a release.
+
+## Human verification
+
+Follow the [copy-and-paste human check](startup-human-check.md) for prerequisites,
+PR checkout, a disposable installation and synthetic home, exact expected output,
+interactive `y`/EOF steps, private-value checks and cleanup. Its expected exit 1
+is explained explicitly. The automated commands later in this record support
+that hands-on check.
+
+On 4 November 2026, Codex rehearsed the guide's disposable installation, closed
+input, terminal `y` and Ctrl-D, private-value/stderr checks and unchanged-file
+comparison on Node 22.23.2, npm 11.5.2 and macOS ARM64. The expected output and
+exit codes matched; all 43 tests and 20 installed startup checks also passed.
+This is an agent rehearsal, not recorded human acceptance.
+
+## Revision and environment
+
+- Date: 4 November 2026. Implementer/verifier: Codex; separate read-only agent
+  review found no important issues in the startup implementation.
+- Baseline: `5f67dbea2be93a6ee6bedb9a029bc79be4b3997d`.
+- Implementation and retained test revision:
+  `b90358aaf22fead155081bb00f6d837a0f8f59e7`. The matrix below was repeated from
+  this committed revision with a clean working tree before writing this record.
+- macOS ARM64; Node.js **22.23.2, 24.22.2 and 26.13.0**; npm **11.5.2**;
+  Python **3.13.1** for the terminal rehearsal.
+- Private package `n8r-surface@0.0.0-experimental.1`, built and packed locally,
+  then installed outside the checkout using `--offline --ignore-scripts`.
+  `npm ci` populated the dependency cache; no registry publication occurred.
+  Each matrix executable was the `node` binary in its own runtime directory.
+
+## Baseline and prepared state
+
+At the baseline, `command -v n8r-surface` returned no path (exit 1) and the package
+manifest contained no `bin` entry. The installed product interaction was therefore
+**blocked by an absent executable**, not an observed failed startup. No research
+or setup result was invented. After adding the process tests, 16 startup checks
+failed on the missing built entry point while the existing 23 library tests passed.
+
+The repeatable check creates a temporary home containing:
+
+- `~/.n8r/n8r-surface.json`: version 1, `artefactRoot: "~/n8r/artifacts"`,
+  `surfaceFormat: "json"`, and synthetic private markers in ignored settings.
+- `~/n8r/artifacts/librechat-uniqueid.json`: a valid synthetic `n8r.surface/0.1`
+  definition titled **LibreChat**. It is a prepared input, not Researcher output.
+- No runner or Lab configuration. A synthetic credential marker in the process
+  environment must also be absent from output. A saved PID in ignored settings
+  must not imply runner liveness.
+
+**Interaction:** invoke installed `n8r-surface` with no arguments from the
+isolated home. First close stdin and capture output/exit. Then run the same
+installed bin in a real POSIX terminal, wait for the guidance question, check the
+already-received overview, and answer `y`. Repeat with terminal EOF (Ctrl-D).
+No credentials or running Lab are required.
+
+## Observed terminal output
+
+This is the installed PTY readback, with only the temporary home replaced by `~`,
+PID/time represented by labelled placeholders, and readline cursor escapes removed.
+The assertions use the real paths, compare the child PID with its process result,
+and check the timestamp is present. File contents are independently reread.
+
+```text
+Configuration
+  File: ~/.n8r/n8r-surface.json
+  Settings version: 1
+  Artefact folder: ~/n8r/artifacts
+  Surface output: JSON
+  AI runner: Not configured
+  Lab connection: Not configured
+
+Processes
+  n8r-surface overview: running (PID <observed PID>); observed <UTC timestamp>
+  Runner/Lab processes: Status unknown (no live status source)
+
+Local artefacts (1)
+  LibreChat | Surface definition | ~/n8r/artifacts/librechat-uniqueid.json
+
+Setup and AI conversation are not implemented in this build. Research needs a supported AI runner.
+Show setup requirements? [y/N] y
+Research will require an explicitly selected runner, model and external credential reference. A Lab connection is optional. No settings have been changed.
+```
+
+With closed input, the same overview appears, followed by the unavailable-capability
+message and `Run in an interactive terminal for read-only setup guidance.` No
+question appears and the process exits within the five-second test deadline.
+Valid startup exits **1**, explicitly indicating unavailable setup/conversation;
+inspection errors and arguments exit **2**. This is not research success.
+
+## Independent readback and repeatable evidence
+
+| Expected outcome | Observed check |
+| --- | --- |
+| Readable settings and actual configured location | Output matches the prepared configuration path, `artifacts` override, JSON format and unconfigured runner/Lab. Defaults separately resolve to `artefacts`; relative paths resolve against the settings directory. |
+| One logical row per entry | The supplied LibreChat definition appears exactly once with its title, type and filename. Two-entry cases also list HTML research metadata; YAML definitions are read. Controls in titles are escaped. |
+| Private values stay private | Markers in nested/unknown settings, URL credentials, malformed input, artefact bodies and the credential environment are absent. Parser errors never echo source content. |
+| Reliable status only | The displayed live overview PID equals the spawned child PID. Runner/Lab status remains unknown, including with a saved PID or declared runner/Lab configuration. |
+| Read-only startup | Before/after bytes, modes and modification times match; the snapshot also checks the directory inventory. PTY `y` and EOF preserve the files and directories. |
+| Empty differs from unavailable | Empty folders say empty; missing/unreadable folders report the path/problem. Invalid or unreadable configuration prevents corpus inspection and remains intact. |
+| Unsupported entries do not disappear or hang | Unsupported, invalid, oversized, unreadable, symlink and directory entries retain a row with a limitation. FIFO configuration and entries finish without blocking. |
+| Overview precedes interaction | PTY checks see configuration, processes and the artefact row before the live guidance question, then supply `y` or EOF. |
+| Installed consumer needs no checkout | The tarball supplies the executable, library and assets. The same startup assertions invoke `n8r-surface` from its installed bin directory under a temporary home. |
+
+All **43 tests** (23 existing library checks plus 20 startup checks) passed with
+`npm test` on each supported Node major above, with no skips. The installed-package
+matrix passed the library consumer check, all **20 startup checks**, and both PTY
+interactions on each runtime. A separate reviewer also exercised terminal `n`,
+Ctrl-D and Ctrl-C on Node 22 without raw diagnostics or a hang.
+
+A validation regression found during implementation treated explicit null settings
+as defaults. Two new checks failed before the fix; null folder/format values now
+report invalid configuration without inspecting a fallback folder.
+
+Reproduce from the repository:
+
+```sh
+npm ci
+npm test
+npm run check:package
+```
+
+For the supported runtime matrix, run `npm test` with each runtime on PATH, then:
+
+```sh
+node scripts/check-package.mjs /path/to/node22/bin/node /path/to/node24/bin/node /path/to/node26/bin/node
+```
+
+The paths above are placeholders. Use binaries named `node` in separate runtime
+directories: the installed shebang resolves `node` from that directory on PATH.
+A custom-named executable beside a different `node` would not establish the same
+matrix. Retained evidence is ordinary code in
+[startup.test.mjs](../../tests/startup.test.mjs),
+[startup-pty.py](../../tests/startup-pty.py) and
+[check-package.mjs](../../scripts/check-package.mjs), plus the observed readback
+above. The checks remove their temporary installations/homes. No raw machine
+paths or private logs are retained in the repository.
+
+## Remaining limits
+
+Only the command's own process is directly known; there is no process registry or
+proof of a live AI runner or Lab. Configured runner/Lab objects are declarations
+whose contents are withheld. Missing setup is explained, not repaired.
+
+The listing recognizes the experimental #15 profile. Older illustrative LibreChat
+JSON, manually edited HTML, unknown formats and unsupported versions get a
+limitation row; there is no universal Surface conformance claim. Files are bounded
+per entry, but this increment does not provide a large-corpus index or total scan
+time limit. Network-mounted folders were not exercised. Linux and Windows were
+not exercised; PTY verification requires POSIX and Python. No inference, source
+research, Lab compatibility, registry/npx download or release claim is made.
+
+Next in #16: separately specify and verify `status`, then real setup, help/version,
+source selection, guarded storage and unavailable-discovery handling. Actual
+Researcher instructions and AI-driven repository research remain #17.

package/docs/n8r-surface/startup.md

@@ -0,0 +1,151 @@
+# Bare startup and local vault setup (#16)
+
+Bare `n8r-surface` displays readable non-private configuration, legacy saved
+artefacts and known own-process status. It then offers first-use vault setup or
+reuses the configured vault. Setup does not start research, scan source contents,
+use a network, launch a runner or require an account. Bare startup is unchanged by the separate [Codex discovery increment](codex-research-verification.md).
+SOURCE-01 remains paused; the new discovery path does not incorporate that checkpoint. This increment does not complete #16 or #30.
+
+The earlier read-only overview and guidance question were delivered by
+[PR #25](https://github.com/injectionator/n8r-surface/pull/25).
+[Historical STARTUP-01 evidence](startup-verification.md) applies to that revision.
+The setup increment replaces its guidance question and exit behavior; see the
+[current setup rehearsal and human tasks](vault-setup-verification.md).
+
+## Settings and parser decisions
+
+One settings file: `~/.n8r/n8r-surface.json`, version 1, limited to 64 KiB.
+The process home directory selects `~`, allowing an isolated verification home.
+There are no project settings, command-line overrides or credential environment
+reads. The repository's `.local/vault-path` remains an agent convention and is
+not read by this command.
+
+```json
+{
+  "version": 1,
+  "vaultRoot": "~/n8r/",
+  "artefactRoot": "~/n8r/artefacts",
+  "surfaceFormat": "json"
+}
+```
+
+`vaultRoot` is optional; absence means setup is pending. It stores the vault for
+future research, containing `research/`, `artifacts/` and `surfaces/`.
+`artefactRoot` remains the separate legacy structured-artefact location and defaults
+to `~/n8r/artefacts`. No migration, renaming or inference from its parent occurs.
+Both locations are displayed. Existing legacy content and every unknown settings
+value are preserved. `surfaceFormat` defaults to `json` and also accepts `yaml`.
+Optional `runner` and `lab` objects (or null) remain independent declarations;
+only configuration presence is shown, never their private contents.
+
+Expand `~/` against home. Stored relative paths resolve against the settings
+folder. Newly entered relative vault paths resolve against invocation cwd;
+first setup saves an absolute path. Validate the fully expanded/resolved path as
+well as the input so that neither can introduce forbidden control characters.
+Resolve pre-existing ancestors and an
+explicitly selected vault-root symlink before showing the destination. Reject
+empty custom paths, control characters, URL forms, non-directory collisions,
+settings symlinks/special files and symlinked required vault children. Invalid
+settings are retained for repair, never replaced with defaults.
+
+Only zero arguments launches startup. Discovery, reopening and local help/version
+have separate paths described in [the command inventory](command-outcomes.md#initial-public-command-inventory).
+Unknown arguments exit 2 without echoing them or inspecting settings. No `setup`,
+`--vault`, `--path` or `status` command is added.
+
+## First use, reuse and repair
+
+The read-only overview precedes all questions. With both input and output attached
+to terminals, first use asks:
+
+```text
+Vault directory [~/n8r/]:
+Vault directory: <resolved absolute path>
+Create vault folders and save this location? [y/N]
+```
+
+Enter at the location question chooses `~/n8r/`. Only `y` or `yes` (case insensitive)
+at confirmation permits writes. Refusal, EOF and interruption before acceptance
+exit 1 without writes. Acceptance creates only missing directories, then adds
+`vaultRoot` to settings and prints `Vault ready: <resolved absolute path>`.
+Existing JSON member bytes are retained when inserting the new field, including
+unknown numeric literals outside JavaScript precision/range.
+No source files are read or written. Reject writes to settings/vault paths inside
+the invocation directory, including symlink aliases and missing descendants.
+Also reject vault folders inside the legacy corpus: adding directories there
+would break its next inspection. Running setup from home can therefore be refused; run from a separate source
+folder. Complete configured reuse is read-only even from such a directory.
+
+A complete configured vault exits 0 without questions, locks or settings rewrites.
+Missing required folders need repair confirmation; repair creates folders without
+rewriting settings. An occupied child path or inaccessible vault exits 2. Existing
+vault files are never removed. A failed confirmed setup may leave empty folders;
+retry reuses them. Setup does not create the legacy corpus when it is absent.
+
+| Outcome | Exit | Writes |
+| --- | --- | --- |
+| Successful accepted setup/repair | 0 | Missing folders; settings only on first setup |
+| Complete configured reuse | 0 | None |
+| Decline, EOF or interrupt before confirmation | 1 | None |
+| Setup/repair needed with nonterminal input or output | 1 | None |
+| Invalid settings/arguments, filesystem or conflict error | 2 | No successful setup claim; partial confirmed folders may remain |
+| Legacy inspection error except absent corpus | 2 | None; takes precedence before any setup question |
+
+Closed-input setup/repair prints exactly:
+
+```text
+Vault setup required; run n8r-surface in an interactive terminal.
+```
+
+It finishes promptly without waiting. Missing legacy corpus is reported as
+unavailable/absent (`ENOENT`) and permits setup/reuse; it is not reported empty.
+Other legacy errors remain visible even when a complete vault exists.
+
+## Concurrency and recovery boundary
+
+The user approved this cooperating-writer boundary on 5 November 2026. Other
+editors must not write settings during confirmed setup. Directory/symlink topology
+must stay stable while setup runs. This is not an adversarial filesystem or
+power-loss durability guarantee, nor protection against arbitrary external writers.
+
+After confirmation, exclusively create `~/.n8r/n8r-surface.json.lock`. Other setup
+processes fail with exit 2 rather than wait or steal the lock. Compare the original
+settings bytes under the lock before folder creation and again before publication.
+Detected edits fail and retain the competing values. Write an exclusive temporary
+sibling and close it only after all required folders are available. For absent
+settings, publish with an exclusive hard link: a competing creator is preserved
+even after the final byte check. For existing settings, atomically rename under
+the lock. A writer ignoring that lock can still race the final check/rename;
+no stronger guarantee is claimed.
+
+Normal completion/failure removes only this invocation's temporary sibling and
+lock. A killed process may leave these and empty folders. If a lock remains,
+first establish that no setup process is active, inspect the saved settings and
+vault, then remove the stale `n8r-surface.json.lock` manually and retry. Never
+remove a lock while another setup may be running. Abandoned `.tmp` siblings may
+be inspected and removed manually after establishing ownership; automatic setup
+does not delete another invocation's files. No automatic age/PID-based lock theft.
+
+## Local inspection boundary
+
+List direct legacy folder entries in filename order, one terminal-safe line each.
+Read JSON/YAML definitions and HTML research records with existing bounded readers;
+use title/type metadata, never source or extension contents. Unsupported, invalid,
+oversized, unreadable, symlink and non-regular entries remain visible as errors.
+Do not recurse, open source locations or execute HTML. Reads are bounded to 2 MiB
+per artefact. Terminal controls, line separators and bidi characters are escaped.
+
+The process identifies only its own PID and observation time. Runner/Lab process
+status remains unknown; configured settings do not establish a live process.
+There is no daemon, PID registry, source scan, network probe or inference.
+
+## Verification boundary
+
+Transaction tests cover preserved values/bytes, malformed and oversized settings,
+source overlap and symlinks, deterministic conflicting writes, a second real
+process under a held lock, partial filesystem/publication failure and retry.
+Process and PTY checks exercise the real command with independent filesystem
+readback; the package check repeats them outside the checkout. See
+[the verification record](vault-setup-verification.md) for exact revisions,
+runtimes, human tasks and remaining limits. Automated rehearsal is not human
+acceptance or proof of research, save/continue, or consumer compatibility.

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

@@ -0,0 +1,224 @@
+# Capability and Bound Surface contract 0.2
+
+This bounded library contract implements [#50](https://github.com/injectionator/n8r-surface/issues/50)
+within the one AI Surface Model. It supports the [agreed delivery intent](surface-descriptions.md),
+not a universal schema or a released Researcher workflow. The standalone skill
+must not call or depend on the `n8r-surface` CLI. Skill artifact production is #51;
+installed-workflow and human acceptance are #52. Observed Surface remains deferred.
+
+For the revised #50 verification, start with [shared relationships 0.3](surface-relationships.md).
+This earlier bounded profile and its fixtures remain readable without alteration;
+`0.3` adds consistent node/edge metadata across both descriptions.
+
+## Versions and shared representation
+
+`n8r.surface/0.2` requires `kind: "capability"` or `kind: "bound"`. It neither
+reinterprets nor replaces `n8r.surface/0.1` selected definitions. Older readers
+reject it. Do not change the version string to downgrade: doing so loses possible
+versus configured meaning, exclusive alternatives, conflicts and instance identity.
+There is no automatic conversion. Keep the original when making a separately
+reviewed projection. Package versions and artifact contract versions are distinct.
+
+Reuse the [0.1 envelope, research records and logical digests](contracts.md).
+All fields below are required; empty arrays are permitted except where specified.
+Objects are closed. This profile requires an empty `extensions` object and has
+no arbitrary attributes or actual-setting fields. JSON is the only encoding;
+`encode` and `decode` reject YAML for these descriptions. Research records retain
+their existing JSON/YAML/HTML support. No new renderer is introduced here.
+
+| Shared field | Meaning |
+| --- | --- |
+| `id`, `title`, `scope`, `revision`, `extensions` | Existing envelope; `extensions` must be `{}`. |
+| `records` | Exact research `{id, revision, digest}` references. |
+| `vocabularies` | Unique `{id, version}` entries; terms remain vocabulary-specific. |
+| `nodes` | `{id, label, type: {vocabulary, term}}`; useful component/target identity only. |
+| `coverage`, `gaps` | Explicit coverage limits, missing information and next research needs. |
+
+A basis entry is `{record, revision, items}`. `items` is nonempty and unique,
+referring to findings, or to decisions only in the dedicated `decisions` field.
+Referenced research revisions must occur in `records`. Source identity, version,
+date, locator, coverage and limitations live in the research record, not copied
+raw configuration. All IDs are opaque, stable and case-sensitive. Labels are not
+identity matching rules. An omitted node/edge/binding is unspecified, not absent.
+
+## Capability Surface
+
+`kind: "capability"` adds `capabilities` and `exclusiveGroups`.
+
+Each capability is `{id, from, to, type, state, basis, conditions, note}`. Endpoints
+resolve to local nodes and type vocabulary resolves locally. Shared components,
+parallel edges, cycles and self-loops are allowed. Each edge is a possible
+relationship, never a selected composition. `conditions` lists material conditions
+and `note` explains applicability and uncertainty. Empty conditions do not prove
+unconditional support outside the stated scope.
+
+| State | Evidence check |
+| --- | --- |
+| `possible` | Nonempty basis; all cited findings are `known`, subject equals `from`, property is `supports`, and every claim value equals the `to` node ID. |
+| `absent` | Nonempty basis; all findings are `absent` with the same subject/property/target rule. This is scoped absence of support, not an unbound instance. |
+| `conflicting` | Nonempty basis containing a conflicting finding; subject/property still match. Inspect all competing values in research. No target is selected. |
+| `unknown`, `omitted`, `redacted`, `out-of-scope` | No support assertion. Any basis resolves to findings about that subject/property; notes explain the state. |
+
+Each exclusive group is `{id, members}` with at least two distinct capability
+IDs. It means **at most one** member may be configured in this bounded instance.
+It does not require a selection, claim exhaustive alternatives, or resolve a
+conflict. The synthetic authentication group is a fixture constraint, not a general
+claim that every product makes OIDC and SAML mutually exclusive. Conditions and
+other constraints remain human-readable; the checker does not execute them.
+
+## Bound Surface
+
+`kind: "bound"` adds `capability`, `instance` and `bindings`:
+
+- `capability` pins one Capability Surface `{id, revision, digest}`.
+- `instance` is `{id, label}` with an opaque identity distinct from the capability
+  artifact and its components. It contains no location or credentials.
+- Each binding is `{id, capability, state, claims, decisions, note}`. The inner
+  `capability` is an edge ID in the pinned Capability Surface. One entry per
+  capability is permitted in this bounded profile.
+- Each claim is `{target, basis}`. `target` resolves to a local Bound node; basis
+  is nonempty. A useful target label may be `MongoDB Atlas` or `OIDC service`.
+  A target need not have the same ID as the product-level capability target.
+
+| State | Required claims |
+| --- | --- |
+| `configured` | Exactly one target with known configuration evidence; capability state must be `possible`. |
+| `conflicting` | At least two distinct targets, each evidenced; no selected target. |
+| `unknown`, `omitted`, `redacted`, `out-of-scope` | No claims; the note explains why. |
+
+A configuration finding has `subject` equal to the opaque instance ID, `property`
+equal to the capability edge ID and claim values equal to target node IDs. It is
+`known` or `conflicting`. Each cited finding must include the target it supports;
+all of that finding's competing targets must be retained in the binding. All
+known/conflicting findings for that same instance and capability in the Bound
+description's referenced research are checked, including uncited basis items.
+Multiple known findings supporting different targets also form a conflict. A configured
+binding cannot cite a conflicting finding. Missing evidence cannot become an
+unbound assertion. Explicit unbound/absence and multi-target configured slots are
+outside this initial binding profile; preserve such source findings in research
+and describe the coverage limit rather than forcing them into a supported state.
+
+`decisions` refers only to research decisions, independently of source findings.
+A human preference is not configuration evidence and cannot resolve a source
+conflict by itself. Corrected source evidence belongs in a new research revision.
+Configuration suffices; no reachability, runtime use or successful deployment is
+asserted or checked. Target suitability and the truth/coverage of source prose
+require inspection; matching references alone do not establish those facts.
+
+## Verification and revisions
+
+The existing public APIs accept the new types:
+
+- `validateArtefact(value)` checks closed shape, states, identity uniqueness,
+  local targets/vocabularies and declared research references.
+- `verifyReferences(value, context)` additionally requires exact research and
+  Capability revisions/digests, checks evidence roles, subject/property/target
+  correspondence and exclusive groups. Include the Capability's research context
+  even when the Bound description cites a later research revision.
+- `encode(value, 'json')` and `decode(text, 'json')` check structure and preserve
+  data. They do not imply that external references were checked.
+- `verifySuccessor(previous, next)` checks parent revision/digest and retained
+  identities. Description kind cannot change. A retained node cannot change its
+  type; a retained capability cannot change endpoints/type. A retained binding
+  slot cannot change its capability ID, instance or capability-artifact identity.
+  A successor may pin a newer revision of the same Capability artifact and change
+  a binding target with new evidence. Check both references and succession.
+
+A binding ID denotes the instance's slot for that capability, not an immutable
+edge to one target. Target changes retain the slot ID and component IDs where
+those components are the same. A different connection/capability needs a new ID.
+Old bytes and old references stay unchanged; these pure library functions do not
+write files or enforce history-wide ID reuse, atomic persistence or retention.
+Cross-revision vocabulary changes and newly supplied source meaning still need
+human review. Size/depth limits are the existing 2 MiB / 64-level codec limits,
+not graph hop limits.
+
+## Privacy boundary
+
+Supply only permitted, sanitized research. Do not copy actual URLs, IP addresses,
+usernames, passwords, keys or raw settings into any note, label, identifier,
+source locator, filename, HTML, JSON or retained evidence. Use opaque source
+identifiers or sanitized snapshots whose digest describes those actual sanitized
+bytes; never invent a digest of unseen raw material. A source that cannot be
+inspected safely is a coverage limit. No raw-secret store is introduced.
+
+Closed shapes and rejection of nonempty extensions prevent designated settings
+fields from being stored, but **validation is not a secret detector**. A secret
+could still be put in ordinary prose or an identifier. Producers must avoid
+collecting it and check all output before retention; #51 owns that workflow.
+Tests use synthetic sentinels, never real secrets. New-description validation and
+reference errors omit input values/keys; parser syntax errors also omit source
+snippets. Do not log raw rejected input or legacy research-validation exceptions.
+Old research records allow arbitrary claim values and retain their existing
+validation contract; sanitization remains essential before calling those APIs.
+
+## Human verification task list
+
+Prerequisite: open this branch's [synthetic examples](../../examples/researcher/descriptions/README.md).
+No CLI, inference, credentials, real configuration or live services are needed.
+
+- [ ] Open `capability.json`. Expect MongoDB, OIDC and SAML as **possible**, an
+  authentication exclusive group and **unknown** inference support, without
+  instance bindings.
+- [ ] Open `bound-r1.json` beside `sources.md` and `research-r1.json`. Expect a
+  **configured** MongoDB Atlas target, **conflicting** OIDC/SAML targets and
+  **unknown** inference. Find the separate OIDC preference; it must not erase
+  either source claim. Expect role/product identities, no actual settings.
+- [ ] Open `bound-r2.json` and `research-r2.json`. Expect the same instance and
+  database binding ID, a self-hosted MongoDB target and exact predecessor
+  references. The original files still show Atlas and the earlier evidence.
+- [ ] Report **Pass / Fail / Blocked**, inspected filenames and any incorrect
+  state, exposed value, lost conflict or broken reference. These are developer
+  fixtures; passing inspection is not installed Researcher acceptance.
+
+### Maintainer preparation and technical readback
+
+From the repository root, use Node.js 22, 24 or 26. Run `npm ci` then
+`npm run build` (exit 0; dependency installation uses the registry). This read-only
+example exercises the library directly, not a skill dependency on a CLI:
+
+```sh
+node --input-type=module <<'JS'
+import {readFileSync} from 'node:fs';
+import {decode, verifyReferences, verifySuccessor} from './dist/index.js';
+const read = name => decode(readFileSync(
+  `examples/researcher/descriptions/${name}.json`, 'utf8'), 'json');
+const context = ['research-r1', 'research-r2', 'capability'].map(read);
+const before = read('bound-r1'), after = read('bound-r2');
+verifyReferences(context[2], context);
+verifyReferences(before, context);
+verifyReferences(after, context);
+verifySuccessor(before, after);
+console.log(before.bindings.map(b => b.state).join(', '));
+console.log(before.bindings[0].claims[0].target);
+console.log(after.bindings[0].claims[0].target);
+JS
+```
+
+Expect exit 0 and exactly:
+
+```text
+configured, conflicting, unknown
+urn:target:atlas
+urn:target:mongodb
+```
+
+The readback changes no files; no cleanup is needed. A nonzero exit or different
+states/targets fails this check. `npm test` covers malformed data, unsupported
+YAML, privacy sentinels, conflicting/exclusive selections and revision/reference
+drift. The package check exercises these assets through an installed library.
+
+## Baseline and evidence boundary
+
+On 8 November 2026, inspection of installed Researcher skill **0.1.9** found its
+explicit statement that it produces working notes and does not generate validated
+research HTML or Surface definitions. This is a prerequisite blocker for the
+requested installed-artifact journey, not an attempted AI investigation or proof
+of generated artifacts. CLI availability is irrelevant to the standalone skill.
+The authorized known gap is implemented here only at the contract/library layer.
+
+The synthetic fixture journey above is the #50 agent rehearsal. It is not
+Researcher-produced findings, an installed-skill rehearsal, human acceptance,
+a real-instance inspection, or evidence of runtime use. #51 must package usable
+standalone artifact production/checking resources; #52 must repeat the actual
+installed conversation and independently read back its saved results.