@remembrance-ai/opencode-plugin 0.1.47 → 0.1.48

package/skills/remembrancer/SKILL.md

@@ -11,17 +11,25 @@ You are the entry skill for Remembrance: shared operational memory for agent ski
 
 The presence of this filesystem skill does not, by itself, prove that the
 native plugin is fully active. The first time Remembrance is relevant in a host
-session, call `get_connection_status` before relying on plugin automation. A
+session, call `run_connection_doctor` before relying on plugin automation. A
 healthy native install reports its MCP transport, authenticated scope, and the
-observed startup and prompt lifecycle. Tool-observer and completion timestamps
-appear after those events become eligible; their absence during the first
-prompt is not, by itself, a failure.
-
-If this skill is visible but `get_connection_status` is absent, explicitly tell
+observed startup and prompt lifecycle after a safe catalog read. Local MCP also reports
+`local_signing_identity` without exposing its subject or private key. A missing
+identity initializes automatically on the first signed contribution; an
+invalid identity requires explicit restore or rotation. Follow the returned
+machine-readable `next_action` rather than asking the user to invent an
+identity. Tool-observer and completion timestamps appear after those events
+become eligible; their absence during the first prompt is not, by itself, a
+failure.
+
+If this skill is visible but `run_connection_doctor` is absent, explicitly tell
 the user that Remembrance is only partially active. Do not silently fall back
 and do not diagnose the registry as anonymous or unavailable. Update or
 reinstall the host-specific plugin, verify that its bundled MCP registration is
-enabled, fully quit and reopen the host, and check again. Codex, Claude Code,
+enabled, fully quit and reopen the host, and check again. The independent
+`npx @remembrance-ai/mcp-server doctor` command can verify registry/auth access,
+but it cannot prove host MCP registration; rerun `run_connection_doctor` inside
+the host after repair. Codex, Claude Code,
 Cursor, and OpenClaw local plugin MCP servers read the same shared credential
 as their hooks from `~/.config/remembrance/config.json`; an intentionally
 configured hosted HTTP MCP instead needs a credential forwarded on that HTTP
@@ -45,9 +53,12 @@ Use the MCP tool `query_skills` when available, or call the REST endpoint
 `POST /api/v1/agent/query`. These are equivalent discovery paths.
 
 Before diagnosing authentication, call the MCP tool
-`get_connection_status` for the transport you will actually use. It reports
+`run_connection_doctor` for the transport you will actually use. It reports
 the local or hosted transport, the credential source, and the verified registry
-scope without returning the key. Never conclude that a plugin is anonymous
+scope after a non-mutating catalog read, with exact bounded remediation and
+without returning the key, absolute local paths, or private registry URLs. Use
+`get_connection_status` only when the underlying fields are needed. Never
+conclude that a plugin is anonymous
 because `REMEMBRANCE_API_KEY` is unset: native hooks and local/bundled MCP can
 read `~/.config/remembrance/config.json`. Hosted MCP cannot read a file on the
 caller's machine and uses only the credential forwarded on its HTTP request.
@@ -356,8 +367,9 @@ When `useful` is `false`, or a positive `lesson` is substantive, the response
 may include `next_step.submit_remembrance_payload`. Submit that payload with
 `submit_remembrance` or `POST /api/v1/agent/remembrances` when the lesson should
 become verified reusable evidence. MCP users can set
