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

package/plugins/n8r-surface/skills/research/references/discovery-map.md

@@ -0,0 +1,160 @@
+# AI Surface discovery guide
+
+The goal is an evidence-backed graph of AI-relevant components and connections,
+not a complete application inventory. Follow how information enters, reaches
+models/tools/data, and produces effects. Include supporting storage, identity,
+infrastructure and observability when they explain those paths or boundaries.
+Settings are supporting evidence: inspect them when they change a node, edge,
+route, authority, data flow or a material uncertainty about the graph.
+
+This is provisional research guidance within the AI Surface Model, not another
+model, a universal schema or a mandatory list of components.
+
+## Start with the available evidence
+
+Establish the task: **discover** a graph, **continue** saved research, or
+**reconcile** an existing Surface with current evidence. Honor a bounded question.
+For broad requests, identify the application boundary and shallow AI-related
+connections before detailed subsystem research. Degree is relative to the start
+node; follow a useful route beyond one hop without imposing a depth ceiling.
+
+| Available material | Use and limit |
+| --- | --- |
+| Unknown folder | Inspect structure, entry points and manifests to locate evidence of AI relevance. Unread files and dependency names are clues, not findings. |
+| Code without docs | Follow calls, configuration readers and dependencies relevant to graph edges; runtime state remains separate. |
+| Docs without code | Use navigation, headings and examples to map documented capabilities; implementation and effective setup remain unverified. |
+| Local/remote documentation | Follow relevant links into source or setup material. Record the URL, applicable version, section and inspection time; current vendor docs may describe another release. |
+| Product guide or earlier research | Reuse navigation, evidence and gaps after checking identity, scope and revision. Distinguish inherited from rechecked findings. |
+| Surface definition(s) | Establish each composition's identity and claims. Compare applicable claims; omitted detail is not absence. |
+| Supplied configuration | Establish environment, revision, defaults and overrides when relevant. An example is not a selected setup; a file is not proof it was loaded. |
+| Human input | Record scoped intent, corrections and decisions separately from source or runtime evidence. |
+| Live UI/API observations | Identify the target environment and dated observed settings; reading a setting does not exercise its connection. |
+
+Use what is available. Record unavailable, unreadable, excluded or truncated
+material without inventing its contents. A locator does not grant access.
+Enough evidence for the user's question, with visible gaps, is a useful stopping
+point; obtaining every source type is not a completion requirement.
+
+## Reuse product knowledge
+
+Look for related material in supplied notes, selected local libraries or a
+connected collection that the host can actually search. Do not scan unrelated
+folders/accounts or presume an n8r-labs connection. A simple index of versioned
+documents and links is sufficient; this skill creates no registry service.
+
+Distinguish a product guide (capabilities/navigation), a particular selected
+Surface (composition), and research (evidence/decisions/gaps). Match repository
+identity, forks, releases and scope rather than a display name alone. An older
+guide can direct reads without establishing current behavior. Several Surfaces
+may select different providers; never union their selections into one deployment.
+Retain provenance and contradictions. A library's origin is not automatic
+authority, and a note repeating a source is not independent corroboration.
+
+When saving, retain reusable product findings separately from private deployment
+choices. Making private research public requires its own authorization.
+
+## Follow graph clues
+
+Documentation indexes and navigation often provide the first paths. Follow
+relevant headings, setup examples and links into code. When links are absent,
+search distinctive configuration keys, symbols and route names. If documentation
+is absent, use entry points and manifests. Read scripts as evidence; do not run
+them merely to discover architecture.
+
+| Area | Clue leads to next useful read |
+| --- | --- |
+| Inputs and effects | Web/chat UI, API, CLI, bot, upload, webhook or scheduled task → handler → AI processing and returned result/action. A generic UI alone is not AI evidence. |
+| Models and inference | Inference call or endpoint → configuration source → proxy/router/aggregator → service → model identity. Cover embeddings, speech, vision and other AI operations, not only chat. A provider SDK or compatible API does not identify the service behind a custom URL. |
+| Agents and orchestration | Prompt/workflow/agent definition → context assembly, model selection, delegation, tools and stopping conditions relevant to connections. |
+| Tools and actions | MCP or other integration → host/client/server role, exposed/consumed capability, transport, executor, target and authority. SDK installation alone does not establish a configured connection. |
+| Knowledge and retrieval | Upload/source connector → parsing/chunking → embeddings/index/store → retrieval/reranking → model context. RAG need not be a separate server; identify who provides and consumes each capability. |
+| State and storage | Conversation, memory or document persistence call → storage adapter → configured store. Include a database such as MongoDB for its AI-related data role; avoid unrelated application tables. |
+| Identity and controls | Login/provider gate, permission check or approval → identity/authority boundary governing relevant access and actions. OIDC enablement and issuer can explain an edge; credential values do not belong in the graph. |
+| Observability and evaluation | Tracing/evaluation hook → instrumentation → destination and covered AI operations. A logging dependency alone does not establish a live telemetry connection. |
+| Software identity and delivery | Manifest, lockfile, entry point, container or deployment declaration → relevant component/version/runtime and configuration binding. These support graph identity; do not enumerate every package or setting. |
+
+For example, `package.json` suggests JavaScript package/tooling context. Inspect
+scripts, engines, workspaces and relevant imports before inferring a runtime;
+it may describe browser tooling alongside a Python service. Keep application,
+package, source revision, deployed build and model versions distinct.
+
+A CRM can have no identified AI capability in the inspected scope, or participate
+as an evidenced tool/data source in a larger AI Surface. Neither a database nor a
+generic API alone establishes AI membership. Report scoped negative findings and
+insufficient evidence distinctly; do not force an AI graph into every repository.
+
+## Reconcile a Surface with current sources
+
+Preserve the supplied bytes and establish format/version, vocabulary, component
+identity, scope and intended versus observed meaning. Only claim validation for
+a supported format actually checked. Unrecognized meanings remain unsupported;
+successful JSON parsing does not make arbitrary Surface JSON understood.
+
+Use the graph as the comparison spine. For each relevant node/edge or supporting
+setting, report: prior claim and basis; current evidence and applicability;
+agreement, difference, additional discovery, conflict, unknown or unsupported
+meaning; and the next useful check. These are prose comparison outcomes, not new
+contract states. Missing search hits or omitted attributes do not establish that
+a node/edge was removed. Preserve stable identities where evidence supports them.
+
+Compare like with like: documented support, implemented support, human intent,
+declared configuration, observed effective configuration, reachability and
+exercised behavior answer different questions. Example: a baseline selects OIDC;
+current code supports OIDC; a staging file declares it disabled. That can establish
+a declared difference for the same staging target, but not its running state or
+that the historical baseline was wrong. Locate applicable override/effective
+evidence if that distinction matters. Do not dump unrelated settings into the diff.
+
+Save the comparison as research. A proposed successor must preserve the original,
+its evidence and unresolved claims. This skill does not emit validated experimental
+Surface JSON/HTML or modify deployments.
+
+## Inspect live connections with the human
+
+Use live inspection when the user's task calls for it and the host provides
+authorized access. Establish the selected application, environment/tenant and
+question from available context; ask only for missing information needed to
+identify the target. Prefer a suitable connected read tool or documented admin
+API; use browser/computer tools where they provide the required access. Respect
+the tools' scopes and restrictions. A blocked route must not be bypassed.
+
+Let the user complete password, MFA or private sign-in flows directly using the
+host's supported handoff. Do not ask for credentials in chat, extract sessions,
+reveal masked secrets, export credentials or copy passwords/keys/tokens into
+notes. Prefer narrow nonsecret fields or settings views to raw configuration
+dumps. If incidental secrets appear, do not repeat or retain them. Avoid saving
+screenshots or payloads containing secrets; record a sanitized observation and
+its location, with the resulting evidence limitation.
+
+Ask graph questions: is this connection enabled; which service/issuer is the
+target; what role, protocol and authority does it use? A masked configured-secret
+indicator may establish presence, never credential validity. Keep target identity
+as specific as needed in private notes; redact sensitive infrastructure details
+from portable/shared output and keep the stable component ID.
+
+Remain read-only: do not toggle/save settings, reveal secrets, rotate keys,
+create clients or invoke a connection test as part of inspection. Those are
+separate user tasks. Do not invent API endpoints or assume any product exposes
+all its configuration through an admin UI.
+
+Record the actual page/section or API operation, environment, time, available
+version and nonsecret result. Distinguish an editable stored setting from a
+runtime-effective setting. Re-read the relevant view/field when verifying the
+observation; inaccessible fields remain unknown. Keep source declarations and
+earlier observations even when they disagree. Live settings are dated evidence,
+not proof of a successful login, inference call, database query or complete setup.
+
+## Present and retain the graph
+
+Lead with a compact graph or edge table: stable components, directed/purposed
+connections, evidence basis and unresolved endpoints. Put supported alternatives
+in a separate view/list from selected composition. Label a connection as declared
+only when an applicable declaration supports it; keep possibilities, inferences
+and unresolved clues explicit. Do not turn a UI settings read into an exercised edge. Include shared
+components and useful deeper routes without inventing separate services for every
+route, configuration key or package. Keep graph-relevant settings beside the edge
+they explain, followed by evidence, coverage and the next consequential question.
+
+Use the [working-note convention](working-notes.md) for durable progress. Sources
+and observation summaries may be incomplete; a successful save does not establish
+runtime behavior, universal compatibility or security certification.

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.

