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

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

@@ -0,0 +1,300 @@
+{
+  "id": "urn:demo:relationship-research",
+  "title": "Synthetic relationship evidence",
+  "scope": "Synthetic role/product identities only; runtime unverified.",
+  "revision": {
+    "id": "r1",
+    "parent": null,
+    "createdAt": "2026-11-08T00:00:00Z",
+    "author": "Synthetic author",
+    "reason": "Initial shared-relationship fixture"
+  },
+  "extensions": {},
+  "contract": "n8r.research/0.1",
+  "sources": [
+    {
+      "id": "urn:source:summary",
+      "location": "sources.md",
+      "version": "synthetic-relationships-1",
+      "digest": "sha256:cb9498a53d65fb16c16b7ac297b84b2d14a825297012bec9ac07df083e3c5647",
+      "inspectedAt": "2026-11-08T00:00:00Z",
+      "coverage": [
+        {
+          "path": "sources.md",
+          "status": "inspected",
+          "note": "Sanitized synthetic source pack, not raw configuration."
+        }
+      ]
+    },
+    {
+      "id": "urn:source:config",
+      "location": "config/assistant.env.example",
+      "version": "synthetic-1",
+      "digest": "sha256:d575d918e3e60fa1bf4490f7d6ceddafdcf0dba56b41b0e566a3adc8d88fe256",
+      "inspectedAt": "2026-11-08T00:00:00Z",
+      "coverage": [
+        {
+          "path": "config/assistant.env.example",
+          "status": "inspected",
+          "note": "Synthetic setting-name documentation only."
+        }
+      ]
+    }
+  ],
+  "findings": [
+    {
+      "id": "urn:f:database",
+      "subject": "urn:node:app",
+      "property": "supports",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:node:mongodb",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Product guide"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:oidc",
+      "subject": "urn:node:app",
+      "property": "supports",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:node:oidc",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Product guide"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:saml",
+      "subject": "urn:node:app",
+      "property": "supports",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:node:saml",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Product guide"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-bound",
+      "subject": "urn:instance:demo",
+      "property": "urn:cap:database",
+      "state": "known",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:target:atlas",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Sanitized instance configuration summary, revision 1"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:identity",
+      "subject": "urn:instance:demo",
+      "property": "urn:cap:oidc",
+      "state": "conflicting",
+      "note": "Synthetic source assertion; not runtime evidence.",
+      "claims": [
+        {
+          "value": "urn:target:oidc",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Sanitized instance configuration summary, revision 1"
+            }
+          ]
+        },
+        {
+          "value": "urn:target:saml",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Sanitized instance configuration summary, revision 1"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-purpose",
+      "subject": "urn:cap:database",
+      "property": "purpose",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "Persist conversation history and user profiles.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Database integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-integration",
+      "subject": "urn:cap:database",
+      "property": "integration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "MongoDB client driver using the MongoDB wire protocol.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Database integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:database-configuration",
+      "subject": "urn:cap:database",
+      "property": "configuration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": [
+            {
+              "owner": "urn:node:app",
+              "mechanism": "environment-variable",
+              "key": "CHAT_STORE_URI",
+              "location": "config/assistant.env.example"
+            }
+          ],
+          "evidence": [
+            {
+              "source": "urn:source:config",
+              "locator": "CHAT_STORE_URI comment"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:oidc-purpose",
+      "subject": "urn:cap:oidc",
+      "property": "purpose",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "Authenticate users through an identity service.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:oidc-integration",
+      "subject": "urn:cap:oidc",
+      "property": "integration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "OpenID Connect",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:saml-purpose",
+      "subject": "urn:cap:saml",
+      "property": "purpose",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "Authenticate users through an identity service.",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    },
+    {
+      "id": "urn:f:saml-integration",
+      "subject": "urn:cap:saml",
+      "property": "integration",
+      "state": "known",
+      "note": "Synthetic source statement; no actual settings.",
+      "claims": [
+        {
+          "value": "SAML 2.0",
+          "evidence": [
+            {
+              "source": "urn:source:summary",
+              "locator": "Authentication integration"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "alternatives": [
+    {
+      "id": "urn:option:oidc",
+      "title": "Prefer OIDC",
+      "findings": [
+        "urn:f:identity"
+      ],
+      "requirements": []
+    }
+  ],
+  "decisions": [
+    {
+      "id": "urn:decision:oidc",
+      "alternative": "urn:option:oidc",
+      "choice": "selected",
+      "reason": "Synthetic human preference; conflict unresolved.",
+      "by": "Synthetic reviewer",
+      "at": "2026-11-08T00:00:00Z"
+    }
+  ],
+  "questions": [],
+  "notes": []
+}

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.