-`verified_attestation: true` after `bootstrap_agent_identity`; REST-only agents
-can sign the payload by following `references/attestation-rest.md`.
+`verified_attestation: true`; local MCP initializes a missing opaque identity
+automatically. REST-only agents can sign the payload by following
+`references/attestation-rest.md`.
 
 Always attach evidence to public submissions: concrete reproduction detail in
 `outcome.failure_modes`, `evidence.artifact_hashes` (sha256 of redacted logs,
@@ -469,10 +481,12 @@ Independent adapters can register lower-trust TOFU keys with a private-key proof
 
 POST https://remembrance.dev/api/v1/agent/keys/register
 
-Agents with MCP should prefer `npx @remembrance-ai/mcp-server` and run
-`bootstrap_agent_identity` once. REST-only agents should follow the bootstrap
-recipe in `references/attestation-rest.md`. Both paths create or reuse a local
-key at
+Agents with MCP should prefer `npx @remembrance-ai/mcp-server`. No identity
+argument or separate setup step is required: the first signed contribution
+creates an opaque subject derived from the public-key fingerprint. Call
+`bootstrap_agent_identity` with no arguments only to preflight that capability
+or recover it. REST-only agents should follow the bootstrap recipe in
+`references/attestation-rest.md`. Both paths create or reuse a local key at
 `REMEMBRANCE_AGENT_KEY_PATH` or `~/.config/remembrance/agent-key.json`, register
 it as a lower-trust TOFU key, and allow later feedback or remembrances to carry
 verified TOFU attestations.
@@ -505,9 +519,10 @@ Worked trust decisions:
 attestation unless `REMEMBRANCE_AGENT_KEY_PATH` overrides it. Back it up like an
 agent identity secret, and do not commit or share it. If the file is deleted,
 rerun the REST bootstrap recipe in `references/attestation-rest.md`, or run
-`bootstrap_agent_identity` if MCP is available. This creates a new TOFU key and
-subject trust history. The old verified-tier history is not recoverable unless
-the original key file was backed up. Use an org API key or a future
+`bootstrap_agent_identity` with no arguments if MCP is available. This creates
+a new TOFU key and opaque subject trust history. The old verified-tier history
+is not recoverable unless the original key file was backed up. Use an org API
+key or a future
 registered-provider key when durable trust continuity matters.
 
 ## New skill idea endpoint
@@ -610,7 +625,7 @@ command, and never report it as submitted.
 
 For organization skills derived from private repository material:
 
-1. Submit directly only when `get_connection_status` confirms organization
+1. Submit directly only when `run_connection_doctor` confirms organization
    scope and the host permits Remembrance as an approved destination.
 2. If host policy blocks export, call the local-only
    `queue_private_skill_import` tool when it is available. It writes a mode-0600

package/skills/remembrancer/references/remembrance-payloads.md

@@ -75,9 +75,9 @@ Populated v2 attestation shape:
 }
 ```
 
-For MCP users, `bootstrap_agent_identity` handles key generation, proof signing,
-registration, and persistence; `submit_feedback` can then add this object when
-`verified_attestation: true` is set.
+For local MCP users, `verified_attestation: true` initializes a missing opaque
+identity automatically, then signs the feedback. `bootstrap_agent_identity`
+remains available as a zero-argument preflight and recovery tool.
 
 REST-only agents can follow `attestation-rest.md` for the canonical signing
 payloads, local key file shape, and dependency-free Node example.
@@ -173,7 +173,7 @@ not discard valid post-use feedback or alter ranking by itself.
       }
     },
     "payload": { "...": "same object, retained as a generic alias" },
-    "mcp_hint": "MCP users can call submit_remembrance with this payload and verified_attestation: true after bootstrap_agent_identity. REST clients can POST submit_remembrance_payload to /api/v1/agent/remembrances."
+    "mcp_hint": "Local MCP users can call submit_remembrance with this payload and verified_attestation: true; a missing opaque signing identity initializes automatically. REST clients can POST submit_remembrance_payload to /api/v1/agent/remembrances."
   }
 }
 ```
@@ -205,9 +205,10 @@ Local identity recovery: the persisted key file
 `~/.config/remembrance/agent-key.json` is a private key. Back it up like an
 agent identity secret, and do not commit or share it. If it is deleted, rerun
 the REST bootstrap recipe in `attestation-rest.md`, or rerun
-`bootstrap_agent_identity` when MCP is available. Remembrance will register a
-new TOFU key and new subject trust history. The old verified-tier history cannot
-be recovered without the original key file. Use an org API key or future
+`bootstrap_agent_identity` with no arguments when MCP is available. Remembrance
+will register a new TOFU key and opaque subject trust history. The old
+verified-tier history cannot be recovered without the original key file. Use
+an org API key or future
 registered-provider key for durable trust continuity.
 
 ## Empty query response

package/skills/remembrancer/references/remembrance-setup.md

@@ -11,7 +11,7 @@ REST/HTTPS, skill-only installs, enterprise org keys, local identity, and common
   Cursor, Gemini, or another agent.
 - The user has an enterprise/org API key and needs to make an agent use
   org-scoped skills or private overlays.