package/plugins/n8r-surface/skills/research/references/skeleton-surface.md

@@ -0,0 +1,105 @@
+# Skeleton Surface v0.1
+
+This is a provisional output profile within the AI Surface Model. Produce a
+compact Markdown Surface working draft, not validated JSON/HTML or a deployment
+recipe. The profile version describes these rules; the skill version identifies
+the instructions used. Neither is the revision of the particular Surface/setup.
+
+## Select and bound the brief
+
+Use this profile when asked for a skeleton or brief Surface. Broad discovery
+starts shallow; a narrow question takes precedence over a general inventory.
+Security is the focus of this profile, while the model supports other purposes.
+The useful question is: where could a security integration inspect or intervene
+in LLM and actual tool calls, with what powers, coverage and gaps?
+
+Retain a node or distinction when removing it hides a key capability, a material
+security boundary, or a place an Experiment could change or observe behavior.
+Keep required supporting roles such as application persistence when they explain
+the setup. Features can be capability nodes; do not turn every setting into a node.
+Use a role such as MCP server or vector store when no instance is selected. Source
+evidence may identify supported products/transports without identifying a binding.
+An empty template field does not establish that every deployment lacks a binding.
+
+Preserve stable node and relationship identities from supplied descriptions.
+Different serialization or vocabulary requires an explicit mapping, not silent
+renaming. Keep shared nodes, parallel routes and cycles. A historical claim not
+re-established at the selected revision must stay qualified or move to a clearly
+linked historical/gap record; it cannot become a current supported capability.
+
+## Keep the graph small without losing meaning
+
+Lead with a short identity/scope line and a graph or edge table. Retain source
+revision, Surface revision and profile name/version. Show key nodes, directed
+relationships, purposes and relevant execution/authority boundaries. Label
+supported possibilities separately from selected composition and observed setup.
+No source-only graph establishes reachability or exercise.
+
+Use concise claim references to linked research or source sections. Identify the
+supporting revision and locator where available. Summarize coverage and unresolved
+questions once where shared; retain exceptions beside the affected edge. Avoid
+repeating boilerplate unknown bindings for every node, but never make an omitted
+value imply absence. No arbitrary node count, depth ceiling or file-size minimum
+applies. A smaller output is not permission to discard a condition or bypass.
+
+| In the brief | In linked records |
+| --- | --- |
+| Nodes, directed edges, roles, material conditions and uncertainty | Detailed source excerpts, inspected ranges and investigation narrative |
+| Claim basis and usable evidence references | Full provenance, conflicts and supporting findings |
+| Interception location, visibility, powers and coverage gaps | Hook signatures, configuration details and vendor compatibility research |
+| Binding status and reference when relevant | Protected resource bindings, nonsecret configuration and secret requirements/references |
+| Observation summary with applicability, when supplied | Dated runtime observations, traces, tests and Experiment Run results |
+
+Use existing evidence records when they suffice. Do not create a large companion
+record just to satisfy a template; direct versioned source references can suffice.
+Keep links portable or state which accompanying files are needed. Never invent
+records or imply their contents were read. Credential values do not belong in
+the brief or research evidence.
+
+## Map interception opportunities
+
+For each relevant candidate, state compactly:
+
+- **Location and stage:** node/edge, before/after model dispatch or tool execution.
+- **Visible context:** messages, tool arguments/results, principal, or unknown.
+- **Powers:** observe, modify, block or require approval, only as supported.
+- **Coverage:** covered routes, conditions, bypasses and unresolved continuations.
+- **Basis:** proposed placement, documented/implemented extension, configured
+  integration, or exercised behavior; link evidence and preserve its limits.
+
+A proxy only sees traffic routed through it. Seeing tool schemas, model-proposed
+calls or returned results in model traffic does not prove mediation of the actual
+tool invocation or downstream effects. Trace the tool executor separately. Keep
+browser-direct routes, scheduled workers and other known alternate paths visible.
+
+A hook's presence does not establish its timing, veto power or complete coverage.
+A sidecar is placement, not an interception mechanism: identify routing, hooks or
+event delivery and how a decision reaches execution. Observation-only telemetry
+is not enforcement. Record failure behavior if known, or as a gap relevant to
+later setup selection; a documented claim is not a runtime test.
+
+Record potential cross-service observation points and correlation gaps without
+claiming end-to-end trace coverage. Do not select a vendor or infer product
+compatibility from names or protocols. If evidence supports only an opportunity,
+say so. Stop once the brief answers the question with gaps visible. Do not install,
+bind resources, configure proxies/hooks or run integration tests as part of it.
+
+## Continue and reconcile
+
+Size and deployment knowledge are independent. A bound setup can have a skeleton;
+a detailed product description can remain unbound. When saving or continuing,
+follow [working notes](working-notes.md), preserving predecessors and evidence.
+
+For Lab-managed changes, the intended consumer behavior is to record a successor
+setup/binding revision with the change and its evidence; an Experiment requests
+resources from its Lab, which owns bindings. This skill does not implement that
+automation. A request is not proof that configuration succeeded. Keep effective
+setup unknown until supported by observation.
+
+Changes outside the Lab do not automatically update saved descriptions. On an
+explicit reconciliation request, read current identified evidence, compare it
+with the predecessor and save an authorized successor. Preserve stable identities,
+explain changed declarations/bindings and retain uncertainty about effective use.
+Reference an unchanged definition when only bindings change; use a successor
+definition when composition or intended settings change. Keep profile version
+unchanged unless the output rules change. Do not retrospectively rebind prior Runs.

