@n8r/surface 0.1.0-experimental.2 → 0.1.0-experimental.5

package/dist/validate.js

@@ -116,7 +116,22 @@ function references(ids, available, p) {
         if (!available.has(item))
             fail(p, `unresolved reference ${item}`);
 }
+// Inspect only a data descriptor; never invoke an untrusted getter to dispatch.
+function isDescription(input) {
+    return input !== null && typeof input === 'object' &&
+        ['n8r.surface/0.2', 'n8r.surface/0.3'].includes(Object.getOwnPropertyDescriptor(input, 'contract')?.value);
+}
 export function validateArtefact(input) {
+    try {
+        return validate(input);
+    }
+    catch (error) {
+        if (isDescription(input))
+            fail('$description', 'invalid structure, identity, state or reference');
+        throw error;
+    }
+}
+function validate(input) {
     canonical(input); // checks portable values, depth and logical size before field access
     const data = object(input, '$');
     if (data.contract === 'n8r.research/0.1') {
@@ -154,6 +169,12 @@ export function validateArtefact(input) {
             references([e.to], nodes, e.id);
         }
     }
+    else if (data.contract === 'n8r.surface/0.2') {
+        validateDescription(input);
+    }
+    else if (data.contract === 'n8r.surface/0.3') {
+        validateGraph(input);
+    }
     else
         fail('$.contract', 'unsupported contract/version');
     const a = input;
@@ -163,9 +184,23 @@ export function validateArtefact(input) {
 }
 /** Explicit offline bundle verification. Missing external context is an error here. */
 export function verifyReferences(input, context) {
+    try {
+        verifyContext(input, context);
+    }
+    catch (error) {
+        if (isDescription(input))
+            fail('$description', 'invalid or unavailable evidence, capability or exclusive selection');
+        throw error;
+    }
+}
+function verifyContext(input, context) {
     const a = validateArtefact(input);
     const records = context.map(validateArtefact);
     unique(records.map(r => JSON.stringify([r.id, r.revision.id])), '$context');
+    if (a.contract === 'n8r.surface/0.2' || a.contract === 'n8r.surface/0.3') {
+        verifyDescriptionContext(a, records);
+        return;
+    }
     if (a.contract !== 'n8r.surface/0.1')
         return;
     for (const ref of a.records) {
@@ -182,3 +217,266 @@ export function verifyReferences(input, context) {
             }
     }
 }
+const basis = shape({ record: id, revision: token, items: array(id, 1) });
+const descriptionType = shape({ vocabulary: id, term: text });
+const descriptionCommon = {
+    ...common, contract: oneOf('n8r.surface/0.2'), extensions: shape({}),
+    records: array(ref), vocabularies: array(shape({ id, version: token })),
+    nodes: array(shape({ id, label: text, type: descriptionType })),
+    coverage: array(text), gaps: array(text)
+};
+const capabilityShape = shape({
+    ...descriptionCommon, kind: oneOf('capability'),
+    capabilities: array(shape({ id, from: id, to: id, type: descriptionType,
+        state: oneOf('possible', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope', 'conflicting'),
+        basis: array(basis), conditions: array(text), note: text })),
+    exclusiveGroups: array(shape({ id, members: array(id, 2) }))
+});
+const boundShape = shape({
+    ...descriptionCommon, kind: oneOf('bound'), capability: ref,
+    instance: shape({ id, label: text }),
+    bindings: array(shape({ id, capability: id,
+        state: oneOf('configured', 'unknown', 'omitted', 'redacted', 'out-of-scope', 'conflicting'),
+        claims: array(shape({ target: id, basis: array(basis, 1) })), decisions: array(basis), note: text }))
+});
+function descriptionBases(a) {
+    return a.kind === 'capability' ? a.capabilities.flatMap(c => c.basis) :
+        a.bindings.flatMap(b => [...b.decisions, ...b.claims.flatMap(c => c.basis)]);
+}
+function validateDescription(input) {
+    const data = object(input, '$');
+    (data.kind === 'capability' ? capabilityShape : boundShape)(input, '$');
+    const a = input;
+    const entries = a.kind === 'capability' ? [...a.capabilities, ...a.exclusiveGroups] : a.bindings;
+    unique([a.id, ...a.nodes.map(n => n.id), ...entries.map(e => e.id), ...(a.kind === 'bound' ? [a.instance.id] : [])], '$');
+    const nodes = new Set(a.nodes.map(n => n.id));
+    const vocab = unique(a.vocabularies.map(v => v.id), '$.vocabularies');
+    const records = unique(a.records.map(r => JSON.stringify([r.id, r.revision])), '$.records');
+    for (const n of a.nodes)
+        references([n.type.vocabulary], vocab, '$.nodes');
+    for (const b of descriptionBases(a)) {
+        references([JSON.stringify([b.record, b.revision])], records, '$.basis');
+        unique(b.items, '$.basis.items');
+    }
+    if (a.kind === 'capability') {
+        for (const c of a.capabilities) {
+            references([c.from], nodes, '$.capabilities.from');
+            references([c.to], nodes, '$.capabilities.to');
+            references([c.type.vocabulary], vocab, '$.capabilities.type');
+            if (['possible', 'absent', 'conflicting'].includes(c.state) && !c.basis.length)
+                fail('$', 'evidence required');
+        }
+        for (const group of a.exclusiveGroups)
+            references(group.members, new Set(a.capabilities.map(c => c.id)), '$.exclusiveGroups');
+    }
+    else {
+        unique(a.bindings.map(b => b.capability), '$.bindings.capability');
+        for (const b of a.bindings) {
+            const count = b.claims.length;
+            if (b.state === 'configured' ? count !== 1 : b.state === 'conflicting' ? count < 2 : count !== 0)
+                fail('$', 'state/claims mismatch');
+            references(b.claims.map(c => c.target), nodes, '$.bindings.targets');
+        }
+    }
+}
+function verifyDescriptionContext(a, context) {
+    const research = a.records.map(ref => {
+        const r = context.find(r => r.id === ref.id && r.revision.id === ref.revision);
+        if (!r || r.contract !== 'n8r.research/0.1' || digest(r) !== ref.digest)
+            fail('$', 'research revision/digest unavailable');
+        return r;
+    });
+    const items = (bases, decisions = false) => bases.flatMap(b => {
+        const r = research.find(r => r.id === b.record && r.revision.id === b.revision);
+        return b.items.map(id => {
+            const item = (decisions ? r.decisions : r.findings).find(f => f.id === id);
+            if (!item)
+                fail('$', 'wrong or missing evidence item kind');
+            return item;
+        });
+    });
+    const findings = (bases) => items(bases);
+    if (a.contract === 'n8r.surface/0.3')
+        verifyRelationshipDetails(a, research);
+    const verifySupport = (c) => {
+        const fs = findings(c.basis);
+        if (fs.some(f => f.subject !== c.from || f.property !== 'supports'))
+            fail('$', 'capability evidence subject/property mismatch');
+        if (c.state === 'possible' && (!fs.length || fs.some(f => f.state !== 'known' || f.claims.some(cl => cl.value !== c.to))))
+            fail('$', 'possible requires supported target evidence');
+        if (c.state === 'absent' && (!fs.length || fs.some(f => f.state !== 'absent' || f.claims.some(cl => cl.value !== c.to))))
+            fail('$', 'absent requires scoped absence evidence');
+        if (c.state === 'conflicting' && !fs.some(f => f.state === 'conflicting'))
+            fail('$', 'conflicting requires conflicting finding');
+    };
+    if (a.kind === 'capability') {
+        for (const c of capabilityEdges(a))
+            verifySupport(c);
+        return;
+    }
+    const ref = a.capability;
+    const c = context.find(c => c.id === ref.id && c.revision.id === ref.revision);
+    if (!c || (c.contract !== 'n8r.surface/0.2' && c.contract !== 'n8r.surface/0.3') || c.contract !== a.contract || c.kind !== 'capability' || digest(c) !== ref.digest)
+        fail('$', 'capability revision/digest unavailable');
+    verifyDescriptionContext(c, context);
+    // A shared node ID denotes the same component; an instance is a distinct identity.
+    if ([c.id, ...c.nodes.map(n => n.id), ...capabilityEdges(c).map(e => e.id)].includes(a.instance.id))
+        fail('$', 'instance identity reused');
+    for (const n of a.nodes) {
+        const old = c.nodes.find(x => x.id === n.id);
+        if (old && canonical(old.type) !== canonical(n.type))
+            fail('$', 'shared component type changed');
+    }
+    if (a.contract === 'n8r.surface/0.3') {
+        for (const edge of a.relationships) {
+            const base = capabilityEdges(c).find(x => x.id === edge.id);
+            if (!base || edge.from !== base.from || edge.to !== base.to || canonical(edge.type) !== canonical(base.type))
+                fail('$', 'relationship differs from pinned Capability');
+            verifySupport({ ...edge, state: base.state });
+        }
+    }
+    for (const b of boundBindings(a)) {
+        const capability = capabilityEdges(c).find(c => c.id === b.capability);
+        if (!capability)
+            fail('$', 'unknown capability');
+        if (b.state === 'configured' && capability.state !== 'possible')
+            fail('$', 'configured requires established possibility');
+        items(b.decisions, true);
+        const targets = new Set(b.claims.map(cl => cl.target));
+        if (b.claims.length) {
+            // Do not allow an author to hide contrary evidence by omitting a basis item.
+            // Only this Bound snapshot's records apply; the pinned Capability may use
+            // older research revisions which must not override the current binding.
+            const matching = research.flatMap(r => r.findings).filter(f => f.subject === a.instance.id && f.property === b.capability &&
+                ['known', 'conflicting'].includes(f.state));
+            for (const f of matching) {
+                if (f.claims.some(cl => typeof cl.value !== 'string' || !targets.has(cl.value)) ||
+                    (b.state === 'configured' && f.state === 'conflicting'))
+                    fail('$', 'omitted contradictory configuration evidence');
+            }
+        }
+        for (const claim of b.claims) {
+            const fs = findings(claim.basis);
+            for (const f of fs) {
+                if (f.subject !== a.instance.id || f.property !== b.capability ||
+                    !['known', 'conflicting'].includes(f.state) ||
+                    !f.claims.some(cl => cl.value === claim.target) ||
+                    f.claims.some(cl => typeof cl.value !== 'string' || !targets.has(cl.value)))
+                    fail('$', 'binding evidence mismatch or suppressed conflict');
+                if (b.state === 'configured' && f.state !== 'known')
+                    fail('$', 'conflict cannot establish configured');
+            }
+        }
+    }
+    for (const group of c.exclusiveGroups) {
+        if (boundBindings(a).filter(b => b.state === 'configured' && group.members.includes(b.capability)).length > 1)
+            fail('$', 'exclusive capabilities configured together');
+    }
+}
+function capabilityEdges(a) {
+    return a.contract === 'n8r.surface/0.3' ? a.relationships : a.capabilities;
+}
+function boundBindings(a) {
+    return a.contract === 'n8r.surface/0.3' ? a.relationships.map(e => ({ id: e.id, capability: e.id, ...e.binding })) : a.bindings;
+}
+const configLocation = (v, p) => {
+    text(v, p);
+    const s = v;
+    if (s.startsWith('/') || /[\\:?#%]/.test(s) || s.split('/').some(part => !part || part === '.' || part === '..'))
+        fail(p, 'requires safe relative documentation location');
+};
+const configReference = shape({ owner: id, mechanism: oneOf('environment-variable', 'file-key', 'argument', 'admin-setting', 'code'), key: text, location: configLocation });
+const detailShape = (check) => (v, p) => {
+    shape({ state: oneOf('known', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope', 'conflicting'),
+        claims: array(shape({ value: check, basis: array(basis, 1) })), note: text })(v, p);
+    const d = v;
+    const count = d.claims.length;
+    if (d.state === 'known' || d.state === 'absent') {
+        if (count !== 1)
+            fail(p, 'known/absent requires one evidenced claim');
+    }
+    else if (d.state === 'conflicting') {
+        if (count < 2 || new Set(d.claims.map(c => canonical(c))).size !== count)
+            fail(p, 'conflicting requires distinct evidenced claims');
+    }
+    else if (count)
+        fail(p, 'non-value state cannot carry claims');
+};
+const sharedRelationship = { id, from: id, to: id, type: descriptionType,
+    basis: array(basis), conditions: array(text), note: text,
+    purpose: detailShape(text), integration: detailShape(text), configuration: detailShape(array(configReference)) };
+const bindingAnnotation = shape({
+    state: oneOf('configured', 'unknown', 'omitted', 'redacted', 'out-of-scope', 'conflicting'),
+    claims: array(shape({ target: id, basis: array(basis, 1) })), decisions: array(basis), note: text
+});
+const graphCommon = { ...descriptionCommon, contract: oneOf('n8r.surface/0.3') };
+const capabilityGraphShape = shape({ ...graphCommon, kind: oneOf('capability'),
+    relationships: array(shape({ ...sharedRelationship, state: oneOf('possible', 'unknown', 'omitted', 'redacted', 'absent', 'out-of-scope', 'conflicting') })),
+    exclusiveGroups: array(shape({ id, members: array(id, 2) })) });
+const boundGraphShape = shape({ ...graphCommon, kind: oneOf('bound'), capability: ref, instance: shape({ id, label: text }),
+    relationships: array(shape({ ...sharedRelationship, binding: bindingAnnotation })) });
+const detailNames = ['purpose', 'integration', 'configuration'];
+function validateGraph(input) {
+    const data = object(input, '$');
+    (data.kind === 'capability' ? capabilityGraphShape : boundGraphShape)(input, '$');
+    const a = input;
+    // Reuse the bounded 0.2 local state/identity checks without changing the input
+    // or the meaning/version of either serialized contract.
+    const legacy = a.kind === 'capability' ? {
+        ...a, contract: 'n8r.surface/0.2', capabilities: a.relationships.map(e => {
+            const { purpose, integration, configuration, ...core } = e;
+            return core;
+        })
+    } : { ...a, contract: 'n8r.surface/0.2', bindings: boundBindings(a) };
+    delete legacy.relationships;
+    validateDescription(legacy);
+    const nodes = new Set(a.nodes.map(n => n.id));
+    const vocab = new Set(a.vocabularies.map(v => v.id));
+    const records = new Set(a.records.map(r => JSON.stringify([r.id, r.revision])));
+    for (const e of a.relationships) {
+        references([e.from], nodes, '$.relationships.from');
+        references([e.to], nodes, '$.relationships.to');
+        references([e.type.vocabulary], vocab, '$.relationships.type');
+        const bases = [...e.basis, ...detailNames.flatMap(name => e[name].claims.flatMap(c => c.basis))];
+        for (const b of bases) {
+            references([JSON.stringify([b.record, b.revision])], records, '$.relationships.basis');
+            unique(b.items, '$.relationships.items');
+        }
+        for (const claim of e.configuration.claims)
+            for (const config of claim.value)
+                references([config.owner], nodes, '$.configuration.owner');
+    }
+}
+function verifyRelationshipDetails(a, research) {
+    for (const e of a.relationships)
+        for (const property of detailNames) {
+            const detail = e[property];
+            const values = new Set(detail.claims.map(c => canonical(c.value)));
+            const assertions = new Set();
+            for (const claim of detail.claims)
+                for (const b of claim.basis) {
+                    const r = research.find(r => r.id === b.record && r.revision.id === b.revision);
+                    for (const id of b.items) {
+                        const f = r.findings.find(f => f.id === id);
+                        if (!f || f.subject !== e.id || f.property !== property ||
+                            (detail.state === 'known' ? f.state !== 'known' : detail.state === 'absent' ? f.state !== 'absent' : !['known', 'absent', 'conflicting'].includes(f.state)) ||
+                            !f.claims.some(c => canonical(c.value) === canonical(claim.value)) ||
+                            f.claims.some(c => !values.has(canonical(c.value))))
+                            fail('$', 'relationship detail evidence mismatch');
+                        assertions.add(f.state);
+                    }
+                }
+            if (detail.state === 'conflicting' && values.size < 2 &&
+                !(assertions.has('known') && assertions.has('absent')))
+                fail('$', 'agreeing evidence does not establish conflict');
+            if (detail.claims.length) {
+                const matching = research.flatMap(r => r.findings).filter(f => f.subject === e.id && f.property === property);
+                for (const f of matching) {
+                    if (f.claims.some(c => !values.has(canonical(c.value))) ||
+                        (detail.state === 'known' && ['absent', 'conflicting'].includes(f.state)) ||
+                        (detail.state === 'absent' && ['known', 'conflicting'].includes(f.state)))
+                        fail('$', 'omitted contradictory relationship detail');
+                }
+            }
+        }
+}

package/docs/n8r-surface/cli-bundles.md

@@ -0,0 +1,72 @@
+# CLI Capability and Bound bundles
+
+The CLI candidate uses the same checked artifact machinery as Researcher skill
+0.1.11. New research can stage `n8r.surface/0.3` Capability or Bound bundles.
+`/save surface` saves the preview's brief, research HTML, Surface JSON, pinned
+dependencies and manifest in the next numbered directory. Reopening either
+`research.html` or `surface.json` reads and checks the complete bundle.
+
+Existing `n8r.surface/0.1` pairs remain readable and can be revised in their
+original format. There is no automatic migration. A Capability and a Bound
+Surface are separate identities; continue a saved description in its original
+kind. Start a new discovery for a different kind. The CLI can also reopen a
+standalone skill bundle. Such a bundle has no CLI runner receipt; historical
+source references are rechecked rather than assigned invented runner provenance.
+
+The runner receives bundled schema examples as synthetic shapes, not findings.
+It computes canonical artifact hashes through a read-only host tool, then stages
+a complete bundle. The host checks current and dependency research sources
+against actual reads or saved evidence. Validation does not establish research
+accuracy, complete secret detection, runtime use or consumer compatibility.
+Use permitted sources or sanitized configuration summaries; do not supply secrets.
+
+## Human verification
+
+Maintainer preparation: install the candidate in the tester's active Node
+installation, confirm Codex sign-in/model access and vault setup, and open the
+terminal in the existing prepared Lumen source directory. Do not ask the tester
+to build packages or find paths. The checks below send that source to OpenAI
+after confirmation. See [using the command](getting-started.md).
+
+- [ ] Run `n8r-surface`. At `You>`, enter: “Research the AI connections in this
+  guide. Keep unknown configuration and runtime use explicit. My decision is to
+  defer runtime verification.” Confirm research. Expect findings based on the
+  guide and the recorded decision. Ask a follow-up question in your own words;
+  the conversation should let you explore freely.
+- [ ] Type `save`. Open the brief or HTML at the returned path. Expect a useful
+  explanation of the connections, source evidence, unknowns and your decision.
+  Type `exit` when you want to leave. No separate Surface-preparation command is
+  required; saving does not end the conversation.
+- [ ] Run `n8r-surface` again and select the saved title by its number. Expect
+  the previous research and decision to return without copying a file path.
+  Say: “Keep my runtime-verification deferral. Add my decision to defer external
+  OIDC investigation because model-service configuration is the priority.”
+  Then type `save`. Expect a new saved result with both decisions; the previous
+  result remains available and unchanged. Type `exit` to leave (exit 0).
+- [ ] Report **Pass / Fail / Blocked** and any point where the experience was
+  confusing or the result was wrong, with the saved links. Wording and filenames
+  can vary. Missing saves, lost decisions or overwritten files fail. Missing
+  installation or sign-in is blocked. Keep the saved work; no cleanup is needed.
+
+Maintainer evidence checks cover exact parent digests, preserved source/settings
+bytes, dependency validation and the local recent-work index. They do not replace
+the user's judgment of the conversation and result.
+
+## Maintainer evidence
+
+At baseline `5eed2ac`, the installed CLI completed the first interaction but
+saved `n8r.surface/0.1`. Candidate regression checks cover shared-helper readback,
+fresh-store successors, dependency corruption, lost decisions, standalone skill
+reopening and legacy pairs. Real-run evidence is recorded with the implementing
+PR; automated checks are not human acceptance or publication evidence.
+
+On 8 November 2026 an installed development tarball based on `5eed2ac` (dirty)
+completed the exact two-session task above with Node 26.13.0, Codex 0.166.0 and
+`gpt-6-astra` using ChatGPT sign-in. Both processes exited 0. Independent helper
+readback verified Capability kind, exact research/Surface parents, retained
+component IDs and runtime deferral, added OIDC deferral and pinned dependencies.
+Source, settings and every predecessor file remained unchanged. Tarball SHA-256:
+`0a4cc51d39327dfab67e186516f9eef1a01efcb1369c7ae35a9cb843e62c458f`.
+This is an agent rehearsal, not a new human acceptance or registry release.
+Subsequent changes broadened dependency-source checks and preserved optional
+runner/note receipts; final candidate verification must identify its own bytes.

package/docs/n8r-surface/command-outcomes.md

@@ -24,6 +24,54 @@ user: define a real task, attempt it through the product, observe the gap, devel
 what is missing, then repeat the same task. It does not publish private Lab
 implementation material or require that application to be running.
 
+Candidate skill 0.1.10 adds standalone Capability/Bound artifact production and
+revision, without adding a CLI command. See the [task, evidence and human
+check](skill-surface-artifacts.md). Installed rehearsal and human acceptance remain
+distinct from contract checks.
+
+## Open, research, save and return (#17)
+
+Given a configured vault and signed-in Codex, running `n8r-surface` in a terminal
+opens a research prompt and lists saved work by title. Type the investigation;
+the current folder is the default source. Optional `/source PATH` changes it. Confirm source
+transmission once, then converse normally. Type `save` to save the result and
+`exit` to leave. Running `n8r-surface` again offers the saved title; selecting its
+number reopens it with the remembered source and model. Save a successor without
+replacing earlier files. Missing/moved sources require a new source selection.
+
+Plain `save`, `save the result` and guided `/save` prepare a checked Surface if
+needed and persist it only after validation. `/save note` saves Markdown.
+Explicit `discover`, `reopen`, their options and legacy `/save` note behavior
+remain available. Noninteractive startup retains the read-only overview.
+A local recent-work index beside settings remembers source/model/output paths;
+it is not part of portable Surface data. Index failure must not conceal an
+otherwise successful artifact save. No saved outputs are removed by this flow.
+
+Installed .3 baseline prints configuration and exits after vault readiness;
+it offers no research prompt or remembered-work selection. Verification will
+exercise bare startup, plain-language research/save, exit and fresh startup
+selection through the installed command, then independently check the files.
+
+## CLI Capability/Bound increment (#17)
+
+Given an installed candidate, a configured vault, Codex 0.166.0 signed in with
+ChatGPT and permitted local sources, ask `discover SOURCE` to prepare a Capability
+or Bound Surface. Enter `/save surface`, exit, then run
+`reopen SAVED/surface.json --source SOURCE` and request a successor. The same
+commands remain public; there is no new subcommand or automatic migration.
+
+Expected: a preview distinguishes possibilities from configured bindings;
+explicit save creates brief, HTML, JSON, dependencies and a checked manifest in
+the next numbered directory. Fresh reopening retains exact dependencies,
+identities, human decisions and parent references. Read the files independently
+and compare predecessor/source bytes. Existing 0.1 pairs remain readable and
+continue in their original format. No runtime-use or Labs compatibility follows.
+
+The installed baseline at `5eed2ac` produced an older 0.1 definition for the
+Capability request. The installed development candidate completed save/reopen/revise with independent
+readback; see [the task and bounded evidence](cli-bundles.md). Final candidate
+bytes and human acceptance remain separate from that rehearsal.
+
 ## Grow the specification with working verification
 
 Work one useful behavior at a time, including behavior that already exists. Add a
@@ -55,10 +103,12 @@ Current progress, with evidence defining the verified scope and revision:
 
 | User or consumer intent | Current progress | Verification / next increment |
 | --- | --- | --- |
+| Create, repeat and reopen a standalone workspace through the skill. | Specified in accepted #41; helper and skill candidate 0.1.9 implemented. Installed-product scenarios and readback passed; overall PM acceptance pending. No new CLI command. | [Workspace contract](workspace.md), [human tasks](workspace-human-check.md), [evidence](workspace-verification.md). |
 | Create a security-focused skeleton and reconcile a later declaration change. | Skeleton Surface v0.1 guidance in installed skill 0.1.8; bounded agent brief/successor rehearsal and readback passed. Human acceptance pending; no new CLI command or Lab automation. | [SKELETON-01/02 prompts and readback](researcher-skeleton-check.md); [versioned results and remaining acceptance](researcher-skill-verification.md#skeleton-surface-018). |
 | Read saved research and selected definitions through the library, retaining identities, findings and references. | Implemented and verified for the experimental library profile; no command claim. | [CONTRACT-01 and repeatable fixture/package checks](verification.md#contract-01-retain-useful-attributable-research-and-selected-definitions). |
 | Run `n8r-surface` alone and see settings, saved artefacts and known process status. | Specified, implemented and verified for the read-only overview and guidance question; setup/conversation unavailable. | [STARTUP-01 installed evidence at `b90358a`](startup-verification.md). Historical read-only baseline; setup supersedes its guidance and exit behavior. |
 | Choose a local vault once and reuse it from another source directory. | Setup-only implementation; installed rehearsal and human acceptance tracked separately. | [SETUP-01 evidence and tasks](vault-setup-verification.md). Research and continuation remain pending. |
+| Begin with a description and establish source access progressively. | Candidate 0.1.16 guidance; baseline rehearsal recorded, web acceptance tracked separately. No new CLI command or access adapter. | [First-use tasks and evidence](first-use-access.md). |
 | Research supplied sources through the installed skill and save working notes. | Implemented; bounded Lumen and LibreChat agent rehearsals have saved/read back notes. Actual human input survived fresh-agent continuation; Work UI acceptance remains pending. | [RESEARCH-01 evidence and limits](researcher-skill-verification.md). No structured-output or standalone-runner claim. |
 | Offer to retain an initial partial graph when saving is undecided. | Implemented in skill 0.1.7; acceptance and evidence are tracked separately. | [Optional save offer](researcher-skill-verification.md#optional-save-offer-017). |
 | Resume from saved recommendations and retain useful next investigations. | Implemented in skill 0.1.6; installed fresh-agent save/continue and independent readback passed. Human acceptance remains pending. | [Recommendations evidence](researcher-skill-verification.md#saved-recommendations-016) and [prepared interaction](researcher-prepared-check.md). |
@@ -545,8 +595,8 @@ validation and read-only release mapping verification. Synthetic Git repositorie
 exercise missing/wrong tags, dirty source, altered archives and release metadata;
 they do not establish an authenticated release or registry provenance. The public
 CLI inventory is unchanged; `check:version` and `check:release` are maintainer npm
-scripts. Real release verification remains blocked until an authorized release
-and publishing setup exist.
+scripts. The subsequent [scoped release](npm-release.md#verified-scoped-release)
+adds authenticated release and registry evidence beyond those synthetic checks.
 
 ## RELEASE-01: prepare and publish the first dual release
 
@@ -560,5 +610,102 @@ The manual workflow prepares retained archives before publication and verifies
 existing registry bytes before staging only absent versions for maintainer 2FA approval. Tests cover altered
 bytes, wrong registry identity/integrity, partial-publication recovery and network
 failure. These use synthetic registry boundaries, not authenticated publication.
-Live workflow, registry installation, cryptographic provenance and immutable
-release acceptance remain unverified until the documented release procedure runs.
+Before the release procedure ran, live workflow, registry installation,
+cryptographic provenance and immutable release acceptance were unverified.
+The subsequent scoped-only result is recorded below.
+
+### Verified first-release outcome
+
+The maintainer narrowed RELEASE-01 to scoped-only publication. On 5 November
+2026, `@n8r/surface@0.1.0-experimental.2` passed exact registry byte/integrity,
+installed library/assets/CLI, isolated startup and signed-provenance checks.
+The GitHub prerelease was finalized and read back as immutable. See the
+[release evidence](npm-release.md#verified-scoped-release). The unscoped
+submission failed with E403 and was removed from the release scope; no unscoped
+registry success or name protection is claimed. Future workflow adaptation
+must remove dual-package assumptions before another scoped release. Unscoped
+publication and name reservation are no longer planned.
+
+## SKILL-PRESENTATION-01: read a useful checked report
+
+**Implemented candidate 0.1.11.** Given a saved checked Capability/Bound bundle,
+ask the installed Researcher to save a readable presentation copy in a new folder,
+using the same bundle and original predecessor. Expect the current conclusion,
+what changed, bounded significance, cited evidence, decisions and unknowns in
+both HTML and brief. Exact-parent comparison is unavailable when parent research
+is not retained. All checked data and original bytes remain unchanged; the new
+manifest covers the new presentation. No new research or CLI behavior is added.
+See the [human task and readback](skill-surface-artifacts.md#short-human-check).
+
+## SKILL-SURFACE-02: save and continue an investigation
+
+**Candidate 0.1.13 implemented; installed assessment tracked separately.**
+No new product CLI command. Given current-chat supplied sources and an authorized
+Surface destination, ask: “Explain the AI paths, save the Surface and maintain an
+investigation journal as we go.” Expect an initial plan, possible/selected paths,
+inspectable evidence, useful next options and numbered saved revisions.
+
+The state change is a self-contained CycloneDX BOM plus derived brief, HTML map,
+Markdown journal and manifest. Given only the latest BOM in a fresh chat, ask to
+continue: evidence, decisions, uncertainties and investigation state must recover.
+A user-directed diversion remains recorded, with deferred work and its reason.
+Earlier bytes remain unchanged. View edits require explicit reconciliation.
+See the [human tasks and evidence](skill-bom-verification.md) and
+[working manual](skill-manual.md). Automated profile checks do not establish
+research accuracy or human acceptance.
+
+## SKILL-OVERVIEW-01: understand a supplied application
+
+Given the identified 0.1.14 candidate, readable source and a new output folder,
+when the user asks for an initial architecture/security overview and saves it,
+the brief explains application meaning, major areas, evidence-backed implications,
+coverage gaps and next decisions. The HTML shows connected nodes once, before
+relationship/evidence detail. Intended choices remain separate from configuration
+and dated observations. Existing revisions stay unchanged.
+
+Specified in [the first-use verification](first-use-overview.md); renderer and
+research guidance implemented. Installed rehearsal and human acceptance status
+are recorded there. Automated structure checks alone do not verify this outcome.
+
+### SKILL-OVERVIEW-02: continue a source-only investigation
+
+Given a saved source investigation with historical runtime blockers and completed
+work, say: “It is just a source checkout. Record that in the Surface, keep
+deployment settings unverified, and show the most useful source-level investigation
+next. Save a successor.” Expect a short current scope, reconciled findings/gaps,
+one recommended source action, and unchanged predecessor bytes. Obsolete blockers
+and actions remain history, not current requirements. No runtime inventory or
+service startup is needed. The brief discloses omitted list items and links full
+detail; it retains limitations beside displayed findings.
+
+For separately requested inspection of an identified runtime target, emit only
+that target's relevant safe fields. A broad response must be filtered inside the
+collecting process before output; saved redaction alone is insufficient.
+See [rehearsal evidence and human checks](first-use-overview.md#follow-up-rehearsal).
+
+## SKILL-INSTANCE-01: understand and revisit a running composition
+
+Candidate 0.1.15 adds research guidance; no product CLI command or access adapter.
+Given an identified target, permitted host access to sources/instance evidence and
+a private destination, ask: “Understand this running system, show what is
+configured, observed and untested, and save the Surface.” Expect source identity,
+scoped observations, a useful composition beyond a single repository, explicit
+access gaps and saved BOM/brief/map/journal readback. No probes or service changes.
+
+Continue from that BOM with current permitted evidence. Expect unchanged stable
+identities and predecessor bytes, with actual target changes distinguished from
+newly learned facts, unchanged checked facts, lost coverage and conflicts. A host
+without required access or saving tools must report the blocked portion without
+fabricating results. Source-only requests need no runtime inventory.
+See the [human tasks and bounded verification](instance-first-research.md).
+
+## SKILL-ACCESS-01: begin without prepared connections
+
+Given a fresh session and a description/document, with laptop source and VPS
+access only mentioned, ask Researcher to understand the system and help provide
+sources. Expect a provisional map, one useful next source and host-appropriate
+access guidance. A project upload is not a live folder; SSH details are not access.
+Supply another source and expect progress rather than repeated intake. Saving
+requires observed helper/runtime/delivery capabilities; otherwise retain copyable
+findings and name the blocked step. No credentials in chat or target mutations.
+See [exact interactions, readback and verification status](first-use-access.md).

package/docs/n8r-surface/contracts.md

@@ -12,6 +12,16 @@ make this profile concrete. Other languages can implement the same data contract
 The library reads supplied strings and returns values/strings; it does not read
 files, fetch references, call inference or write a corpus.
 
+The separate JSON-only [Capability and Bound contract 0.2](surface-description-contract.md)
+adds possible relationships and configured instance bindings without reinterpreting
+these selected `0.1` definitions. The APIs accept both versions; their meanings
+and fields remain distinct. Installed-skill production is separate work.
+
+The [shared relationship contract 0.3](surface-relationships.md) adds the same
+component-node and relationship-edge structure to both descriptions, including
+evidenced purpose, integration mechanism and safe configuration references.
+Existing `0.1` and `0.2` representations remain readable.
+
 ## Common envelope and identity
 
 Every artefact has these required fields. Objects are closed except the explicit

package/docs/n8r-surface/critical-path.md

@@ -1,5 +1,26 @@
 # n8r-surface critical path
 
+The [security assurance strategy agreed on 12 November 2026](security-assurance-strategy.md)
+sets the destination: a consultant-led framework connecting policy and levels to
+controls, implementation and observable tests. Its
+[milestone map](security-assurance-strategy.md#existing-work-and-proposed-next-milestones)
+places the existing skill, pending acceptance and proposed first framework slice
+in that context. The delivery history below does not define a complete assurance
+framework or establish a posture score.
+
+The [product direction captured on 11 November 2026](product-direction.md)
+proposes a first value demonstration: installed-skill discovery across sources,
+a bounded security finding on an integrated test system, and a verified defence.
+It accepts unintegrated sources for discovery and requires runtime evidence for
+runtime claims. This is a proposed acceptance target, not implementation or
+rehearsal evidence; the delivery history and existing obligations below remain.
+
+The next installed-skill delivery agreed on 8 November 2026 is
+[Capability and Bound Surfaces from workspace artifacts](surface-descriptions.md),
+tracked by #50 → #51 → #52 under #17. Observed Surface is deferred. The earlier
+CLI sequence and evidence below remain historical context, not this increment's
+completion criteria.
+
 The user updated delivery order on 5 November 2026: standalone Codex research,
 Markdown save/reopen, then partial Surface generation and a complete fresh-session
 revision proof. npm distribution ([#27](https://github.com/injectionator/n8r-surface/issues/27))