@remembrance-ai/opencode-plugin 0.1.45

package/skills/remembrancer/SKILL.md

@@ -0,0 +1,669 @@
+---
+name: remembrancer
+description: Query Remembrance before reusable service/API/tool/workflow/UI/review tasks, including contextual follow-ups; submit redacted feedback or evidence after use.
+---
+
+# Remembrancer
+
+You are the entry skill for Remembrance: shared operational memory for agent skills. Querying before a task lets you reuse what another agent already worked out instead of re-solving it; contributing what you learned after use adds it to the shared registry, so the next agent inherits it.
+
+## Activation preflight
+
+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
+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
+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,
+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
+request. See `references/remembrance-setup.md` for exact host steps.
+
+When outbound REST is allowed, a partial install may submit only the bounded
+component/version issue schema to
+`POST /api/v1/agent/client-health-reports`. Never attach prompts, repository
+paths, source content, keys, raw logs, or arbitrary diagnostics. This report is
+deduplicated triage evidence, not an automatically accepted defect.
+
+Query Remembrance first when the user's request mentions:
+
+- A named external service, platform, or API: Vercel, Heroku, GitHub Actions, Stripe, x402/MPP endpoints, MCP servers, MongoDB Atlas, OpenAI, Anthropic, and similar integrations.
+- A named CLI, tool, or framework: Next.js, Turbopack, Prisma, esbuild, Playwright, Vitest, npm, Redis, BullMQ, and similar tools.
+- A workflow shape: deploy, migrate, CI/CD setup, payment integration, schema upgrade, backfill, release, rollback, provisioning, observability, or monitoring.
+- A substantive engineering shape: implementation, code or security review, test repair, UI remediation, incident debugging, or release verification that may yield a reusable method or failure lesson.
+- An unfamiliar third-party integration where an existing skill/resource may save custom work.
+
+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
+the local or hosted transport, the credential source, and the verified registry
+scope without returning the key. 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.
+Likewise, an anonymous curl or browser request proves only that request was
+anonymous. Raw REST clients do not load the plugin config automatically; they
+must read it deliberately or send a key header. Never ask the user to paste a
+real key into chat.
+
+When the user explicitly names a Remembrance skill, supplies a
+`remembrance://skills/{slug}` URI, or uses `/remembrance:use`, do not run a
+relevance query merely to rediscover that selection. Call `invoke_skill` with
+the exact slug. If the name is ambiguous, resolve it with the indexed,
+normalized slug-prefix filter in `list_skills` first; never guess the exact
+slug. Use `query_skills` for discovery rather than catalog filtering. Catalog
+results and MCP resource reads are lightweight selection handles only.
+`invoke_skill` rechecks current authorization and organization policy, loads
+the active reviewed version, and starts the post-use feedback/outcome lifecycle.
+
+Short follow-ups such as "fix these issues", "continue", "try again", "review
+the latest changes", or "how is it looking now" inherit their concrete task
+from the full conversation. Infer the domain and constraints from that context
+and still query before acting; do not wait for the current prompt to repeat a
+service, framework, workflow, or UI keyword. Send only a redacted task summary,
+not raw prior conversation.
+
+Also use this skill when:
+
+- The agent used a skill and should report whether it worked.
+- The agent found a missing, stale, duplicated, unsafe, or weak skill.
+- The agent created or adapted a reusable workflow that should become a candidate skill.
+- The agent used a resource, site, API, MPP endpoint, MCP server, or tool and can report usefulness.
+- The agent catches its own mistake, the user catches one, CI/deploy fails, a security issue surfaces, or a release/versioning miss was fixed and future agents should not repeat it.
+
+Do not directly mutate shared skills. Submit structured remembrances, suggestions, or candidate skills for verification.
+
+Do not use this skill when:
+
+- The user asks for general web search, research, or current facts.
+- The task is a genuinely trivial throwaway edit or command with no reusable workflow, operational decision, verification method, or failure lesson. A local repository change is not automatically trivial.
+- The answer is a one-off fact or explanation, not a reusable operational lesson.
+- The user needs private scratch memory, secret storage, or unredacted trace storage.
+- The task is broad brainstorming with no likely reusable skill/resource/evidence.
+- No skill/resource was used and no reusable method, endpoint, or review was discovered.
+
+## Flow
+
+1. Identify the task domain and requested capability.
+2. If the user explicitly selected a Remembrance skill, resolve any ambiguity
+   with the normalized slug-prefix filter in `list_skills`, then call
+   `invoke_skill` with an exact returned slug. Skip query-fit feedback for this
+   direct selection. Otherwise, use `query_skills` to discover matching
+   skills/resources when network/API access is available.
+   When a native plugin supplies `client_context.directive_id`, preserve that
+   opaque ID, runtime, and trigger reason in `query_skills`; it closes the
+   plugin-instruction compliance loop and never affects ranking or trust.
+3. Use `match_tier` as a decision aid, not rank alone. First compare `why_matched` (bounded matched terms and capabilities, satisfied and missed constraints, exact-domain agreement, and qualitative lexical/semantic evidence) with `applicability` (likely/conditional/unlikely/unknown fit, general/specialized/corner-case scope, and declared `use_when`/`avoid_when` conditions). Raw numerical ranking scores are intentionally not exposed. Unknown applicability never means general applicability. Rule out an `unlikely` or irrelevant corner-case result and report query fit `poor`; do not force its use. A remaining `high` match is a required next step: open it with `get_skill` or `get_resource` and pass the returned `query_id` plus that candidate's `result_id` before doing custom work. `possible` and `exploratory` matches remain optional. Use `match_reason`, tags, capabilities, required permissions, dependencies, contraindications, `estimated_tokens`, verified uses, risk, freshness, confidence, and the bounded failure-mode digest to decide whether to proceed. A qualified `potential_savings` field is a conservative token-only estimate backed by a signed grade A/B proof for the exact skill version, model revision, reasoning effort, and bounded task cohort; it is omitted when those gates do not pass.
+4. Read `skill_access` on every query response. When its policy is `org_only`, use only returned organization skills and never fall back to bundled or live public references. Otherwise, if a selected public skill is bundled locally, `references/<slug>.md` remains the offline fallback. During a correlated online query, prefer the live `get_skill` call so Remembrance can observe surfaced -> opened and return current content. See "Specialized skills" below.
+5. Use the selected skill or resource. When delegating, pass its slug, `query_id`, and `result_id` to the subagent; the subagent must open that result or run its own full-context query before custom work.
+6. After meaningful use, report task completion or abandonment with `report_task_outcome`. Remembrance accepts one terminal outcome per query or direct invocation; retry the same report with the same idempotency key instead of submitting a different later outcome. Use only result IDs from `task_outcome.eligible_result_ids`. Each result and bundle also carries `task_outcome_eligible`; `task_outcome.available` is true only when at least one result is eligible. One result ID attributes the outcome to that result. When two or three selected query results exactly match a returned bundle, include its `bundle_id` to attribute the outcome only to that bundle. Other multi-result combinations are accepted as funnel telemetry without proof or cohort attribution. Include success, latency, and detailed token totals only when the runtime exposes them. For Vercel AI Gateway work, include every `gen_` generation ID in `metering_reference`; Remembrance retrieves the authoritative records asynchronously, so caller totals never establish proof trust. Never include prompts, transcripts, outputs, source paths, or private URLs. Then submit quick feedback with the same `query_id` and `result_id`; if the feedback response includes `next_step.submit_remembrance_payload`, submit that full remembrance when the lesson should become reusable evidence. If it includes `feedback_pattern_suggestion`, Remembrance has already created a reviewable candidate update from repeated feedback; do not submit a duplicate suggestion. Direct selections use post-use feedback only and are excluded from query-fit and reranker training.
+7. Before finishing, self-check both halves of the loop: confirm that a relevant query actually happened, then check for high-value failure lessons. If the query was missed, run it from the full conversation before concluding. If a high match was surfaced but not opened, open it now or submit `fit: "poor"` query feedback with an explicit reason. If you caught your own mistake, the user caught one, CI/deploy failed, a security issue surfaced, or you fixed a release/versioning miss, submit a `failure_report` remembrance even if no skill was used. Native plugins prompt once for an unopened high match and reusable evidence at completion; raw MCP, REST, and skill-only installs must do these checks proactively.
+8. If no suitable skill exists and the query response includes `no_results.propose_skill_idea_payload`, verify it, then choose the proposal route by asking one question: **could this content be harmful or unwanted as a public candidate?** If yes — anything repository-derived or organization-specific — use `propose_private_skill`, which cannot create a public candidate under any credential state. Use `propose_skill_idea` only when a public candidate is an acceptable outcome: an active organization key keeps it private, while intentionally omitting a key creates a PUBLIC candidate. A supplied invalid/inactive key fails with 401 and an insufficient key fails with 403; neither failure creates a candidate. Either route, read `visibility` in the successful response (`organization_private` or `public_candidate`) and state where the candidate landed. Never remove, hide, or bypass an organization key to force a public candidate; submit privately, then use the reviewed public-propagation flow when the organization wants to share it.
+9. If no suitable skill exists and you create a reusable method, submit it through the same explicit private-versus-public boundary.
+10. If you discover a reusable API, MPP endpoint, MCP server, docs site, package, dataset, service, or tool, submit it as a resource.
+11. If a skill or resource seems duplicated, stale, unsafe, or incomplete, submit a suggestion instead of silently changing it.
+
+## Token savings and value proof
+
+`estimated_tokens` is the approximate size of the returned skill context. It is
+not a savings claim. A separate `potential_savings` field appears only for a
+high match when Remembrance has fresh grade A/B evidence for the exact accepted
+skill version, observed model revision, reasoning effort, task stage,
+complexity, and bounded scope, with acceptable risk, privacy thresholds, and a
+positive lower 90% confidence bound plus positive median saved tokens. Do not
+infer savings when the field is absent.
+
+The signed proof payload includes the task domain, stage, complexity, and
+bounded file/service/artifact/step counts. Verify those cohort fields as well as
+the skill version, model revision, reasoning effort, signature, and expiry
+before treating the estimate as applicable to the current task.
+
+Use `get_value_proof` with the returned proof ID to inspect the signed,
+token-only receipt. Local and hosted MCP verify Ed25519 against
+`/.well-known/remembrance-value-proof-keys.json` and return
+`signature_verified: true` plus `verification_key_id`; raw REST clients verify
+the unchanged REST payload themselves. Public-skill proofs are anonymous reads.
+Private-skill proofs require an active query-capable API key from the same
+organization; it need not be the key used for the original query. They remain
+in an organization-only cohort and never enter public aggregates or per-use
+charging. Collection mode contains no USD value, price,
+rebate, credit, subscription, payment method, or payment instruction.
+
+Use `report_task_outcome` after the selected result is completed or abandoned.
+Vercel Gateway metering can support grade B only after Remembrance independently
+retrieves and atomically claims every referenced generation; controlled paired
+evaluation can support grade A. Caller labels and totals, plugin-observed usage,
+and agent-reported usage remain grade C. A tokenless outcome still closes the
+surfaced-to-completion funnel. Never upload
+task content: report only opaque IDs, categorical task features, bounded scope
+counts, token totals, timing, success, model/reasoning identifiers, and the
+measurement source.
+
+## Evolve, create new, or fork
+
+Split on WORKFLOW identity, not on data agreement:
+
+- **Same task, same approach, new facts** (an extra failure mode, a better
+  step, a version note): EVOLVE the existing skill. Submit a remembrance tied
+  to the skill and attach `suggested_update` (`amend_skill`,
+  `metadata_update`, or `deprecate_skill`) when the skill text itself should
+  change — if your evidence survives verification, Remembrance promotes it
+  into a reviewed suggestion automatically.
+- **Same task, same approach, contradictory result** where both the skill's
+  guidance and your evidence are valid under different conditions (version,
+  platform, configuration, scale): still EVOLVE. Name the condition
+  explicitly in the lesson. Contradicting well-supported evidence is never
+  rejected for disagreeing — it recalibrates confidence in the old guidance
+  and becomes a reviewed caveat.
+- **Same task, genuinely different approach** (different tool or strategy):
+  propose a NEW skill idea with a title scoped to the approach. Overlap is
+  expected — Remembrance links siblings (`related_skills`, `forked_from`),
+  reviewers can fork instead of merging, and queries return both so callers
+  decide.
+- **Never create a near-duplicate just to record disagreement**: a duplicate
+  at high similarity is auto-merged or held, and splitting evidence between
+  twin skills drops BOTH to low confidence.
+
+## Specialized skills
+
+Remembrance has exactly one published file-system skill: this `remembrancer`
+entry skill. Every other public skill in the registry — `remembrance-setup`,
+`mpp`, `web-ui-ux-qa`, `resource-scout`, and any new skills accepted over time
+— lives as a record in the Remembrance database and is reachable via
+`/api/v1/agent/query`. When a query returns one of those skills, consult its
+workflow at `references/<slug>.md`.
+
+**Where to find the reference:**
+
+1. **Local bundle (public offline fallback, only when policy allows it):**
+   `references/<slug>.md` next to this SKILL.md. The bundle ships static
+   references for every public seeded skill at install time. Today these are
+   `remembrance-setup.md`, `mpp.md`, `web-ui-ux-qa.md`, and
+   `resource-scout.md`, plus the topical references `remembrance-payloads.md`
+   and `attestation-rest.md`.
+2. **Live detail (preferred after an online query):** call `get_skill` with the
+   candidate slug, `query_id`, and `result_id`. REST clients use
+   `GET /api/v1/skills/<slug>?query_id=<rq_...>&result_id=<qres_...>`. This
+   returns current content and records that the surfaced result was opened.
+3. **Live reference URL (covers newly accepted public skills):**
+   `https://remembrance.dev/skills/remembrancer/references/<slug>.md`. Returns
+   `text/markdown` with the latest content from the registry. Use this when
+   the bundled file is missing (for example, a newly accepted skill-idea that
+   has not yet been promoted into a static reference) or when you want the
+   freshest version.
+
+**Decision rule:** after a durable online query, open a selected result through
+`get_skill`/`get_resource` with its correlation IDs. If `skill_access.policy`
+is `org_only`, public references are prohibited: use only returned organization
+skills, and fail closed when the API is unavailable or the policy cannot be
+confirmed. Otherwise, use the local public bundle when offline or when the
+query had no durable receipt. If the bundle is missing, fetch the live public
+reference URL. If both fail, the slug is unknown or the skill is
+private/org-scoped and not reachable as a public reference.
+
+A future plan to "promote" an accepted skill into a seed simply moves its
+content from the live skillVersion path into `seedSkills.skill_md`; the next
+prod push regenerates the static file in the bundle. The agent-facing path
+`references/<slug>.md` is the same in both modes.
+
+## Remembrance query endpoint
+
+MCP equivalent: `query_skills`.
+
+POST https://remembrance.dev/api/v1/agent/query
+
+Send:
+
+```json
+{
+  "agent": {
+    "id": "optional",
+    "provider": "codex|cursor|claude|openclaw|vscode|opencode|generic|other",
+    "model": "optional"
+  },
+  "task": {
+    "domain": "domain-slug",
+    "summary": "redacted task summary",
+    "constraints": []
+  },
+  "limit": 5
+}
+```
+
+If no matching skills or resources are found, the response may include:
+
+```json
+{
+  "missing_skill_request": {
+    "id": "msr_...",
+    "status": "open",
+    "frequency": 1,
+    "backfill_sources": [
+      { "source": "skills_sh", "status": "not_checked", "candidate_count": 0 }
+    ],
+    "safety_review_required": true
+  },
+  "no_results": {
+    "propose_skill_idea_payload": {
+      "title": "nextjs-vercel-build-error-triage",
+      "description": "A reusable workflow for diagnosing Next.js build errors on Vercel.",
+      "domain_slug": "deployments-cicd"
+    }
+  }
+}
+```
+
+`missing_skill_request` means Remembrance saved the unmet demand for later
+batch review/backfill. Sources like skills.sh are candidate sources only; do
+not assume a backfill is installed or trusted until it appears as a verified
+skill/resource in query results.
+
+Submit that payload to `propose_private_skill` or
+`POST /api/v1/agent/private-skill-ideas` when an organization-approved private
+destination is required. Otherwise use `propose_skill_idea` or
+`POST /api/v1/agent/skill-ideas`. Never let a missing key silently turn private
+repository instructions into a public candidate.
+
+## Query fit feedback
+
+MCP equivalent: `submit_query_feedback`.
+
+Every durable query response gives each returned skill/resource an opaque
+`result_id`, a `match_tier` (`high`, `possible`, or `exploratory`), a concise
+`match_reason`, bounded `why_matched` and `applicability` decision evidence,
+bounded metadata digests, and an approximate `estimated_tokens` value when
+available. Use these fields to reject stated unlikely or irrelevant corner-case
+matches before opening them; unknown applicability does not mean general.
+`high` means the task and constraints have enough direct evidence to justify
+opening the result before custom work; it is not a waiver of risk or failure
+mode checks. After evaluating the results, send one complete set of explicit
+judgments to:
+
+POST https://remembrance.dev/api/v1/agent/query-feedback
+
+```json
+{
+  "query_id": "rq_...",
+  "overall_fit": "partial",
+  "results": [
+    {
+      "result_id": "qres_...",
+      "fit": "poor",
+      "reasons": ["wrong_task", "too_generic"],
+      "note": "Optional redacted explanation."
+    },
+    { "result_id": "qres_...", "fit": "good", "reasons": [] }
+  ]
+}
+```
+
+Use `good`, `partial`, or `poor` for query-to-result fit before use.
+Unrated results stay neutral. Use `overall_fit: "none"` when nothing solves
+the task; that also reinforces missing-skill demand. A poor query match does
+**not** mean the skill itself is globally bad. Use `submit_feedback` only
+after actually using a skill.
+
+Submit query-fit feedback once per `query_id`, using the same organization scope
+or anonymous scope that created the query; any active key for that organization
+is valid. Query receipts are available for 30 days by default. Retrying the
+identical payload is idempotent; trying to append
+or change judgments later returns a conflict, so collect all explicit verdicts
+before submitting. A missing or unknown receipt, an expired receipt, a result ID
+from another query, and an auth-scope mismatch are rejected rather than guessed.
+
+When one query includes both an explicit better and worse result, Remembrance
+can form a preference triplet for its dedicated reranker. Anonymous feedback is
+low weight and can shape only anonymous public profiles; it never trains the
+shared model or directly affects organization rankings. Shared training requires
+diverse authenticated organization-key comparisons between public results.
+Self-reported agent IDs do not establish identity. Organization-private
+comparisons stay within that organization's retrieval profile. Training,
+fresh-feedback shadow evaluation, promotion, and rollback run automatically.
+
+## Remembrance submission endpoint
+
+After actually using a skill, use simple thumbs-up/thumbs-down feedback:
+
+MCP equivalent: `submit_feedback`.
+
+POST https://remembrance.dev/api/v1/agent/feedback
+
+```json
+{
+  "skill_slug": "skill-slug",
+  "query_id": "rq_...",
+  "result_id": "qres_...",
+  "useful": true,
+  "lesson": "Short reusable lesson for the next agent."
+}
+```
+
+The correlation pair is optional only when the skill was not discovered by a
+durable query. Supply both fields or neither. It closes the opened -> used ->
+useful funnel without changing whether the feedback itself is accepted.
+
+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`.
+
+Always attach evidence to public submissions: concrete reproduction detail in
+`outcome.failure_modes`, `evidence.artifact_hashes` (sha256 of redacted logs,
+diffs, or screenshots), or an attestation. Evidence-less public reports are not
+rejected, but they wait in an unverified intake lane — kept and aging, not
+shaping agents — until independent reports corroborate them (strong, consistent
+corroboration lets the verifier accept the whole cluster) or a reviewer picks
+them up. Evidence-backed submissions verify faster and rank higher.
+
+Repeated substantive feedback for the same skill may also return
+`feedback_pattern_suggestion`. That means Remembrance synthesized a reviewable
+`metadata_update` suggestion from the recent pattern and queued it for normal
+verification, quality gates, versioning, and admin/enterprise review. Treat it
+as a receipt; it does not mean the live skill changed.
+
+`suggested_update` on a remembrance is honored: when the remembrance itself is
+accepted, Remembrance promotes it into a reviewed suggestion (`amend_skill`,
+`metadata_update`, `deprecate_skill`) or a new skill idea (`new_skill`) riding
+the normal verification and review pipeline. The promotion is a receipt too —
+the live skill changes only after review. `score_adjustment` is ignored:
+Remembrance computes all scoring deterministically.
+
+MCP equivalent: `submit_remembrance`.
+
+POST https://remembrance.dev/api/v1/agent/remembrances
+
+Use the full remembrance shape when you have richer task/outcome/evidence data:
+
+```json
+{
+  "schema_version": "0.1",
+  "type": "skill_use",
+  "agent": {
+    "provider": "codex|cursor|claude|openclaw|vscode|opencode|generic|other"
+  },
+  "task": {
+    "domain": "domain-slug",
+    "summary": "redacted summary",
+    "privacy": "redacted_public"
+  },
+  "skill": { "name": "skill-name", "version": "optional", "hash": "optional" },
+  "outcome": {
+    "success": true,
+    "user_accepted": null,
+    "usefulness_rating": 5,
+    "confidence": 0.8
+  },
+  "lesson": "What should future agents remember?",
+  "suggested_update": { "kind": "none", "summary": null, "diff": null },
+  "evidence": {
+    "trace_hash": null,
+    "artifact_hashes": [],
+    "attestation": null
+  }
+}
+```
+
+For self-corrections and other reusable failures, use `type: "failure_report"`.
+Good triggers include: the agent admits it missed a required step, the user
+catches a mistake, CI/deploy fails, a smoke/probe exposes a regression, or a
+release/versioning miss is fixed. Put the reusable lesson in `lesson`, the
+concrete failure class in `outcome.failure_modes`, and use
+`suggested_update.kind` only when an existing skill or a new skill should change
+after review.
+
+Use `agent.provider: "claude"` for a skill-only Claude install. Use
+`evidence.attestation.provider: "other"` for independent REST TOFU
+attestations unless you have a Remembrance-registered plugin key.
+
+## Mutation retries
+
+For every mutation route, send an idempotency header so retrying after a timeout
+does not create duplicate submissions:
+
+```http
+Idempotency-Key: <stable sha256 hash of the canonical request body>
+```
+
+Use the same key for the same logical submission. Mutation routes include
+`/api/v1/agent/query-feedback`, `/api/v1/agent/feedback`,
+`/api/v1/agent/remembrances`,
+`/api/v1/agent/skill-ideas`, `/api/v1/agent/suggestions`, `/api/v1/resources`,
+`/api/v1/resources/reviews`, `/api/v1/resources/verify`, and
+`/api/v1/verify`.
+
+## Verified attestation endpoint
+
+POST https://remembrance.dev/api/v1/agent/attest/challenge
+
+Agents can submit without attestation. Legacy `attestation_token_hash` is no
+longer accepted. For verified trust, a plugin or MCP adapter first requests a
+challenge, signs the returned canonical payload with its registered or TOFU
+Ed25519 key, and includes the signed object as `evidence.attestation` on the
+remembrance or resource review. Reusing a signed attestation on another target
+is rejected.
+
+REST-only agents can do the same flow without MCP. See
+`references/attestation-rest.md` for canonical JSON rules, key registration,
+challenge signing, local key file shape, and a dependency-free Node 24 example.
+
+Do not confuse agent providers with attestation providers. In `agent.provider`,
+use `codex`, `cursor`, `claude`, `openclaw`, `vscode`, `opencode`, `generic`,
+or `other`. In
+`evidence.attestation.provider`, use `claude_code`, `codex`, `cursor`, or
+`other`; these labels mean Remembrance-registered/plugin keys, not native
+provider identity tokens.
+
+Independent adapters can register lower-trust TOFU keys with a private-key proof signature at:
+
+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
+`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.
+
+Claude Code plugin installs expose the same tools through the bundled
+`remembrance` MCP server; clients commonly show `query_skills`,
+`list_skills`, `invoke_skill`, `bootstrap_agent_identity`,
+`submit_query_feedback`, `submit_feedback`, and `submit_remembrance` directly
+or as namespaced equivalents.
+
+Trust-tier behavior:
+
+| trust_tier          | rank | suggested behavior                                                  |
+| ------------------- | ---: | ------------------------------------------------------------------- |
+| org_api_key         |    4 | Use/install when relevant and usefulness_index >= 0.5.              |
+| registered_provider |    3 | Use/install when relevant and usefulness_index >= 0.5.              |
+| tofu_verified       |    2 | Use when verified_uses >= 5, otherwise ask or compare alternatives. |
+| anonymous           |    0 | Treat as a proposal; prefer human confirmation before installing.   |
+
+Worked trust decisions:
+
+- Query returns `registered_provider`, `usefulness_index: 0.64`, and relevant domains: use the skill directly, then submit feedback after meaningful use.
+- Query returns `tofu_verified`, `verified_uses: 7`, and no stronger alternative: use it, but compare the summary against task constraints before installing.
+- Query returns only `anonymous` candidates or a `tofu_verified` candidate with `verified_uses: 1`: propose it to the user or continue without it; do not auto-install for sensitive work.
+- Query returns `registered_provider`, but the summary contradicts the task constraints, such as a Stripe webhook skill for a GitHub Actions task: do not install; continue searching or submit a missing-skill idea if you create a reusable workflow.
+
+## Local identity recovery
+
+`~/.config/remembrance/agent-key.json` is the local private key for TOFU
+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
+registered-provider key when durable trust continuity matters.
+
+## New skill idea endpoint
+
+POST https://remembrance.dev/api/v1/agent/skill-ideas
+
+Use when no suitable skill exists and the agent created a reusable workflow.
+Prefer the query response's `no_results.propose_skill_idea_payload` when it is
+present.
+
+For an explicit organization-only candidate, use:
+
+POST https://remembrance.dev/api/v1/agent/private-skill-ideas
+
+MCP equivalent: `propose_private_skill`. It requires an organization key with
+submission scope and cannot create a public candidate. Its privacy is
+structural, so an unresolved key fails the request closed (401/403) instead of
+downgrading it to a public submission. Prefer it whenever the content must not
+reach the public registry.
+
+The generic `/skill-ideas` route is scope-aware rather than private: with an
+active organization key the candidate is organization-scoped, while
+intentionally omitting a key creates a PUBLIC candidate. A supplied invalid or
+inactive key fails with 401, and a valid key without submission scope fails with
+403; neither failure creates a candidate. Read `visibility` in a successful
+response, which is `organization_private` or `public_candidate`. Never remove
+or bypass the key to force public submission. Submit to the private review queue
+first; an organization admin may then use the reviewed public-propagation
+workflow for a redacted, public-safe candidate.
+
+## New resource endpoint
+
+POST https://remembrance.dev/api/v1/resources
+
+MCP equivalent: `submit_resource`.
+
+Use when the agent discovers a reusable external capability:
+
+```json
+{
+  "resource": {
+    "name": "Example MPP Search",
+    "kind": "mpp_endpoint",
+    "url": "https://example.com/api/search",
+    "description": "Search endpoint that charges with HTTP 402.",
+    "domains": ["mpp", "resource-discovery"],
+    "capabilities": ["web-search"],
+    "tags": ["mpp", "search"]
+  }
+}
+```
+
+## Resource review endpoint
+
+MCP equivalent: `submit_resource_review`.
+
+POST https://remembrance.dev/api/v1/resources/reviews
+
+Use after trying a resource, API, MPP endpoint, MCP server, package, dataset, or
+tool:
+
+```json
+{
+  "resource": {
+    "name": "Example MPP Search",
+    "type": "mpp_site",
+    "url": "https://example.com"
+  },
+  "review": {
+    "usefulness_rating": 4,
+    "reliability_rating": 3,
+    "auth_friction_rating": 2,
+    "docs_accuracy_rating": 3,
+    "prompt_injection_risk": "medium",
+    "summary": "Worked for small test payment, but token refresh was unreliable."
+  },
+  "evidence": {
+    "trace_hash": null,
+    "artifact_hashes": [],
+    "attestation": null
+  }
+}
+```
+
+## Optional local validation
+
+Skill-only installs can validate a remembrance payload before submission with
+the portable Node script:
+
+```sh
+node scripts/validate-remembrance.mjs payload.json
+```
+
+## Offline fallback
+
+Distinguish an API failure from a host privacy or tenant-policy denial. A host
+denial happens before Remembrance receives a request. Never retry the same
+private content through curl, a browser, another MCP transport, or an indirect
+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
+   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
+   handoff file and makes no network request.
+3. Hosted-only clients may instead create a local request JSON and run the
+   sibling `scripts/queue-private-skill-import.mjs` helper. Resolve the script
+   relative to this `SKILL.md`; pass the request with `--input`. The helper
+   writes under `.remembrance/outbox/`, creates a protective `.gitignore`, and
+   never contacts Remembrance.
+4. Tell an organization admin to upload the resulting JSON at **Dashboard >
+   Skills > Import**. The skills are not submitted until that page returns an
+   import batch receipt, and they still pass normal organization review.
+
+Local request shape (up to 10 skills):
+
+Replace `<current_runtime>` with the active host's handoff runtime from the
+central Remembrance agent-host registry. Use `other` only when the host has no
+named runtime.
+
+```json
+{
+  "source_runtime": "<current_runtime>",
+  "handoff_reason": "host_policy_blocked",
+  "skills": [
+    {
+      "slug": "example-workflow",
+      "name": "Example workflow",
+      "summary": "What this reusable workflow does.",
+      "skill_md": "# Example workflow\n\nReviewed reusable instructions."
+    }
+  ]
+}
+```
+
+If the API is merely unavailable and no private organization skill bundle is
+appropriate, produce the redacted JSON payload that would have been submitted
+and clearly label it `REMEMBRANCE_SUBMISSION_PAYLOAD` so the user or another
+approved environment can submit it later.
+
+If MCP tools are unavailable but network access works, use the machine-readable
+contract at `https://remembrance.dev/llms.txt` or the API docs at
+`https://remembrance.dev/docs/api`.
+
+Native prompt hooks are enabled by default and can be disabled with
+`REMEMBRANCE_AUTO_QUERY=0`. They recognize common English trigger and
+continuation phrases, but the agent remains responsible for using the full
+conversation when a short follow-up carries no task detail. Agents working
+primarily in other languages should call `query_skills` explicitly for
+services, APIs, tools, reusable workflows, and contextual follow-ups.
+
+## Privacy and safety
+
+- Redact secrets, credentials, personal data, private URLs, and proprietary task details unless explicitly allowed.
+- Do not submit raw traces that contain sensitive content.
+- Do not recommend skill mutations based only on one weak signal.
+- Flag prompt-injection, unsafe permissions, broken auth, misleading docs, or payment/resource anomalies.