package/plugins/n8r-surface/skills/research/references/working-notes.md

@@ -0,0 +1,116 @@
+# Working research notes
+
+Use Markdown for the first portable research increment. These are readable
+working notes, not a released interchange schema or a validated experimental
+HTML/Surface artefact. Use the user's requested prose format when practical;
+retain the same evidence and limitations. Do not impose a large empty template.
+
+## Where notes live
+
+Use a user-selected destination first. When an applicable vault convention places
+Surface descriptions under `surfaces/<source-slug>/`, propose a numbered file
+such as `surface-draft-001.md` there. A save offer does not create directories or
+files; wait for acceptance. Without that convention, use the default below for
+the same Markdown working draft. When continuing a saved note, use its
+folder unless the user requests a move. Otherwise, on a host with a persistent
+user-owned local filesystem, use:
+
+```text
+~/Documents/n8r-surface/research/<source-slug>/<topic>-001.md
+```
+
+Derive short lowercase hyphenated slugs from the source and question. For a
+LibreChat authentication investigation, use `librechat/authentication-001.md`.
+Resolve the user's actual home directory through the host, expand `~`, and show
+the absolute folder and filename before writing. Create missing directories as
+part of an authorized save. Keep that local locator in the conversation, not in
+portable note content. Do not treat a temporary execution container as the user's
+persistent filesystem. If local saving is unavailable, explain that limitation
+and offer a named Markdown download or text without claiming the default exists.
+
+List existing notes for that topic first. Use the next unused three-digit number
+(`002`, `003`, and so on; grow beyond three digits if needed). An existing filename
+is never permission to overwrite. For continuation, read the predecessor and any
+human edits, name it in the successor and record the change. Recheck its bytes
+before saving; if they changed, reread and reconcile before choosing a new output.
+Check that existing notes describe the same source before continuing them;
+matching directory names alone do not establish source identity.
+
+Provide the actual saved file as a clickable link after readback. On a local
+host, use an absolute file link. The user should be able to open it without
+searching the plugin cache or scrolling back through tool output. Skill removal
+must leave this research folder and every previous note intact.
+
+## What a note retains
+
+A saved note should let another person or a fresh chat continue the task:
+
+- Identify the question, scope, date, skill version and host/tool capabilities
+  actually used. Do not guess a hidden model ID or application version.
+- Identify the supplied sources using portable relative names or public locators.
+  Record available revision/version information and exact hashes for inspected
+  files when supported. Explicitly mark unavailable identity evidence.
+- Lead with the partial AI Surface graph or edge table, stable component labels
+  and evidence locations. Keep supported possibilities separate from selected
+  connections. Include only settings needed to explain the graph, not an app-wide
+  configuration inventory.
+- Preserve conflicting claims, unknowns, coverage limits and scoped absences.
+- Retain human decisions and unanswered questions separately from source evidence.
+- State what was actually read or exercised and what remains to be done. Include
+  **Recommended next steps** as described below, and a useful next question when
+  a user decision is needed.
+
+Keep source links usable when the notes are moved, or explain what accompanying
+source files are needed. Do not copy whole repositories or credentials into the
+notes. A source digest identifies bytes, not truth, completeness or compatibility.
+
+## Recommended next steps
+
+Include a **Recommended next steps** section in the latest Surface note for the
+same source and scope. If no Surface note exists, include it in the latest research
+note. A Surface note here is a saved prose description of the Surface; this rule
+does not add validated structured-output support or require creating one.
+
+For each recommendation, state:
+
+- **Next investigation:** the concrete question or connection to investigate.
+- **Why it matters:** which uncertainty or user decision it would resolve.
+- **Where to resume:** the relevant source file/section, component ID, saved note
+  or permitted view, plus any access or missing evidence needed to proceed.
+
+Use portable references, not local absolute paths or credentials. For example:
+
+> **Next investigation:** establish the selected document-search target.
+> **Why it matters:** the optional search path has no address in the supplied
+> settings, so its selected connection remains unresolved.
+> **Where to resume:** `current.env`, `DOCUMENT_SEARCH_URL`, and `system.md` →
+> Uploaded documents; request applicable deployment settings if available.
+
+When continuing, read this section alongside the predecessor and human edits,
+re-establish source identity, and use it to choose the next investigation within
+the user's current scope. Recommendations are proposed work, not permission for
+new access or evidence that a connection exists. If the needed evidence is
+unavailable, retain the blocker and a concrete resumption point.
+
+In the saved successor, update the section to reflect what was resolved, what
+remains and the next useful investigation. Explain a changed priority or superseded
+recommendation briefly. Preserve earlier notes unchanged. If an older note has
+no recommendations, derive them from its supported gaps and current evidence in
+the successor; do not retrofit the predecessor. If no further investigation is
+needed within scope, say so and explain why rather than inventing work.
+
+## Save and read back
+
+If the destination already exists or changed since it was read, stop that write
+and propose a new file or a reviewed merge. Do not claim atomic guarded storage
+or byte-conflict guarantees that the host has not provided.
+
+After saving, read the saved bytes through an available tool and check that the
+findings, references, uncertainties, human choices and current recommendations
+survived. Provide the actual path or download and report any readback limitation. Merely printing a filename
+is not a save. Reopening in a fresh chat is a separate continuation check.
+
+Installing or removing the skill changes its availability in the host. User notes
+belong to the user and must remain outside the plugin installation/cache folders.
+Never delete research as part of skill removal. Uninstallation does not erase
+instructions or source content already present in an old conversation.