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

package/dist/surface-bom.js

@@ -0,0 +1,139 @@
+/** Bounded Surface profile over CycloneDX 1.7; no parallel native authority. */
+import { validateBom } from './cyclonedx-validation.js';
+import { privacy } from './skill-artifacts.js';
+import { canonical } from './portable.js';
+import { decodeJsonValue } from './codec.js';
+export const prefix = 'n8r:surface:';
+export const property = (name, value) => ({ name: prefix + name, value: typeof value === 'string' ? value : JSON.stringify(value) });
+function fail(reason) { throw Error(`Surface BOM refused: ${reason}. Input values withheld.`); }
+function requireThat(ok, reason) { if (!ok)
+    fail(reason); }
+const nonempty = (x) => typeof x === 'string' && x.trim().length > 0;
+const strings = (x) => Array.isArray(x) && x.every(nonempty) && new Set(x).size === x.length;
+const date = (x) => typeof x === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d+)?Z$/.test(x) && Number.isFinite(Date.parse(x));
+const keys = (x, required, optional = []) => x && typeof x === 'object' && !Array.isArray(x) && required.every(k => Object.hasOwn(x, k)) && Object.keys(x).every(k => [...required, ...optional].includes(k));
+const unique = (xs) => new Set(xs).size === xs.length;
+export function projectDependencies(edges) {
+    const map = new Map();
+    for (const e of edges)
+        if (e.kind === 'dependency' && e.selection === 'selected') {
+            const targets = map.get(e.from) ?? new Set();
+            targets.add(e.to);
+            map.set(e.from, targets);
+        }
+    return [...map].sort(([a], [b]) => a.localeCompare(b)).map(([ref, to]) => ({ ref, dependsOn: [...to].sort() }));
+}
+/** Parses only the documented profile, checking references and projection consistency. */
+export function checkSurfaceBom(input) {
+    validateBom(input);
+    const b = structuredClone(input);
+    requireThat(nonempty(b.serialNumber) && Number.isSafeInteger(b.version) && b.version > 0 && date(b.metadata?.timestamp), 'revision identity');
+    // Safe profile does not carry endpoints/connection values. Public source URLs are
+    // supported only as externalReferences; source content itself is not persisted.
+    const safe = structuredClone(b);
+    for (const r of safe.externalReferences ?? []) {
+        requireThat(!r.url.startsWith('file:') && !r.url.includes('@') && !/[?]/.test(r.url), 'source locator privacy');
+        if (/^https:\/\//.test(r.url)) {
+            const u = new URL(r.url);
+            requireThat(!u.username && !u.password && !/^\d/.test(u.hostname) && !['localhost'].includes(u.hostname), 'source locator privacy');
+            r.url = 'urn:public-source';
+        }
+    }
+    privacy(safe);
+    const refs = new Set();
+    function visit(x) { if (!x || typeof x !== 'object')
+        return; if (!Array.isArray(x) && Object.hasOwn(x, 'bom-ref')) {
+        requireThat(nonempty(x['bom-ref']) && !refs.has(x['bom-ref']), 'unique BOM references');
+        refs.add(x['bom-ref']);
+    } for (const v of Object.values(x))
+        visit(v); }
+    visit(b);
+    const nodes = new Set([...(b.components ?? []), ...(b.services ?? [])].map(n => n['bom-ref']));
+    const annotations = new Map((b.annotations ?? []).map((a) => [a['bom-ref'], a]));
+    for (const a of annotations.values())
+        requireThat(nonempty(a['bom-ref']) && a.subjects.length > 0 && a.subjects.every((id) => refs.has(id)), 'annotation subjects');
+    for (const c of b.citations ?? []) {
+        requireThat(c.pointers && !c.expressions && refs.has(c.attributedTo) && !c.process, 'citation attribution');
+        for (const p of c.pointers) {
+            requireThat(typeof p === 'string' && p.startsWith('/'), 'citation pointer');
+            let v = b;
+            for (const k of p.slice(1).split('/').map((k) => k.replace(/~1/g, '/').replace(/~0/g, '~'))) {
+                requireThat(v !== null && typeof v === 'object' && Object.hasOwn(v, k), 'citation pointer target');
+                v = v[k];
+            }
+        }
+    }
+    const allowed = ['profile', 'objective', 'scope', 'relationship', 'entry', 'evidence', 'coverage', 'gap', 'predecessor-digest', 'reconciliation', 'migration'];
+    const ps = b.properties ?? [];
+    for (const p of ps)
+        requireThat(p.name.startsWith(prefix) && allowed.includes(p.name.slice(prefix.length)), 'profile property');
+    const values = (key) => ps.filter((p) => p.name === prefix + key).map((p) => p.value);
+    const one = (key) => { const vs = values(key); requireThat(vs.length === 1 && nonempty(vs[0]), 'single ' + key); return vs[0]; };
+    requireThat(one('profile') === '1', 'supported profile version');
+    for (const key of ['predecessor-digest', 'reconciliation', 'migration'])
+        requireThat(values(key).length <= 1, 'single ' + key);
+    const parsed = (key) => values(key).map((s) => { try {
+        return decodeJsonValue(s);
+    }
+    catch {
+        return fail('profile JSON');
+    } });
+    const evidence = parsed('evidence'), relationships = parsed('relationship'), entries = parsed('entry');
+    requireThat(unique(evidence.map(e => e.id)) && unique(relationships.map(e => e.id)) && unique(entries.map(e => e.id)), 'unique profile IDs');
+    const evidenceIds = new Set(evidence.map(e => e.id));
+    for (const e of evidence) {
+        requireThat(keys(e, ['id', 'basis', 'sources', 'applicability']) && annotations.has(e.id) && ['source', 'configuration', 'observation', 'user'].includes(e.basis) && nonempty(e.applicability) && Array.isArray(e.sources), 'evidence record');
+        requireThat(e.basis === 'user' || e.sources.length > 0, 'source-backed evidence');
+        for (const s of e.sources)
+            requireThat(keys(s, ['index', 'locator']) && Number.isSafeInteger(s.index) && s.index >= 0 && b.externalReferences?.[s.index] && nonempty(s.locator), 'source reference');
+    }
+    const evidenceFor = (ids, subjects, basis) => strings(ids) && ids.every(id => evidenceIds.has(id) && subjects.every(n => annotations.get(id).subjects.includes(n)) && (!basis || basis.includes(evidence.find(e => e.id === id).basis)));
+    const presentation = Object.create(null);
+    for (const n of [...(b.components ?? []), ...(b.services ?? [])]) {
+        const hints = (n.properties ?? []).filter((p) => p.name === prefix + 'presentation');
+        requireThat(hints.length <= 1, 'single node presentation');
+        if (!hints.length)
+            continue;
+        let p;
+        try {
+            p = decodeJsonValue(hints[0].value);
+        }
+        catch {
+            return fail('node presentation JSON');
+        }
+        requireThat(keys(p, ['boundary', 'area', 'evidence'], ['focus']) && ['internal', 'external', 'unknown'].includes(p.boundary) && nonempty(p.area) && (p.focus === undefined || typeof p.focus === 'boolean'), 'node presentation shape');
+        requireThat(evidenceFor(p.evidence, [n['bom-ref']]) && (p.boundary === 'unknown' || p.evidence.length > 0), 'node presentation evidence');
+        presentation[n['bom-ref']] = p;
+    }
+    requireThat(Object.values(presentation).filter(p => p.focus).length <= 1, 'single focus application');
+    const edgeKeys = ['id', 'from', 'to', 'kind', 'optionality', 'group', 'support', 'selection', 'observations', 'evidence', 'selectionEvidence', 'purpose', 'mechanism', 'configuration', 'conditions', 'note'];
+    for (const e of relationships) {
+        requireThat(keys(e, edgeKeys) && nonempty(e.id) && nodes.has(e.from) && nodes.has(e.to), 'relationship endpoints/shape');
+        requireThat(['dependency', 'integration', 'hosting', 'data-flow'].includes(e.kind) && ['required', 'optional', 'alternative', 'unknown'].includes(e.optionality) && typeof e.group === 'string', 'relationship kind/optionality');
+        requireThat(e.optionality !== 'alternative' || nonempty(e.group), 'alternative group');
+        requireThat(['supported', 'unknown', 'absent', 'conflicting', 'out-of-scope'].includes(e.support) && ['selected', 'unknown', 'not-selected', 'conflicting'].includes(e.selection), 'relationship states');
+        requireThat([e.purpose, e.mechanism, e.note].every(nonempty) && strings(e.configuration) && strings(e.conditions), 'relationship detail');
+        requireThat(evidenceFor(e.evidence, [e.from, e.to]) && evidenceFor(e.selectionEvidence, [e.from, e.to], ['configuration', 'user']), 'relationship evidence');
+        requireThat(!['supported', 'absent', 'conflicting'].includes(e.support) || e.evidence.length > 0, 'support evidence');
+        requireThat(e.selection === 'unknown' || e.selectionEvidence.length > 0, 'selection evidence');
+        requireThat(e.selection !== 'selected' || !e.configuration.some(x => /\$\{|<[^>]+>|placeholder/i.test(x)), 'placeholder selection');
+        requireThat(Array.isArray(e.observations), 'observations');
+        for (const o of e.observations)
+            requireThat(keys(o, ['at', 'evidence', 'note']) && date(o.at) && nonempty(o.note) && o.evidence.length > 0 && evidenceFor(o.evidence, [e.from, e.to], ['observation']), 'dated observed evidence');
+    }
+    const entryIds = new Set(entries.map(e => e.id));
+    for (const e of entries) {
+        requireThat(keys(e, ['id', 'kind', 'title', 'text', 'status', 'reason', 'access', 'evidence', 'at'], ['parent', 'supersedes']) && [e.id, e.title, e.text, e.reason, e.access].every(nonempty) && date(e.at), 'investigation entry');
+        requireThat(['next', 'question', 'decision', 'diversion', 'finding'].includes(e.kind) && ['open', 'active', 'done', 'deferred', 'superseded'].includes(e.status), 'investigation state');
+        requireThat(strings(e.evidence) && e.evidence.every(id => evidenceIds.has(id)), 'investigation evidence');
+        requireThat(e.kind !== 'decision' || e.evidence.some(id => evidence.find(x => x.id === id)?.basis === 'user'), 'decision provenance');
+        for (const id of [e.parent, e.supersedes])
+            requireThat(id === undefined || (entryIds.has(id) && id !== e.id), 'investigation links');
+    }
+    const deps = (b.dependencies ?? []).map((d) => ({ ref: d.ref, dependsOn: [...(d.dependsOn ?? [])].sort() })).sort((a, z) => a.ref.localeCompare(z.ref));
+    requireThat((b.dependencies ?? []).every((d) => !d.provides) && canonical(deps) === canonical(projectDependencies(relationships)), 'selected dependency projection');
+    requireThat(b.compositions?.some((c) => c.aggregate === 'unknown'), 'bounded coverage declaration');
+    const coverage = values('coverage'), gaps = values('gap');
+    requireThat(strings(coverage) && strings(gaps), 'coverage/gaps');
+    return { bom: b, objective: one('objective'), scope: one('scope'), relationships, entries, evidence, coverage, gaps, presentation };
+}

package/dist/surface-draft.d.ts

@@ -1,8 +1,11 @@
+import { type Bundle } from './skill-artifacts.js';
 import type { ResearchRecord, SurfaceDefinition, Artefact } from './contracts.js';
-export type SurfaceDraft = {
+export type LegacyDraft = {
     research: ResearchRecord;
     surface: SurfaceDefinition;
 };
+export type SurfaceDraft = LegacyDraft | Bundle;
+export declare const isBundle: (draft: SurfaceDraft) => draft is Bundle;
 export type DraftContext = {
     createdAt?: string;
     previous?: SurfaceDraft;
@@ -14,6 +17,6 @@ export declare const revisionRef: (a: Artefact) => {
 };
 /** Preservation beyond the library's bounded lineage checks. */
 export declare function verifyPairSuccessor(before: SurfaceDraft, after: SurfaceDraft): void;
-/** The model supplies contract content; the host owns envelope and record-reference fields. */
+/** New bundles use the shared skill checker; legacy content keeps host-owned envelopes. */
 export declare function prepareSurfaceDraft(input: unknown, context?: DraftContext): SurfaceDraft;
-export declare function previewSurface({ research: r, surface: s }: SurfaceDraft): string;
+export declare function previewSurface(draft: SurfaceDraft): string;

package/dist/surface-draft.js

@@ -1,8 +1,11 @@
+import { checkBundle, verifyBundleSuccessor } from './skill-artifacts.js';
+import { renderBrief } from './skill-presentation.js';
 import { randomUUID } from 'node:crypto';
 import { canonical, digest } from './portable.js';
 import { validateArtefact, verifyReferences } from './validate.js';
 import { verifySuccessor } from './revisions.js';
 import { InspectionError } from './settings.js';
+export const isBundle = (draft) => draft.surface.contract === 'n8r.surface/0.3';
 export const revisionRef = (a) => ({ id: a.id, revision: a.revision.id, digest: digest(a) });
 const error = (s) => { throw new InspectionError(s); };
 function retained(before, after, label) {
@@ -12,6 +15,10 @@ function retained(before, after, label) {
 }
 /** Preservation beyond the library's bounded lineage checks. */
 export function verifyPairSuccessor(before, after) {
+    if (isBundle(before) && isBundle(after)) {
+        verifyBundleSuccessor(before, after);
+        return;
+    }
     verifySuccessor(before.research, after.research);
     verifySuccessor(before.surface, after.surface);
     for (const key of ['sources', 'findings', 'alternatives', 'decisions', 'questions'])
@@ -44,12 +51,19 @@ export function verifyPairSuccessor(before, after) {
                 error(`Preserve opaque extension ${name}`);
         }
 }
-/** The model supplies contract content; the host owns envelope and record-reference fields. */
+/** New bundles use the shared skill checker; legacy content keeps host-owned envelopes. */
 export function prepareSurfaceDraft(input, context = {}) {
     canonical(input); // bound size/depth and reject non-data before inspecting it
     const raw = input;
-    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || Object.keys(raw).sort().join(',') !== 'research,surface')
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw) || !['research,surface', 'dependencies,research,surface'].includes(Object.keys(raw).sort().join(',')))
         error('Expected research and surface content objects');
+    if (raw?.surface?.contract === 'n8r.surface/0.3') {
+        const bundle = checkBundle(JSON.parse(JSON.stringify(raw)));
+        if (context.previous) {
+            verifyPairSuccessor(context.previous, bundle);
+        }
+        return bundle;
+    }
     const data = JSON.parse(JSON.stringify(raw));
     const createdAt = context.createdAt ?? new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
     for (const key of ['research', 'surface']) {
@@ -83,7 +97,10 @@ export function prepareSurfaceDraft(input, context = {}) {
         verifyPairSuccessor(context.previous, draft);
     return draft;
 }
-export function previewSurface({ research: r, surface: s }) {
+export function previewSurface(draft) {
+    if (isBundle(draft))
+        return renderBrief(draft) + '\nNot saved. Enter /save surface to save exactly this preview.';
+    const { research: r, surface: s } = draft;
     return ['Validated partial Surface preview (declared only; not runtime proof)', s.title,
         'Components:', ...s.nodes.map(n => `  ${n.id} | ${n.label}`),
         'Declared connections:', ...s.relationships.map(e => `  ${e.id}: ${e.from} -> ${e.to} (${e.type.term})`),

package/dist/surface-instructions.d.ts

@@ -1,2 +1,3 @@
 /** Content fields mirror the existing experimental contracts; host metadata is omitted. */
-export declare const surfaceInstructions = "\nSTRUCTURED SURFACE CAPABILITY (host adapter 0.1):\nWhen the user asks to create or update a Surface, call surface_draft with research and surface content objects. This stages a preview only. Never claim a save. Natural-language save requests explain /save surface. /save still saves Markdown. A later user turn invalidates the preview, so restage a revised pair after answering a correction. Retain stable component IDs from notes. If an old label is not namespaced, record the explicit old-to-new mapping in research.notes and show it to the human. Do not silently rename identities.\n\nUse these exact content fields (no contract, id, revision or records; the host assigns them):\nresearch: {title,scope,extensions,sources,findings,alternatives,decisions,questions,notes}.\nsurface: {title,scope,extensions,kind:\"definition\",vocabularies,nodes,relationships,requirements,coverage,gaps}.\nAll collections are arrays except extensions and entity attributes, which are objects. Empty arrays/objects are allowed. Nonempty text is required for text fields. IDs use a URI-style namespace such as urn:lumen:app. All timestamps use real UTC seconds, YYYY-MM-DDTHH:mm:ssZ, without fractions. Only safe integer JSON numbers are supported. Do not add undocumented fields.\n\nSource: {id,location,version,digest,inspectedAt,coverage:[{path,status,note}]}. location is a portable relative source path from an ACTUAL source_read/search or saved host evidence, never an absolute path. digest must be the exact SHA-256 from that tool or saved host evidence. Never invent a digest. status is inspected|missing|unreadable|excluded|truncated|unsupported. Record ranges and limits. On revision retain historical source objects exactly and add a new source ID for new bytes or inspection; never relabel old evidence as fresh.\nFinding: {id,subject,property,state,note,claims:[{value,evidence:[{source,locator}]}]}. subject is a component ID; evidence.source references sources[].id. state is known|unknown|omitted|redacted|absent|out-of-scope|conflicting. known/absent require one agreed sourced value; conflicting requires different sourced values; other states require empty claims. Every claim requires evidence. Keep human decisions separate from sourced claims.\nAlternative: {id,title,findings:[finding IDs],requirements:[text descriptions]}.\nDecision: {id,alternative,choice:\"selected\"|\"rejected\"|\"deferred\",reason,by,at}. One current decision per alternative. Use actual human choices, never infer selection from support. Preserve prior choices unless the human changes them. Record an explicit correction's reason and date; previous revisions retain prior choices.\nQuestion: {id,text,findings:[finding IDs]}. Note: {by,at,text}. Keep human prose, unresolved questions and recommended next investigations.\nVocabulary: {id,version}; version is a token such as 0.1. Use an explicitly scoped provisional vocabulary, not a claim of universal compatibility.\nNode: {id,label,type:{vocabulary,term},attributes:{property:{state,note,value?}},basis:[{items:[finding/decision/alternative/question IDs]}],requirements:[requirement IDs]}.\nRelationship: same fields as a node EXCEPT no label, plus {from:node ID,to:node ID,claim:\"declared\"}. Keep endpoint identity for retained relationship IDs. Only selected composition belongs in relationships. A supported option is not automatically selected. Shared components, cycles and parallel edges are allowed.\nFact state is known|unknown|omitted|redacted|absent|out-of-scope. Only known facts have a value; all other states omit value. Put conflicting values in research and unknown in the Surface with an explanatory note.\nRequirement: {id,kind:\"secret\"|\"resource\"|\"configuration\",description,state}. Never include credential values. coverage and gaps are arrays of nonempty strings. Surface basis contains only items; the host fills the exact research record/revision and digest.\n\nOn pair reopening keep research and Surface identities via host bookkeeping. Retain all research sources, findings, alternatives, decisions, questions and component IDs. Keep historical claims and research notes exactly; append corrections and new evidence instead of removing history. Every node and relationship needs nonempty basis linking structured findings/decisions. Retained finding subjects/properties and node types cannot change; retain opaque extensions exactly. Removed selections remain rejected/deferred in research. Preserve prior unknowns unless evidence resolves them. Explain source unavailable/changed status and distinguish declared from reachable or exercised. On validation error, repair the staged content using feedback; do not discard evidence to make validation pass.\n";
+export declare const legacySurfaceInstructions = "\nSTRUCTURED SURFACE CAPABILITY (host adapter 0.1):\nWhen the user asks to create or update a Surface, call surface_draft with research and surface content objects. This stages a preview only. Never claim a save. Natural-language save requests explain /save surface. /save still saves Markdown. A later user turn invalidates the preview, so restage a revised pair after answering a correction. Retain stable component IDs from notes. If an old label is not namespaced, record the explicit old-to-new mapping in research.notes and show it to the human. Do not silently rename identities.\n\nUse these exact content fields (no contract, id, revision or records; the host assigns them):\nresearch: {title,scope,extensions,sources,findings,alternatives,decisions,questions,notes}.\nsurface: {title,scope,extensions,kind:\"definition\",vocabularies,nodes,relationships,requirements,coverage,gaps}.\nAll collections are arrays except extensions and entity attributes, which are objects. Empty arrays/objects are allowed. Nonempty text is required for text fields. IDs use a URI-style namespace such as urn:lumen:app. All timestamps use real UTC seconds, YYYY-MM-DDTHH:mm:ssZ, without fractions. Only safe integer JSON numbers are supported. Do not add undocumented fields.\n\nSource: {id,location,version,digest,inspectedAt,coverage:[{path,status,note}]}. location is a portable relative source path from an ACTUAL source_read/search or saved host evidence, never an absolute path. digest must be the exact SHA-256 from that tool or saved host evidence. Never invent a digest. status is inspected|missing|unreadable|excluded|truncated|unsupported. Record ranges and limits. On revision retain historical source objects exactly and add a new source ID for new bytes or inspection; never relabel old evidence as fresh.\nFinding: {id,subject,property,state,note,claims:[{value,evidence:[{source,locator}]}]}. subject is a component ID; evidence.source references sources[].id. state is known|unknown|omitted|redacted|absent|out-of-scope|conflicting. known/absent require one agreed sourced value; conflicting requires different sourced values; other states require empty claims. Every claim requires evidence. Keep human decisions separate from sourced claims.\nAlternative: {id,title,findings:[finding IDs],requirements:[text descriptions]}.\nDecision: {id,alternative,choice:\"selected\"|\"rejected\"|\"deferred\",reason,by,at}. One current decision per alternative. Use actual human choices, never infer selection from support. Preserve prior choices unless the human changes them. Record an explicit correction's reason and date; previous revisions retain prior choices.\nQuestion: {id,text,findings:[finding IDs]}. Note: {by,at,text}. Keep human prose, unresolved questions and recommended next investigations.\nVocabulary: {id,version}; version is a token such as 0.1. Use an explicitly scoped provisional vocabulary, not a claim of universal compatibility.\nNode: {id,label,type:{vocabulary,term},attributes:{property:{state,note,value?}},basis:[{items:[finding/decision/alternative/question IDs]}],requirements:[requirement IDs]}.\nRelationship: same fields as a node EXCEPT no label, plus {from:node ID,to:node ID,claim:\"declared\"}. Keep endpoint identity for retained relationship IDs. Only selected composition belongs in relationships. A supported option is not automatically selected. Shared components, cycles and parallel edges are allowed.\nFact state is known|unknown|omitted|redacted|absent|out-of-scope. Only known facts have a value; all other states omit value. Put conflicting values in research and unknown in the Surface with an explanatory note.\nRequirement: {id,kind:\"secret\"|\"resource\"|\"configuration\",description,state}. Never include credential values. coverage and gaps are arrays of nonempty strings. Surface basis contains only items; the host fills the exact research record/revision and digest.\n\nOn pair reopening keep research and Surface identities via host bookkeeping. Retain all research sources, findings, alternatives, decisions, questions and component IDs. Keep historical claims and research notes exactly; append corrections and new evidence instead of removing history. Every node and relationship needs nonempty basis linking structured findings/decisions. Retained finding subjects/properties and node types cannot change; retain opaque extensions exactly. Removed selections remain rejected/deferred in research. Preserve prior unknowns unless evidence resolves them. Explain source unavailable/changed status and distinguish declared from reachable or exercised. On validation error, repair the staged content using feedback; do not discard evidence to make validation pass.\n";
+export declare const surfaceInstructions: string;

package/dist/surface-instructions.js

@@ -1,5 +1,5 @@
 /** Content fields mirror the existing experimental contracts; host metadata is omitted. */
-export const surfaceInstructions = `
+export const legacySurfaceInstructions = `
 STRUCTURED SURFACE CAPABILITY (host adapter 0.1):
 When the user asks to create or update a Surface, call surface_draft with research and surface content objects. This stages a preview only. Never claim a save. Natural-language save requests explain /save surface. /save still saves Markdown. A later user turn invalidates the preview, so restage a revised pair after answering a correction. Retain stable component IDs from notes. If an old label is not namespaced, record the explicit old-to-new mapping in research.notes and show it to the human. Do not silently rename identities.
 
@@ -21,3 +21,12 @@ Requirement: {id,kind:"secret"|"resource"|"configuration",description,state}. Ne
 
 On pair reopening keep research and Surface identities via host bookkeeping. Retain all research sources, findings, alternatives, decisions, questions and component IDs. Keep historical claims and research notes exactly; append corrections and new evidence instead of removing history. Every node and relationship needs nonempty basis linking structured findings/decisions. Retained finding subjects/properties and node types cannot change; retain opaque extensions exactly. Removed selections remain rejected/deferred in research. Preserve prior unknowns unless evidence resolves them. Explain source unavailable/changed status and distinguish declared from reachable or exercised. On validation error, repair the staged content using feedback; do not discard evidence to make validation pass.
 `;
+export const surfaceInstructions = `
+STRUCTURED SURFACE HOST ADAPTER 0.3:
+For new research, use the bundled Capability/Bound contract and surface_draft with a COMPLETE bundle {research,surface,dependencies}. This tool validates and stages only; the user enters /save surface to save the preview as brief.md, research.html, surface.json, dependencies.json and manifest.json. /save still saves Markdown. A later conversational turn invalidates the preview.
+Use surface_digest with {artifact: COMPLETE_ARTIFACT} to get canonical SHA-256 for exact revision references. Never guess artifact or source digests. Source digests come from source_read/search. Use real UTC timestamps in seconds. All artifact envelopes include contract, id, revision, title, scope, extensions. Revision includes id, parent (null initially), createdAt, author and reason. The current UTC time is supplied by the host.
+Use the shapes below as schema examples ONLY: they are synthetic and are NOT evidence. Replace identities and findings with actual source evidence. Unknown details need explicit notes and empty claims. The host has no shell or filesystem staging tool. Use only surface_digest and surface_draft for structured work; do not attempt to invoke the standalone helper.
+Compute research digest first, then set surface.records to the exact research reference. Each basis is {record:research.id,revision:research.revision.id,items:[finding IDs]}. Bound dependencies include its pinned Capability and that Capability's exact research. For a successor retain research/surface identity and kind, use new revision IDs, exact parent references, unchanged prior decisions, stable component and relationship identities, and exact historical dependencies. Retain parent research in dependencies to explain changes. Do not discard contradictory evidence.
+On reopening a LEGACY n8r.surface/0.1 pair, continue that original format with the legacy content-only tool input described below; never silently migrate old files. For new work, always use n8r.surface/0.3. A saved Capability and a Bound description are distinct identities, not kind-changing successors.
+LEGACY INSTRUCTIONS (only for reopened definitions):
+` + legacySurfaceInstructions;

package/dist/surface-overview.d.ts

@@ -0,0 +1,15 @@
+/** Deterministic, offline overview. Layout hints never establish deployed boundaries. */
+import type { Surface } from './surface-bom.js';
+export declare const escapeHtml: (s: unknown) => string;
+export declare const fragmentId: (kind: string, id: string) => string;
+export declare const boundaryNames: {
+    internal: string;
+    external: string;
+    unknown: string;
+};
+export declare function nodeGroups(s: Surface): {
+    boundary: keyof typeof boundaryNames;
+    area: string;
+    nodes: any[];
+}[];
+export declare function renderOverview(s: Surface): string;

package/dist/surface-overview.js

@@ -0,0 +1,86 @@
+export const escapeHtml = (s) => String(s).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+// No percent escapes in IDs: browsers decode fragment URLs before lookup.
+// Escape underscores too so literal and encoded identifiers cannot collide.
+export const fragmentId = (kind, id) => kind + '-' + Array.from(id).map(c => /[a-zA-Z0-9-]/.test(c) ? c : '_' + c.codePointAt(0).toString(16) + '_').join('');
+export const boundaryNames = { internal: 'Inside the application', external: 'External integrations', unknown: 'Unclassified' };
+export function nodeGroups(s) {
+    const groups = new Map();
+    for (const n of [...(s.bom.components ?? []), ...(s.bom.services ?? [])]) {
+        const p = s.presentation[n['bom-ref']], boundary = p?.boundary ?? 'unknown', area = p?.area ?? 'Placement not researched';
+        const key = JSON.stringify([boundary, area]);
+        if (!groups.has(key))
+            groups.set(key, { boundary, area, nodes: [] });
+        groups.get(key).nodes.push(n);
+    }
+    return [...groups.values()].sort((a, b) => Object.keys(boundaryNames).indexOf(a.boundary) - Object.keys(boundaryNames).indexOf(b.boundary));
+}
+function wrap(text) {
+    // Wrap long tokens too; preserve the full label in the accessible title.
+    const lines = [];
+    let line = '';
+    for (const word of text.split(/\s+/)) {
+        if (line && (line + ' ' + word).length > 30) {
+            lines.push(line);
+            line = '';
+        }
+        let rest = word;
+        while (rest.length > 30) {
+            lines.push(rest.slice(0, 30));
+            rest = rest.slice(30);
+        }
+        line += (line ? ' ' : '') + rest;
+    }
+    if (line)
+        lines.push(line);
+    return lines;
+}
+export function renderOverview(s) {
+    const h = escapeHtml, groups = nodeGroups(s);
+    if (!groups.length)
+        return '<p>No components recorded yet. Continue the source investigation.</p>';
+    const positions = new Map();
+    const columns = Object.keys(boundaryNames);
+    const heights = [65, 65, 65];
+    let labels = '';
+    const counts = new Map();
+    for (const e of s.relationships) {
+        const key = JSON.stringify([e.from, e.to].sort());
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    const columnWidth = 370 + Math.max(0, ...counts.values()) * 12, canvasWidth = columnWidth * 3 + 10;
+    const lanes = new Map();
+    for (const g of groups) {
+        const col = columns.indexOf(g.boundary), x = 25 + col * columnWidth;
+        let y = heights[col];
+        const areaLines = wrap(g.area);
+        labels += `<text x="${x}" y="${y}" class="area-label">${areaLines.map((line, i) => `<tspan x="${x}" dy="${i ? 18 : 0}">${h(line)}</tspan>`).join('')}</text>`;
+        y += areaLines.length * 18 + 12;
+        for (const n of g.nodes) {
+            const lines = wrap(n.name), height = Math.max(54, lines.length * 18 + 24);
+            positions.set(n['bom-ref'], { x, y, height, n, lines });
+            y += height + 24;
+        }
+        heights[col] = y + 22;
+    }
+    const edges = s.relationships.map((e, i) => {
+        const a = positions.get(e.from), b = positions.get(e.to);
+        const ay = a.y + a.height / 2, by = b.y + b.height / 2;
+        const key = JSON.stringify([e.from, e.to].sort()), rank = lanes.get(key) ?? 0;
+        lanes.set(key, rank + 1);
+        let d;
+        if (e.from === e.to)
+            d = `M${a.x + 280} ${ay - 9} C${a.x + 330 + rank * 12} ${ay - 28} ${a.x + 330 + rank * 12} ${ay + 28} ${a.x + 280} ${ay + 9}`;
+        else if (a.x === b.x) {
+            const lane = a.x + 300 + rank * 12;
+            d = `M${a.x + 280} ${ay} C${lane} ${ay} ${lane} ${by} ${b.x + 280} ${by}`;
+        }
+        else {
+            const right = b.x > a.x, ax = a.x + (right ? 280 : 0), bx = b.x + (right ? 0 : 280), bend = (ax + bx) / 2;
+            const offset = (rank + 1) * 12;
+            d = `M${ax} ${ay} C${bend + offset} ${ay + offset} ${bend + offset} ${by + offset} ${bx} ${by}`;
+        }
+        return `<a href="#edge-${i}"><path data-edge="${h(e.id)}" d="${d}" class="${e.selection === 'selected' ? 'selected' : 'possible'}" marker-end="url(#arrow)"><title>${h(a.n.name + ' → ' + b.n.name + ': ' + e.purpose + '; support ' + e.support + '; selection ' + e.selection)}</title></path></a>`;
+    }).join('');
+    const nodes = [...positions].map(([id, p]) => `<a href="#${fragmentId('node', id)}"><g data-node="${h(id)}"><title>${h(p.n.name)}</title><rect x="${p.x}" y="${p.y}" width="280" height="${p.height}" rx="6"/><text x="${p.x + 12}" y="${p.y + 24}">${p.lines.map((line, i) => `<tspan x="${p.x + 12}" dy="${i ? 18 : 0}">${h(line)}</tspan>`).join('')}</text></g></a>`).join('');
+    return `<div class="map"><svg role="img" aria-label="Connected application overview; full relationships follow" viewBox="0 0 ${canvasWidth} ${Math.max(...heights) + 20}"><defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="7" refY="3" orient="auto"><path d="M0,0 L0,6 L8,3 z" fill="#64746d"/></marker></defs>${columns.map((c, i) => `<text x="${25 + i * columnWidth}" y="30" class="boundary-label">${h(boundaryNames[c])}</text>`).join('')}${labels}${edges}${nodes}</svg></div>`;
+}

package/dist/surface-store.d.ts

@@ -1,12 +1,9 @@
 import { type SurfaceDraft } from './surface-draft.js';
 import { type Note, type NoteContext } from './notes.js';
 type Manifest = {
-    version: 1;
-    files: {
-        'research.html': string;
-        'surface.json': string;
-    };
-    provenance: NoteContext;
+    version: 1 | 2;
+    files: Record<string, string>;
+    provenance?: NoteContext;
     note?: {
         file: string;
         digest: string;
@@ -14,13 +11,14 @@ type Manifest = {
     predecessor?: {
         directory: string;
         manifestDigest: string;
-    };
+    } | string | null;
 };
 export type SavedSurfacePair = SurfaceDraft & {
     directory: string;
     researchPath: string;
     surfacePath: string;
     manifest: Manifest;
+    briefPath?: string;
     bytes: Record<string, Buffer>;
 };
 export declare function readSurfacePair(path: string): SavedSurfacePair;

package/dist/surface-store.js

@@ -1,11 +1,12 @@
 import fs from 'node:fs';
+import { readBundle, saveBundle } from './skill-artifacts.js';
 import { basename, dirname, join, resolve, relative, sep } from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { decode, encode } from './codec.js';
 import { readResearchHtml, renderResearchHtml } from './html.js';
 import { verifyReferences } from './validate.js';
 import { canonical } from './portable.js';
-import { verifyPairSuccessor } from './surface-draft.js';
+import { verifyPairSuccessor, isBundle } from './surface-draft.js';
 import {} from './notes.js';
 import { InspectionError, readBytes } from './settings.js';
 const LIMIT = 8 * 1024 * 1024;
@@ -82,6 +83,16 @@ export function readSurfacePair(path) {
     catch {
         fail('Invalid pair manifest JSON');
     }
+    if (m?.files?.['dependencies.json']) {
+        const bundle = readBundle(directory);
+        for (const name of Object.keys(m.files))
+            bytes[name] = read(join(directory, name));
+        // Standalone skill manifests have no runner receipt. Re-read recorded sources
+        // on reopening; they remain historical evidence, not a fresh tool result.
+        if (m.provenance)
+            checkProvenance(m.provenance);
+        return { ...bundle, directory, researchPath: join(directory, 'research.html'), surfacePath: join(directory, 'surface.json'), briefPath: join(directory, 'brief.md'), manifest: m, bytes };
+    }
     manifest(m);
     for (const name of ['research.html', 'surface.json']) {
         bytes[name] = read(join(directory, name));
@@ -117,13 +128,34 @@ export class SurfaceStore {
         if (this.note && !read(this.note.path, 256 * 1024).equals(Buffer.from(this.note.text)))
             fail('Original note changed; reopen before saving');
         if (this.previous)
-            for (const name of MEMBERS)
+            for (const name of Object.keys(this.previous.bytes))
                 if (!read(join(this.previous.directory, name)).equals(this.previous.bytes[name]))
                     fail('Predecessor changed; reopen before saving');
     }
     save(draft, provenance) {
         this.unchanged();
         checkProvenance(provenance);
+        if (isBundle(draft)) {
+            if (this.previous)
+                verifyPairSuccessor(this.previous, draft);
+            fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+            checkDirectories(this.directory, this.stamps);
+            const names = fs.readdirSync(this.directory);
+            if (names.length > 10000)
+                fail('Too many Surface revisions');
+            const max = names.reduce((n, name) => Math.max(n, Number(/^surface-(\d+)$/.exec(name)?.[1] ?? 0)), 0);
+            if (!Number.isSafeInteger(max + 1))
+                fail('Surface numbering limit reached');
+            const target = join(this.directory, `surface-${String(max + 1).padStart(3, '0')}`);
+            saveBundle(draft, target, this.previous?.directory);
+            const manifestPath = join(target, 'manifest.json');
+            const receipt = JSON.parse(utf8(read(manifestPath)));
+            fs.writeFileSync(manifestPath, JSON.stringify({ ...receipt, provenance, ...(this.note ? { note: { file: basename(this.note.path), digest: this.note.digest } } : this.previous?.manifest.note ? { note: this.previous.manifest.note } : {}) }, null, 2) + '\n', { mode: 0o600 });
+            const saved = readSurfacePair(join(target, 'surface.json'));
+            this.unchanged();
+            this.previous = saved;
+            return saved;
+        }
         verifyReferences(draft.surface, [draft.research]);
         if (this.previous)
             verifyPairSuccessor(this.previous, draft);

package/dist/surface-view.d.ts

@@ -0,0 +1,3 @@
+/** Views are generated from the BOM and never become a second authority. */
+import type { Surface } from './surface-bom.js';
+export declare function renderSurface(s: Surface): Record<'brief.md' | 'investigation.md' | 'surface.html', string>;

package/dist/surface-view.js

@@ -0,0 +1,50 @@
+import { escapeHtml as html, nodeGroups, boundaryNames, renderOverview, fragmentId } from './surface-overview.js';
+const md = (s) => String(s).replace(/[\r\n]/g, ' ').replace(/[\\`*_{}\[\]<>|]/g, c => '\\' + c);
+export function renderSurface(s) {
+    const nodes = [...(s.bom.components ?? []), ...(s.bom.services ?? [])];
+    const name = (id) => nodes.find(n => n['bom-ref'] === id)?.name ?? id;
+    const focus = nodes.find(n => s.presentation[n['bom-ref']]?.focus);
+    const title = focus ? `${focus.name} — initial security overview` : 'Surface overview';
+    const intro = focus?.description ?? s.objective;
+    const groups = nodeGroups(s);
+    const replaced = new Set(s.entries.flatMap(e => e.supersedes ? [e.supersedes] : []));
+    const current = s.entries.filter(e => !replaced.has(e.id) && e.status !== 'superseded');
+    const findings = current.filter(e => e.kind === 'finding' && e.status === 'done' && e.evidence.length > 0);
+    const next = current.filter(e => ['next', 'question'].includes(e.kind) && ['open', 'active'].includes(e.status)).sort((a, b) => Number(b.status === 'active') - Number(a.status === 'active'));
+    const briefFindings = findings.slice(-5).reverse();
+    const label = (e) => `${e.selection === 'selected' ? 'Selected' : e.support === 'supported' ? 'Possible' : 'Support ' + e.support} · ${e.kind}${e.observations.length ? ' · observed ' + e.observations.map(o => o.at).join(', ') : ''}`;
+    const mechanics = `BOM revision ${s.bom.version}. Generated view; propose edits for reconciliation into a successor. The BOM remains authoritative.`;
+    const scopeNote = 'Supported paths describe options. Selection can reflect human intent or configuration; inspect its evidence. Dated observations stand separately. Missing information does not establish absence.';
+    const continuation = 'Continue with the available evidence: trace a source-level path, describe an intended setup, or inspect an identified deployment. Source-only research needs no running services. Choose another direction or stop at any time.';
+    const interchange = 'This architecture and research record is not a comprehensive dependency SBOM. Standard dependencies contain only selected dependency relationships; profile properties retain other paths and evidence. Generic consumers may omit that detail.';
+    const evidence = (ids) => ids.map(id => `<a href="#${fragmentId('ev', id)}">${html(id)}</a>`).join(', ') || 'No evidence yet';
+    const evidenceMd = (ids) => ids.map(id => `[${md(id)}](surface.html#${fragmentId('ev', id)})`).join(', ');
+    const basis = (id) => { const b = s.evidence.find(e => e.id === id)?.basis; return b === 'user' ? 'user intent' : b ?? 'unknown'; };
+    const placementMd = (id) => { const p = s.presentation[id]; return p ? ' Placement basis: ' + (p.evidence.map(e => `${md(basis(e))} — ${evidenceMd([e])}`).join('; ') || 'Not recorded') : ''; };
+    const list = (xs, empty) => xs.length ? xs.map(x => '- ' + md(x)).join('\n') : '- ' + empty;
+    const more = (count, section) => count > 0 ? `\n\n${count} additional items in [the full ${section}](surface.html#${section}).` : '';
+    const briefList = (xs, empty) => list(xs.slice(0, 7), empty) + more(xs.length - 7, 'coverage');
+    let remaining = 12;
+    const grouped = groups.flatMap(g => {
+        const shown = g.nodes.slice(0, remaining);
+        remaining -= shown.length;
+        return shown.length ? [`### ${boundaryNames[g.boundary]} · ${md(g.area)}\n\n` + shown.map(n => `- **${md(n.name)}** · ${md(n.type ?? 'service')} · ${md(n['bom-ref'])}${placementMd(n['bom-ref'])}${s.relationships.some(e => e.from === n['bom-ref'] || e.to === n['bom-ref']) ? '' : ' · Connections unknown.'}`).join('\n')] : [];
+    }).join('\n\n') + more(nodes.length - 12, 'inventory');
+    const brief = `# ${md(title)}\n\n${md(intro)}\n\nScope: ${md(s.scope)}\n\n## Major areas and integrations\n\n${grouped || 'No components recorded yet.'}\n\n${scopeNote}\n\nOpen the [connected overview and relationship details](surface.html#overview). Grouping records placement, not verified deployed trust boundaries. Inspect its evidence basis: source, user intent, configuration or dated observation.\n\n## Security observations and investigation leads\n\n${findings.length ? briefFindings.map(e => `- **${md(e.title)}** — ${md(e.text)} Why it matters: ${md(e.reason)} Evidence: ${evidenceMd(e.evidence)}.`).join('\n') : 'No evidence-backed findings recorded. Continue research; this is not an assurance conclusion.'}${more(findings.length - 5, 'findings')}\n\n${findings.length > 5 ? 'Showing the five most recently recorded current findings, not a severity ranking.\n\n' : ''}## Coverage and gaps\n\nResearched:\n\n${briefList(s.coverage, 'No coverage recorded.')}\n\nUnknown or not researched:\n\n${briefList(s.gaps, 'No gaps recorded; completeness is not established.')}\n\n## Next step\n\n${next.slice(0, 1).map(e => `- **${md(e.title)}** — ${md(e.text)} Why: ${md(e.reason)} Access: ${md(e.access)}`).join('\n') || 'No current action recorded.'}${more(next.length - 1, 'next')}\n\n${continuation}\n\n## Evidence and saved detail\n\nOpen [the map and evidence](surface.html), [investigation journal](investigation.md), or [saved Surface](surface.cdx.json).\n\n${interchange}\n\n${mechanics}\n`;
+    const journal = `# Investigation journal\n\n${mechanics}\n\n## Objective and scope\n\n${md(s.objective)}\n\n${md(s.scope)}\n\n## Available evidence and coverage\n\n${list(s.coverage, 'No coverage recorded.')}\n\n## Journey\n\n` + s.entries.map(e => `### ${md(e.title)}\n\n${md(e.kind)} · ${md(e.status)} · ${md(e.at)} · ID: ${md(e.id)}\n\n${md(e.text)}\n\nWhy: ${md(e.reason)}\n\nAccess needed: ${md(e.access)}\n\nEvidence: ${evidenceMd(e.evidence) || 'None yet'}${e.parent ? '\n\nBranch of: ' + md(e.parent) : ''}${e.supersedes ? '\n\nSupersedes: ' + md(e.supersedes) : ''}\n`).join('\n') + `\n## Open gaps\n\n${list(s.gaps, 'No gaps recorded; completeness is not established.')}\n\nChoose a next step, inspect the whole map, redirect or stop.\n`;
+    const details = s.relationships.map((e, i) => `<details id="edge-${i}"><summary>${html(name(e.from))} → ${html(name(e.to))} <small>${html(label(e))}</small></summary><p>${html(e.purpose)}</p><p>Support: ${html(e.support)}. Selection: ${html(e.selection)}. Optionality: ${html(e.optionality)}. ${html(e.group ? 'Alternative group: ' + e.group : '')}</p><p>${html(e.note)}</p><p>Integration: ${html(e.mechanism)}. Configuration locations: ${html(e.configuration.join('; ') || 'Unknown')}</p><p>Conditions: ${html(e.conditions.join('; ') || 'None recorded')}</p><p>Support evidence: ${evidence(e.evidence)}. Selection evidence: ${evidence(e.selectionEvidence)}</p>${e.observations.map(o => `<p>Observed ${html(o.at)}: ${html(o.note)} — ${evidence(o.evidence)}</p>`).join('')}</details>`).join('');
+    const ev = (s.bom.annotations ?? []).map((a) => `<article id="${fragmentId('ev', a['bom-ref'])}"><h3>${html(a['bom-ref'])}</h3><p>${html(a.text)}</p><p>${html(a.timestamp)} · ${html(a.annotator.individual?.name ?? a.annotator.organization?.name ?? 'Recorded annotator')}</p>${s.evidence.filter(e => e.id === a['bom-ref']).map(e => `<p>${html(e.basis)} — ${html(e.applicability)}</p>${e.sources.map(ref => { const source = s.bom.externalReferences[ref.index]; return `<p>Source: ${html(source.url)} · ${html(ref.locator)}<br>${html(source.comment ?? '')}<br>${html((source.hashes ?? []).map((h) => h.alg + ': ' + h.content).join('; '))}</p>`; }).join('')}`).join('')}</article>`).join('');
+    const ul = (items) => '<ul>' + items.map(x => `<li>${html(x)}</li>`).join('') + '</ul>';
+    const journey = (entries) => entries.map(e => `<article><p class="tag">${html(e.kind)} · ${html(e.status)}</p><h3>${html(e.title)}</h3><p>${html(e.text)}</p><p>Why: ${html(e.reason)}<br>Access needed: ${html(e.access)}</p><p>${html(e.at)} · ${html(e.id)}${e.parent ? ' · Branch of ' + html(e.parent) : ''}${e.supersedes ? ' · Supersedes ' + html(e.supersedes) : ''}</p><p>${evidence(e.evidence)}</p></article>`).join('');
+    const body = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src 'none'; base-uri 'none'; form-action 'none'"><title>${html(title)}</title><style>
+body{margin:0;background:#f5f3ec;color:#18362e;font:17px/1.6 system-ui,sans-serif}main{max-width:1200px;margin:auto;padding:40px 28px}header{border-bottom:2px solid #18362e;padding-bottom:25px}h1{font:42px/1.1 Georgia,serif;max-width:1000px}h2{font:28px Georgia,serif;margin-top:48px}a{color:#14634b}nav{display:flex;gap:22px;flex-wrap:wrap}small,.muted{color:#58675f}svg{width:100%;min-width:1000px}svg rect{fill:#e6ebe1;stroke:#a3b7a7}svg text{fill:#18362e;font:14px system-ui,sans-serif}.boundary-label{font-weight:bold}.area-label{font-style:italic}.selected{stroke:#14634b;stroke-width:3;fill:none}.possible{stroke:#64746d;stroke-width:2;stroke-dasharray:7 5;fill:none}svg a:focus{outline:3px solid #ba882f}svg path:hover{stroke:#ba882f;stroke-width:5}.map{overflow:auto;background:white;border:1px solid #d6dace;border-radius:8px;margin:24px 0}details,article{background:#fff;padding:18px 22px;margin:12px 0;border:1px solid #d6dace;border-radius:6px;overflow-wrap:anywhere}summary{cursor:pointer;font-weight:600}summary small{display:block;font-weight:400}:target{outline:3px solid #ba882f}li{margin:10px 0}.tag{letter-spacing:.12em;font-size:12px;text-transform:uppercase}p,li,h1,h2,h3{overflow-wrap:anywhere}
+</style></head><body><main><header><p class="tag">Initial security overview</p><h1>${html(title)}</h1><p>${html(intro)}</p><p>Scope: ${html(s.scope)}</p><nav><a href="#overview">Overview</a><a href="#findings">Security observations</a><a href="#coverage">Coverage</a><a href="#next">Next step</a><a href="#relationships">Relationships</a><a href="#evidence">Evidence</a><a href="brief.md">Brief</a></nav></header>
+<section id="overview"><h2>Connected application overview</h2><p>Each node appears once. Grouping records placement, not verified deployed trust boundaries. Inspect its evidence basis: source, user intent, configuration or dated observation. Unclassified means placement has not been established.</p><p>Solid green: selected. Dashed: selection unestablished or not selected; inspect the support state in details. Arrowheads show direction. Click a node for its record or a path for its details.</p><p>${html(scopeNote)}</p>${renderOverview(s)}</section>
+<section id="findings"><h2>Security observations and investigation leads</h2>${findings.length ? journey(findings) : '<p>No evidence-backed findings recorded. Continue research; this is not an assurance conclusion.</p>'}</section>
+<section id="coverage"><h2>Coverage and gaps</h2><h3>Researched</h3>${s.coverage.length ? ul(s.coverage) : '<p>No coverage recorded.</p>'}<h3>Unknown or not researched</h3>${s.gaps.length ? ul(s.gaps) : '<p>No gaps recorded; completeness is not established.</p>'}</section>
+<section id="next"><h2>Next step</h2><p>${html(continuation)}</p>${journey(next)}</section>
+<section id="relationships"><h2>Detailed relationships</h2>${details || '<p>No relationships recorded yet.</p>'}</section>
+<section id="inventory"><h2>Component and service records</h2>${groups.map(g => `<h3>${html(boundaryNames[g.boundary])} · ${html(g.area)}</h3>${g.nodes.map(n => `<article id="${fragmentId('node', n['bom-ref'])}"><h3>${html(n.name)}</h3><p>${html(n.description ?? 'Description not recorded.')}</p><p>${html(n.type ?? 'service')} · ${html(n['bom-ref'])}${s.relationships.some(e => e.from === n['bom-ref'] || e.to === n['bom-ref']) ? '' : ' · Connections unknown.'}</p><p>Grouping evidence: ${(s.presentation[n['bom-ref']]?.evidence ?? []).map(id => html(basis(id)) + ' — ' + evidence([id])).join('; ') || 'Not recorded'}</p></article>`).join('')}`).join('')}</section>
+<section id="journey"><h2>Investigation journey</h2><p>Choose a next step, inspect the full journey, redirect or stop.</p>${journey(s.entries)}</section><section id="evidence"><h2>Evidence and decisions</h2>${ev}</section><footer><h2>Saved detail and interoperability</h2><p>${html(interchange)}</p><p><a href="investigation.md">Journal file</a> · <a href="surface.cdx.json">Saved Surface</a></p><p>${html(mechanics)} This view proves neither completeness nor runtime use.</p></footer></main></body></html>\n`;
+    return { 'brief.md': brief, 'investigation.md': journal, 'surface.html': body };
+}