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

package/plugins/n8r-surface/skills/research/references/examples/surface.cdx.json

@@ -0,0 +1,188 @@
+{
+  "bomFormat": "CycloneDX",
+  "specVersion": "1.7",
+  "serialNumber": "urn:uuid:94141625-a8d3-4cec-984a-c46be305058d",
+  "version": 1,
+  "metadata": {
+    "timestamp": "2026-11-13T12:00:00Z"
+  },
+  "components": [
+    {
+      "bom-ref": "app",
+      "type": "application",
+      "name": "Synthetic Assistant"
+    },
+    {
+      "bom-ref": "model",
+      "type": "machine-learning-model",
+      "name": "Synthetic Model"
+    }
+  ],
+  "services": [
+    {
+      "bom-ref": "db-a",
+      "name": "Database A"
+    },
+    {
+      "bom-ref": "db-b",
+      "name": "Database B"
+    },
+    {
+      "bom-ref": "db-c",
+      "name": "Database C"
+    },
+    {
+      "bom-ref": "db-d",
+      "name": "Database D"
+    }
+  ],
+  "dependencies": [
+    {
+      "ref": "app",
+      "dependsOn": [
+        "db-b"
+      ]
+    }
+  ],
+  "compositions": [
+    {
+      "aggregate": "unknown"
+    }
+  ],
+  "annotations": [
+    {
+      "bom-ref": "evidence-support",
+      "subjects": [
+        "app",
+        "db-a",
+        "db-b",
+        "db-c",
+        "db-d"
+      ],
+      "annotator": {
+        "individual": {
+          "name": "Researcher"
+        }
+      },
+      "timestamp": "2026-11-13T12:00:00Z",
+      "text": "The synthetic source describes four supported database alternatives. This does not establish a selected deployment."
+    },
+    {
+      "bom-ref": "evidence-selection",
+      "subjects": [
+        "app",
+        "db-b"
+      ],
+      "annotator": {
+        "individual": {
+          "name": "Researcher"
+        }
+      },
+      "timestamp": "2026-11-13T12:00:00Z",
+      "text": "A synthetic safe configuration projection identifies database B; connection values were not retained."
+    },
+    {
+      "bom-ref": "decision-1",
+      "subjects": [
+        "app"
+      ],
+      "annotator": {
+        "individual": {
+          "name": "User"
+        }
+      },
+      "timestamp": "2026-11-13T12:00:00Z",
+      "text": "Investigate storage before model hosting."
+    }
+  ],
+  "externalReferences": [
+    {
+      "type": "evidence",
+      "url": "synthetic-source-pack",
+      "comment": "Synthetic source pack; version 1; inspected support and safe projection only.",
+      "hashes": [
+        {
+          "alg": "SHA-256",
+          "content": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        }
+      ]
+    }
+  ],
+  "citations": [
+    {
+      "bom-ref": "citation-1",
+      "pointers": [
+        "/annotations/0/text"
+      ],
+      "timestamp": "2026-11-13T12:00:00Z",
+      "attributedTo": "app",
+      "note": "Synthetic fixture attribution, not real product evidence."
+    }
+  ],
+  "properties": [
+    {
+      "name": "n8r:surface:profile",
+      "value": "1"
+    },
+    {
+      "name": "n8r:surface:objective",
+      "value": "Understand storage choices and the selected connection."
+    },
+    {
+      "name": "n8r:surface:scope",
+      "value": "Synthetic assistant; no live runtime access."
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-a\",\"from\":\"app\",\"to\":\"db-a\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-b\",\"from\":\"app\",\"to\":\"db-b\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"selected\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[\"evidence-selection\"],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[\"safe-projection.json: database-kind\"],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-c\",\"from\":\"app\",\"to\":\"db-c\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"storage-d\",\"from\":\"app\",\"to\":\"db-d\",\"kind\":\"dependency\",\"optionality\":\"alternative\",\"group\":\"storage\",\"support\":\"supported\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[\"evidence-support\"],\"selectionEvidence\":[],\"purpose\":\"Persist conversation state\",\"mechanism\":\"Database driver\",\"configuration\":[],\"conditions\":[],\"note\":\"Supported alternative; selection of other targets is unestablished.\"}"
+    },
+    {
+      "name": "n8r:surface:relationship",
+      "value": "{\"id\":\"inference\",\"from\":\"app\",\"to\":\"model\",\"kind\":\"integration\",\"optionality\":\"unknown\",\"group\":\"\",\"support\":\"unknown\",\"selection\":\"unknown\",\"observations\":[],\"evidence\":[],\"selectionEvidence\":[],\"purpose\":\"Generate a response\",\"mechanism\":\"Unknown\",\"configuration\":[],\"conditions\":[],\"note\":\"Model serving connection remains uninvestigated.\"}"
+    },
+    {
+      "name": "n8r:surface:entry",
+      "value": "{\"id\":\"plan-1\",\"kind\":\"next\",\"title\":\"Inspect storage selection\",\"text\":\"Establish the selected database from a safe configuration projection.\",\"status\":\"done\",\"reason\":\"Projection supplied in this synthetic example.\",\"access\":\"Safe configuration projection\",\"evidence\":[\"evidence-selection\"],\"at\":\"2026-11-13T12:00:00Z\"}"
+    },
+    {
+      "name": "n8r:surface:entry",
+      "value": "{\"id\":\"choice-1\",\"kind\":\"decision\",\"title\":\"Storage first\",\"text\":\"Investigate storage before model hosting.\",\"status\":\"active\",\"reason\":\"User priority\",\"access\":\"None\",\"evidence\":[\"decision-1\"],\"at\":\"2026-11-13T12:00:00Z\"}"
+    },
+    {
+      "name": "n8r:surface:entry",
+      "value": "{\"id\":\"question-1\",\"kind\":\"question\",\"title\":\"Which service hosts inference?\",\"text\":\"Inspect the serving configuration to identify the model endpoint role.\",\"status\":\"open\",\"reason\":\"Source does not establish this connection.\",\"access\":\"Safe inference configuration\",\"evidence\":[],\"at\":\"2026-11-13T12:00:00Z\"}"
+    },
+    {
+      "name": "n8r:surface:coverage",
+      "value": "Only synthetic support and selection sources inspected."
+    },
+    {
+      "name": "n8r:surface:gap",
+      "value": "Runtime use has not been observed."
+    },
+    {
+      "name": "n8r:surface:evidence",
+      "value": "{\"id\": \"evidence-support\", \"basis\": \"source\", \"sources\": [{\"index\": 0, \"locator\": \"support.md:1-20\"}], \"applicability\": \"Synthetic fixture only.\"}"
+    },
+    {
+      "name": "n8r:surface:evidence",
+      "value": "{\"id\": \"evidence-selection\", \"basis\": \"configuration\", \"sources\": [{\"index\": 0, \"locator\": \"safe-projection.json: database-kind\"}], \"applicability\": \"Synthetic fixture only.\"}"
+    },
+    {
+      "name": "n8r:surface:evidence",
+      "value": "{\"id\": \"decision-1\", \"basis\": \"user\", \"sources\": [], \"applicability\": \"Synthetic fixture only.\"}"
+    }
+  ]
+}

package/plugins/n8r-surface/skills/research/references/first-use-access.md

@@ -0,0 +1,97 @@
+# Start with what the user has
+
+Use this guide when a newcomer asks how to begin, provide sources or establish
+access, or mentions sources this session cannot yet read. It applies across hosts;
+no Lab, prepared workspace, repository attachment or live access is required.
+
+## First useful response
+
+Read accessible material before asking for more. A short description is enough
+for a provisional map: identify the reported components and connections, their
+basis and the consequential unknowns. A document's claim remains a document claim.
+If no source is supplied, ask for the easiest starting point: a short description,
+an architecture/deployment excerpt or a repository/document link.
+
+Then recommend one useful next source, explain the question it would answer and
+help make it accessible. For example, a deployment note's custom gateway points
+to its endpoint configuration or entrypoint; those can reveal the next component.
+Ask one focused question, not a checklist of every repository, account and host.
+Use facts already supplied rather than making the user repeat them. If the user
+cannot provide that source, offer an easier alternative and retain the partial map.
+
+Keep a lightweight source/access record in working notes or the journal:
+source identity, mentioned/available/read/blocked/deferred, actual access route,
+inspected scope and next step. Available means a tool/attachment is present; read
+means a successful scoped read occurred. A blocked source needs its reason and
+consequence, not repeated retries. These are working-note labels, not new BOM
+properties or evidence classifications. Do not turn this record into an intake form.
+
+## Help establish the next access route
+
+Discover the current host's relevant tools and supported connection/upload flows.
+Use tools already available within the authorized scope. If a connection is needed,
+explain the smallest supported user action; verify access by reading the selected
+source afterward. Consult current host help or visible UI rather than inventing
+menu names. Installing this skill supplies no repository, SSH or account access.
+
+| User's starting point | Useful next action | What to keep explicit |
+| --- | --- | --- |
+| Description or document | Read the supplied text/attachment; follow relevant links or ask for one missing section. | Reported architecture, document date/version and unverified deployment claims. |
+| GitHub or another remote repository | Read selected files through an authorized connector/API or permitted public web access. For private sources, guide the supported host sign-in/connection flow. | A link or sign-in is not a successful repository read; check repository, revision and permitted scope. |
+| Laptop folder | If approved local tools can read it, use the selected folder. Otherwise help the user upload selected files or use a supported connected-computer route. | A web Project's uploaded files are snapshots, not a live folder mount or automatic synchronization. A local path alone is inaccessible remotely. |
+| VPS/SSH clue | Establish target, inspection scope and an available authorized execution route. Host/user/port and an existing connection alias may identify it; ask only for missing details needed next. | An IP or SSH command supplies no credentials, network reachability or shell tool. Existing laptop access is not inherited by a cloud chat. |
+| Existing admin UI/API | Use an approved scoped read interface and the user's supported sign-in handoff. | Public views may reveal only a small part of the setup; diagnostic operations can have side effects. |
+
+For laptop uploads, suggest the smallest useful selection: a README section,
+source tree excerpt, deployment manifest with sensitive values removed, or the
+entrypoint named by existing evidence. Explain why each requested file matters.
+Offer an archive only if the host supports inspecting it and the user prefers it;
+do not require the whole repository. Preserve relative paths and ask for revision
+or capture identity when available. Uploads and connected folders are alternatives,
+not mandatory steps or permission to publish code.
+
+For a VPS, first determine where commands could run: an authorized tool/service,
+an explicitly connected computer with permitted SSH, or the user's own terminal.
+Only claim SSH capability after checking the actual tools and approved connection.
+Keep authentication in the host's supported flow or existing credential store;
+never request passwords, tokens or private keys in chat or uploads. A key offered
+in chat should be declined with a concrete alternative. Do not disable host-key
+checks, expose SSH publicly or add credentials/agents to make onboarding work.
+If the host cannot provide a supported secure access route, say so and continue
+with available documents/source or the human-assisted route below.
+
+## Human-assisted evidence
+
+When direct access is unavailable and the user wants to continue, offer a small
+read-only collection step they can perform in their own environment. Establish
+the target/runtime first. Explain what it reads, the expected safe fields and
+what finding they could support. Filter before output; avoid raw environment,
+connection strings, logs and complete inspection/config dumps. Ask them to review
+for sensitive content before sharing. Do not hide a state change in a diagnostic
+command. An access denial remains a blocker, not a reason to bypass permissions.
+
+Treat returned material as user-supplied evidence, with reported target, time,
+command/scope and redactions where available. Do not claim the agent accessed the
+host or independently observed the command. Missing metadata limits the claim;
+keep useful partial findings rather than inventing timestamps or source hashes.
+
+## Saving and returning
+
+Research readiness is separate from local workspace creation. Before promising a
+save, check the installed helper, supported Node runtime, writable destination and
+host file-delivery tools. For explicit local workspace setup, use
+[workspace operations](workspace.md); do not run its local-folder procedure merely
+because a user starts research in a web Project.
+
+If helper execution and file delivery are available in the cloud, use
+[Surface persistence](cyclonedx.md), read back the outputs and provide the actual
+supported download/attachment links. Distinguish cloud files/downloads from a
+local vault and from a Project source. Do not promise persistence across chats or
+claim an attachment action that has not occurred. Deliver retained evidence with
+the Surface when its relative references need it, or disclose the missing sources.
+
+If execution or delivery is unavailable, provide a useful copyable map and notes;
+name the specific blocked save step. Do not call prose a validated saved Surface.
+Explain what the user should retain and supply on return. Reopening starts from
+supplied artifacts and rechecks access; it does not assume local keys, connections
+or research were carried into a fresh session.

package/plugins/n8r-surface/skills/research/references/first-use-overview.md

@@ -0,0 +1,101 @@
+# A useful first security overview
+
+For broad initial source research, help the reader understand the application
+before explaining the saved format. Preserve a narrow question when one is given.
+This is a bounded first pass, not an exhaustive audit or vulnerability verdict.
+
+## Research and record
+
+- Explain what the application does in one plain sentence. Put this in the focus
+  component's standard `description`; name that component as the presentation
+  focus using the [optional node hints](cyclonedx.md#overview-presentation-hints).
+- Group major internal functions and external integrations only where evidence
+  establishes their placement relative to the application. A browser is not the
+  backend; a supported database option is not an installed store. Preserve shared
+  identities and paths across groups. Leave unresolved placement unclassified.
+- Record a few consequential observations as `finding` journal entries with
+  `status: done`, evidence references, and a `reason` explaining why each matters.
+  Keep the finding and its limitation together. A source-backed execution path is
+  an investigation lead, not a demonstrated vulnerability or runtime guarantee.
+  Do not promote an unsupported inference just to fill the opening.
+- Make coverage legible across **identity**, **authorization**, **data handling**,
+  **storage**, **secrets**, **exposure** and **observability**. Use named `coverage`
+  and `gap` strings, such as “Identity: supported sign-in options inspected” or
+  “Observability: runtime trace coverage not researched.” These labels describe
+  inspected work, not control effectiveness. Mark unresearched areas explicitly;
+  do not expand a first pass into seven exhaustive investigations.
+- For integrations within scope, research supported options separately from
+  intended selections, safe configuration evidence and dated runtime observations.
+  “Identity provider unknown” alone does not describe supported authentication.
+  If support was not researched, say so and identify the next useful source read.
+- Keep model-request control points distinct from actual tool execution. Preserve
+  browser-originated traffic, backend extensions and scheduled execution contexts
+  when evidenced; explain their consequences without presuming every app has them.
+
+The generated brief uses descriptions, groups, findings, coverage/gaps and open
+next steps. The generated HTML puts a connected overview before full relationships,
+source evidence and investigation history. Do not hand-edit these views instead of
+recording the relevant evidence in the BOM.
+
+## Scope once, exceptions where needed
+
+State common source/deployment limits in `scope`. Keep per-relationship conditions,
+conflicts, bypasses, selection evidence and observations intact. Use `note` for
+what is distinctive about a path instead of repeating generic deployment caveats.
+The concise brief links to full relationship details; brevity must not erase a
+consequential exception from its associated finding.
+
+## Invite the next decision
+
+Match the next step to the established investigation context:
+
+- **Source checkout only:** recommend one concrete source-level trace, naming the
+  entry point, authorization boundary and question it can answer. Keep deployment
+  settings unverified. Research can continue without a daemon, deployed instance
+  or chosen provider. Ask about intended setup only if the user wants planning.
+- **Intended setup:** record choices as dated user-basis evidence, then explain
+  what configuration evidence would establish them later.
+- **Identified deployment:** inspect only the permitted target and relevant safe
+  fields. Keep configuration and dated runtime observations separate.
+- **Context unclear:** continue useful source research; before requesting runtime
+  access, establish whether the user wants source analysis, planning or inspection
+  of an existing deployment. A checked-out Compose file identifies a declaration,
+  not a running target. An available Docker daemon is not a target identity.
+
+## Keep the successor current and the brief short
+
+Before each save, reconcile the current scope, findings, coverage, gaps and actions:
+
+1. Record new evidence with its date and applicability. Preserve old observations
+   and accepted decisions in the journal and predecessor; do not rewrite their text.
+2. Mark obsolete entries `superseded` and link a replacement with `supersedes`.
+   Mark completed actions `done`; mark out-of-scope work `deferred` with a reason.
+   For example, reachable runtime evidence supersedes an unavailable-daemon blocker
+   and completes the retry action; it does not establish a deployment's presence.
+3. Replace obsolete current scope/gap strings in the successor. Preserve their
+   historical content in dated journal entries/evidence. Do not append contradictory
+   current statements and leave the reader to determine which applies.
+4. Keep one recommended action `active`, with a clear result and access requirement.
+   Other genuinely useful choices can remain open or deferred in the journal.
+5. Read the generated brief as a newcomer. Aim for roughly 400–700 words: a short
+   current scope, major areas, a few current implications, concise coverage/gaps
+   and one next action. Consolidate overlapping findings using supersession while
+   preserving each consequential exception and its evidence. A word target never
+   justifies dropping a limitation or inventing a summary.
+
+The renderer shows at most twelve nodes, five current findings (most recently
+recorded, not severity-ranked), seven coverage items, seven gaps and one action
+(active first, otherwise recorded order). It explicitly links additional items to
+full HTML detail. Complete finding text, reasons and evidence stay together;
+long individual entries are not silently truncated. Prioritise and consolidate
+research content before saving; list limits alone do not guarantee a short brief.
+The journal and full map retain the complete record, including superseded entries.
+This skill does not configure or deploy the system.
+
+End the chat with a short statement of what the research clarified, links to the
+brief and map (journal/detail links can follow), and the next useful question.
+Keep format mechanics underneath. Explain the architecture/research BOM's bounded
+machine-readable value when relevant: it is not a comprehensive dependency SBOM;
+standard dependencies cover only the selected dependency subset. Other consumers
+may ignore the profile's paths and evidence. Conventional SBOM linkage is future
+work, not a claim made by this increment.

package/plugins/n8r-surface/skills/research/references/instance-first.md

@@ -0,0 +1,125 @@
+# Investigate an identified running composition
+
+Use this path when the user starts with an instance, service URL or deployed
+composition, or continues source research with permitted instance evidence.
+A source checkout can describe one component without describing the whole system.
+Keep source-only work on its existing path when no instance investigation is asked
+for. This guide adds no access adapter, credential store or runtime dependency.
+
+For a newcomer or an inaccessible source, use [first-use access](first-use-access.md)
+to help establish one useful source at a time. A short reported system description
+is enough to begin; a complete access setup is not an entry requirement.
+
+## Use the host harness
+
+Codex/ChatGPT supplies the tools and access; the skill supplies the investigation
+method. Discover the relevant tools actually available in this session. Prefer a
+scoped connector or documented read API, then permitted browser or shell access.
+Do not assume a tool name, a terminal, SSH, a local clone or a connected account.
+A URL identifies a source; a successful scoped read establishes access.
+
+Start with the supplied target and question. State the selected environment and
+read-only coverage, carrying forward existing authorization. Ask only for missing
+information needed to identify the target or permitted access. Do not make users
+choose evidence categories or reproduce information an available source supplies.
+
+| Source | Useful host operation | Identity and limit to retain |
+| --- | --- | --- |
+| Remote repository | Read selected files at a pinned revision through the available connector/API. | Repository, revision, file and inspected ranges; returned text may not be original file bytes. |
+| Local checkout | Read relevant files and working-copy identity. | Commit plus differences and hashes of inspected bytes; not deployed build identity. |
+| Document or URL | Read the selected page/section using its available connector or browser. | Document revision/product version, capture time and section; newer docs may not apply to the target. |
+| Instance configuration | Read safe fields from the selected instance/admin view. | Target identity, setting scope and time; stored settings may not be loaded. |
+| Runtime metadata | Filter to the target and project allowlisted fields before output. | Instance/container/process identity, image/build identity, state and capture time. |
+| Existing observations | Read a permitted redacted event/trace or supplied observation. | Request correlation, participating identities, effective setup and coverage; missing events do not prove absence. |
+
+If a source is unavailable, retain the partial graph and identify the consequence:
+for example, storage is configured but current use is unverified. A permission
+refusal is not a prompt to bypass that route. Ask for an authorized source or
+human-supplied redacted evidence when needed. Do not sign in for the user, extract
+sessions, install tools or start services to fill the gap. Follow the discovery
+guide's [live inspection rules](discovery-map.md#inspect-live-connections-with-the-human).
+
+## Follow the composition
+
+Begin with the selected instance's identity and entry point, then follow evidence
+of relevant connections. An endpoint binding can lead to a separate gateway,
+inference provider, identity service, storage or telemetry destination. Determine
+its role before deciding which source file, document or live view to read next.
+Do not replace a custom endpoint with a familiar vendor because its protocol is
+compatible. Do not add roadmap components or enumerate unrelated host resources.
+
+Use repositories and operational documents to explain those discovered components.
+An old deployment recipe is a navigation clue until current evidence supports it.
+Match product documentation to the installed version; mismatches remain visible.
+Record supported alternatives separately from the selected instance paths.
+
+For each consequential claim, keep the evidence level precise:
+
+- Source describes support or a code path; it does not establish selection.
+- A safe binding establishes configured selection, with its setting scope.
+- Process/container state establishes presence at a time, not connection use.
+- A response establishes reachability for that operation and vantage point.
+- A correlated request/trace can establish the exercised portion of a path,
+  within its identity, time and coverage limits.
+
+A mounted file hash identifies inspected bytes, not necessarily the bytes loaded
+by a running process. A model name in configuration is not catalog availability
+or inference. A health response does not exercise storage, authentication or
+model requests. Similarly named fields in public config and process environment
+may have different meanings: inspect their version-specific implementation before
+calling them equivalent or conflicting. Keep separate login, application actor,
+provider credential and upstream identity boundaries when evidence supports them.
+
+Read-only means the operation's behavior, not its HTTP verb. A diagnostic GET
+may start a worker, refresh credentials or run a connection test. Use known passive
+operations or existing evidence; leave uncertain operations uncalled. Research
+does not send prompts or invoke tools to make an edge observable. Those are
+separately authorized testing tasks.
+
+## Retain evidence and continue
+
+Keep the journal current while working when saving is authorized. State what was
+read, what it established and the next useful question; the user can redirect or
+stop at a useful partial result. Save through the existing [Surface helper](cyclonedx.md).
+No special whole-Surface observed state is needed: use per-relationship evidence
+and dated observations, with unknown composition and explicit coverage/gaps.
+
+Keep source identity distinct from captured evidence identity. If a connector
+returns rendered or normalized text, hash a retained safe projection only as that
+projection, not as the original remote file. Never fabricate unavailable hashes,
+versions or observation times. Preserve actual source capture times separately
+from the time the BOM was saved. Do not add transport newlines before hashing
+source bytes. See [evidence identity](cyclonedx.md#evidence-identity-and-readback).
+
+On revisit, read the supplied predecessor, re-establish permitted access and
+compare equivalent observations for the same target. Explain each material result
+in ordinary language:
+
+- **Target change:** comparable evidence establishes a changed setting/build or
+  relationship. Say which prior conclusions or tests may need revisiting.
+- **Newly learned fact:** previously unread evidence adds detail; discovery time
+  alone does not establish when the target changed.
+- **Unchanged checked fact:** the same scoped fact was checked again, at a new
+  time; do not generalize to unchecked parts of the system.
+- **Lost coverage:** access or evidence is missing now; retain prior dated facts
+  without presenting them as freshly verified or treating the component as removed.
+- **Conflict:** evidence disagrees or identities are inconsistent; preserve both
+  and name the evidence needed to resolve it. A mutable image tag is not a digest.
+
+These are explanations, not new schema enums. Retain stable component identities,
+previous bytes, decisions and observations. Update current scope/gaps and next
+steps; keep old findings in history. A telemetry setting first read today may
+predate the baseline, and a file timestamp alone does not prove historical use.
+
+When consolidating earlier findings into a current journal summary, carry the
+original evidence IDs for every retained configuration/source claim. A new
+runtime-state check supports only its inspected facts; it cannot substitute for
+those sources. Open the summary's evidence links during readback and check each
+claim, even when the underlying graph still has correct provenance. Correct an
+incomplete saved summary in a successor, preserving the earlier revision.
+
+Finish with the useful composition, consequential uncertainties and one practical
+next investigation with its access requirement. Independently read back the saved
+BOM and generated brief/map/journal. Check that the key claims remain distinguishable
+without this chat and that referenced retained evidence is locatable. State any
+host persistence or navigation limitation rather than claiming a missing save.

package/plugins/n8r-surface/skills/research/references/model-meanings.md

@@ -0,0 +1,55 @@
+# AI Surface Model meanings
+
+The AI Surface Model describes connected components, configuration and relationships
+at the detail available or useful. A language model is a component described by
+it. There is one AI Surface Model; Lab and Experiment are descriptions within it.
+A Lab contains Experiments. Each Experiment owns its desired setup and selected
+Surface revision and requests resource configuration directly from its Lab.
+The Lab owns resource configuration and local bindings. Lab / Lab Assistant
+share one entity. The ownership chain is Lab → Experiment → Setup.
+Bench is retired; preserve historical references as historical evidence, never
+as current ownership or authority. Do not invent a hierarchy when it is outside
+the supplied investigation.
+
+Partial knowledge is useful. Preserve these distinct meanings:
+
+| Meaning | Use |
+| --- | --- |
+| Known | Supported by identified evidence with a stated scope. |
+| Unknown | The question is relevant but available evidence does not answer it. |
+| Omitted | Deliberately left out of this description. |
+| Redacted | Known detail withheld, such as sensitive values. |
+| Absent | Evidence establishes absence within a specific scope. |
+| Out of scope | Not part of the selected investigation. |
+
+A missing field or uninspected directory does not establish absence. Evidence
+that a product supports OIDC does not establish that this user enabled it.
+Two HTTP routes can belong to the same service. Keep shared components, parallel
+connections and cycles; depth is relative to a starting point, not a fixed limit.
+Assign simple stable local labels such as `component:identity` when findings will
+be saved or continued; add detail without silently replacing the entity.
+
+Keep definitions separate from deployments, observations and Experiment Runs.
+A declared connection, a reachable endpoint and an exercised interaction are
+three different evidence claims. Source reading alone establishes none of the
+runtime claims. Later findings must not silently rewrite what an earlier result
+referred to. Record source, time, applicable revision and limits.
+
+Interoperability is a bounded, versioned mapping with explicit losses. Matching
+names, parsing JSON or reading a schema does not establish compatibility or
+successful recreation. Distinguish a product possibility from a selected setup.
+
+Named output profiles select content within this one model. Size, purpose and
+deployment knowledge are independent. A profile version identifies output rules;
+Surface definition and setup/binding revisions identify the described state.
+Preserve those revisions and prior Run attribution when adding detail or bindings.
+The [skeleton procedure](skeleton-surface.md) defines the provisional brief and
+explicit reconciliation lifecycle. Detailed and recreation profiles remain future
+directions, not implemented contracts.
+
+This bundled reference records the draft meanings for skill 0.1.8. The repository's
+[draft concepts](https://github.com/injectionator/n8r-surface/blob/main/spec/README.md)
+are a moving source link; use the installed package version and digest to identify
+the instructions actually used. Fields and serialization remain provisional. Maintainers must update this
+reference with semantic changes; consumers do not need the source checkout to
+read it.