-- MCP tools such as get_connection_status, query_skills, list_skills,
+- MCP tools such as run_connection_doctor, get_connection_status, query_skills, list_skills,
   invoke_skill, submit_query_feedback, submit_feedback, submit_remembrance,
   propose_private_skill, queue_private_skill_import, report_task_outcome,
   get_value_proof, get_skill, get_resource, or bootstrap_agent_identity are
@@ -129,7 +129,7 @@ openclaw remembrance setup
 If ClawHub search shows multiple Remembrance matches, use the official package
 that points to "dreamarkinc/remembrance-skills", mentions the Remembrance agent
 skill/resource service, and exposes the expected Remembrance MCP tools such as
-get_connection_status, query_skills, list_skills, invoke_skill,
+run_connection_doctor, get_connection_status, query_skills, list_skills, invoke_skill,
 submit_query_feedback, submit_remembrance, get_skill, and get_resource, plus
 report_task_outcome and get_value_proof. Do not install
 unrelated roots, genealogy, ancestry, or memorial packages.
@@ -190,9 +190,11 @@ chmod 600 ~/.config/remembrance/config.json
 ~~~
 
 Do not infer connection scope by checking one environment variable. After
-setup, call MCP `get_connection_status`. It names the active transport,
-credential source, verified organization/public scope, and config permission
-status without exposing the key. An anonymous curl or browser probe describes
+setup, run MCP `run_connection_doctor`. It performs a non-mutating catalog
+read and names the active transport, credential source, verified
+organization/public scope, and config permission status with one exact
+remediation, without exposing the key, absolute paths, or custom registry URLs.
+Use `get_connection_status` only for the underlying fields. An anonymous curl or browser probe describes
 only that request, not the plugin. Raw REST clients do not load this file
 automatically; they must deliberately read it or send a key header.
 
@@ -203,14 +205,30 @@ export REMEMBRANCE_API_KEY="YOUR_ORG_KEY"
 export REMEMBRANCE_API_URL="https://remembrance.dev"
 ~~~
 
+For a custom registry, bind the key to that exact destination. Store `apiKey`
+and `apiUrl` together in the shared config, or bind environment credentials
+explicitly:
+
+~~~bash
+export REMEMBRANCE_API_KEY="YOUR_ORG_KEY"
+export REMEMBRANCE_API_URL="https://registry.example"
+export REMEMBRANCE_API_KEY_ORIGIN="https://registry.example"
+~~~
+
+Every remote registry requires HTTPS; only loopback development may use HTTP.
+An intentionally trusted private or link-local HTTPS registry also requires
+`REMEMBRANCE_ALLOW_PRIVATE_REGISTRY=true`. If the destination and credential
+binding do not match exactly, Remembrance pauses remote calls instead of
+forwarding the key.
+
 For Codex Desktop, the packaged plugin now runs a bundled local MCP server.
 The native hooks and MCP process both read the shared file above, so the GUI
 does not need `launchctl setenv` for the normal plugin path. Fully quit and
-reopen Codex after installing or updating the plugin, then call
-`get_connection_status`. A healthy install reports `local_stdio_mcp`, the
+reopen Codex after installing or updating the plugin, then run
+`run_connection_doctor`. A healthy install reports `local_stdio_mcp`, the
 expected organization scope, and an active `plugin_health` lifecycle.
 
-If filesystem skills are visible but `get_connection_status` is absent, or if
+If filesystem skills are visible but `run_connection_doctor` is absent, or if
 that tool reports missing native hooks, treat the install as partially active.
 Update or reinstall from the Remembrance marketplace, fully restart Codex, and
 run the check again. The plugin records only local component timestamps and
@@ -219,6 +237,12 @@ codes for deduplicated global-admin triage. It never submits prompts, keys,
 paths, or raw logs. Set `REMEMBRANCE_HEALTH_REPORTING=0` to disable that
 best-effort report.
 
+If no Remembrance MCP tool is visible, run
+`npx @remembrance-ai/mcp-server doctor`. This safely verifies registry,
+credential, and catalog-read access outside the host, but it deliberately
+reports host registration as unobservable. Update or reinstall the native
+plugin, fully restart the host, then rerun `run_connection_doctor` inside it.
+
 A manually configured hosted MCP URL is still supported, but hosted MCP cannot
 read the shared file and must receive its own request credential. Only that
 manual override needs a process environment or HTTP header credential. A Codex
@@ -283,6 +307,7 @@ Add this separately to `managed_config.toml`:
 enabled = true
 enabled_tools = [
   "get_connection_status",
+  "run_connection_doctor",
   "query_skills",
   "list_skills",
   "invoke_skill",
@@ -358,9 +383,8 @@ overrides `launchctl` and the config file.
 For the Claude Code desktop app, prefer the shared mode-0600 config file above.
 The plugin hooks and bundled local MCP server both read it, so the GUI process
 does not need to inherit shell exports or duplicate the key in Claude settings.
-Fully quit and relaunch Claude Code after changing the file, then call
-`get_connection_status` and confirm `shared_config`, `local_stdio_mcp`,
-active plugin health, and the expected organization scope.
+Fully quit and relaunch Claude Code after changing the file, then run
+`run_connection_doctor` and require `safe_to_query: true`.
 
 For Cursor, prefer the shared config file above. The Cursor plugin-managed MCP
 server and local hooks read it. If using a non-prod Remembrance endpoint, include
@@ -381,6 +405,7 @@ bounded feedback/outcomes, and organization-private contribution:
 
 ~~~text
 get_connection_status
+run_connection_doctor
 query_skills
 list_skills
 invoke_skill
@@ -446,6 +471,7 @@ Merge this into managed settings:
   "permissions": {
     "allow": [
       "mcp__remembrance__get_connection_status",
+      "mcp__remembrance__run_connection_doctor",
       "mcp__remembrance__query_skills",
       "mcp__remembrance__list_skills",
       "mcp__remembrance__invoke_skill",
@@ -473,8 +499,8 @@ The exclusive managed MCP file lives at
 `/etc/claude-code/managed-mcp.json` on Linux/WSL, and
 `C:\Program Files\ClaudeCode\managed-mcp.json` on Windows. The sandbox
 domain applies to command/REST fallbacks; managed HTTP MCP authorization remains
-the exact server URL plus named tools. Verify with `claude mcp list`, then call
-`get_connection_status` and confirm organization scope before contribution
+the exact server URL plus named tools. Verify with `claude mcp list`, then run
+`run_connection_doctor` and require organization scope before contribution
 work. See the official
 [managed MCP](https://code.claude.com/docs/en/managed-mcp),
 [permissions](https://code.claude.com/docs/en/permissions), and
@@ -500,6 +526,7 @@ narrow server/tool set:
       },
       "includeTools": [
       "get_connection_status",
+      "run_connection_doctor",
       "query_skills",
       "list_skills",
       "invoke_skill",
@@ -523,7 +550,7 @@ System settings live at `/Library/Application Support/GeminiCli/settings.json`
 on macOS, `/etc/gemini-cli/settings.json` on Linux, and
 `C:\ProgramData\gemini-cli\settings.json` on Windows. Also allow
 `remembrance.dev` in the organization's egress policy. Restart Gemini CLI,
-inspect the registered server, then call `get_connection_status` and confirm
+inspect the registered server, then run `run_connection_doctor` and require
 organization scope before contribution work. See the official
 [enterprise configuration](https://google-gemini.github.io/gemini-cli/docs/cli/enterprise.html)
 and [MCP settings](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html).
@@ -552,6 +579,7 @@ tool profile hides MCP tools, and `tools.deny: ["bundle-mcp"]` disables them:
         "toolFilter": {
           "include": [
       "get_connection_status",
+      "run_connection_doctor",
       "query_skills",
       "list_skills",
       "invoke_skill",
@@ -597,8 +625,8 @@ the server's `toolFilter`. Merge this separately into `policy.jsonc`:
 ~~~
 
 Keep the organization key in the plugin's mode-0600 shared config or another
-approved secret source, not in `policy.jsonc`. After the probes, call
-`get_connection_status` and confirm organization scope. See the official
+approved secret source, not in `policy.jsonc`. After the probes, run
+`run_connection_doctor` and require organization scope. See the official
 [plugin policy](https://docs.openclaw.ai/tools/plugin),
 [conversation hook policy](https://docs.openclaw.ai/plugins/hooks),
 [MCP tool filters](https://docs.openclaw.ai/cli/mcp), and
@@ -616,7 +644,7 @@ based fallback paths.
 Cursor's current public enterprise documentation does not define a managed
 per-MCP-tool allowlist equivalent to Codex, Claude Code, Gemini CLI, or
 OpenClaw. Keep Cursor's normal tool approvals enabled and do not claim an
-undocumented control exists. Call `get_connection_status` and confirm
+undocumented control exists. Run `run_connection_doctor` and require
 organization scope on every enabled surface, then verify query, invocation,
 feedback, and private-contribution receipts; local plugin hooks and cloud-agent
 hooks can differ. See the official
@@ -633,8 +661,8 @@ tool list above when the client supports tool filtering. Keep normal approval
 behavior for non-read-only calls unless unattended organization-private
 contribution is explicitly approved. A client with no server/tool policy must
 use its existing destination control or the zero-network handoff. Supply the
-organization key through the client's secret/header mechanism, then call
-`get_connection_status` and confirm organization scope before private writes.
+organization key through the client's secret/header mechanism, then run
+`run_connection_doctor` and require organization scope before private writes.
 
 If any host still denies the export, that denial remains authoritative. The
 portable local handoff and dashboard import work identically for Codex, Claude
@@ -665,6 +693,16 @@ Local stdio MCP server:
 npx @remembrance-ai/mcp-server
 ~~~
 
+Independent setup check when the host does not expose Remembrance tools:
+
+~~~bash
+npx @remembrance-ai/mcp-server doctor
+~~~
+
+This verifies registry, credential, and catalog-read access without submitting
+content. It cannot prove host MCP registration; after repair, rerun
+`run_connection_doctor` inside the host.
+
 Cursor MCP fallback config (use this only when plugin install is unavailable):
 
 ~~~json
@@ -728,16 +766,17 @@ be copied to ".agents/skills/remembrancer/SKILL.md" for compatible providers.
 
 1. Start a fresh agent session.
 2. Check whether Remembrance MCP tools are visible. Expected tools include
-   get_connection_status, query_skills, list_skills, invoke_skill, get_skill,
+   run_connection_doctor, get_connection_status, query_skills, list_skills, invoke_skill, get_skill,
    get_resource, submit_query_feedback, submit_feedback, submit_remembrance,
    propose_private_skill, report_task_outcome, get_value_proof, and
    bootstrap_agent_identity. Local MCP also exposes
    queue_private_skill_import. Clients
    with MCP resource discovery should also expose paginated
    `remembrance://skills/{slug}` handles.
-3. Call get_connection_status and confirm the active transport, credential
-   source, and expected public/organization scope before inspecting environment
-   variables or making a raw probe.
+3. Call run_connection_doctor and require `safe_to_query: true`. Confirm the
+   active transport and expected public/organization scope before inspecting
+   environment variables or making a raw probe. Follow its exact remediation
+   for any warning or failure.
 4. Ask the agent to query Remembrance for a known task, for example:
    "Query Remembrance for web UI QA before reviewing a responsive dashboard."
 5. Follow with a context-only prompt such as "fix these issues". Confirm the
@@ -781,8 +820,10 @@ be copied to ".agents/skills/remembrancer/SKILL.md" for compatible providers.
    queue_private_skill_import instead, upload its JSON in the dashboard, and
    verify the agent reports a local queue receipt separately from the server
    import receipt.
-14. If using local MCP, run bootstrap_agent_identity once when verified TOFU
-   contributions are needed.
+14. If using local MCP, verify local_signing_identity in get_connection_status.
+   A missing opaque identity initializes automatically on the first signed
+   contribution; bootstrap_agent_identity with no arguments is an optional
+   preflight or recovery action.
 
 ## Troubleshooting matrix
 

package/src/index.mjs

@@ -13,7 +13,7 @@
 //
 //   SESSION START  (event -> session.created): records lifecycle health under the
 //     "opencode" surface and logs the activation notice, so a user can see the
-//     plugin loaded and knows to call get_connection_status.
+//     plugin loaded and knows to call run_connection_doctor.
 //
 //   PROMPT (chat.message -> experimental.chat.system.transform): queries from
 //     the current user turn, then injects the bounded result into the model's
@@ -268,7 +268,7 @@ export const Remembrance = async (context = {}) => {
       await notify(
         client,
         `Remembrance ${version} is active. Relevant memory is added before eligible turns; ` +
-          "get_connection_status verifies tools and organization access without exposing the key.",
+          "run_connection_doctor verifies the active connection and gives one exact next step without exposing the key.",
       );
     } catch (error) {
       debugLog(env, "opencode_session_created_failed", {