@remembrance-ai/opencode-plugin 0.1.53 → 0.1.60

package/skills/remembrancer/SKILL.md

@@ -13,10 +13,13 @@ 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 `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 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
+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 and is reused as the installation
+principal; an invalid identity requires explicit restore or rotation. Local MCP
+and native plugins obtain a revocable 24-hour principal session in the
+background and register a privacy-bounded runtime profile. They never transmit
+the hostname, username, config path, or repository path. 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
@@ -116,13 +119,30 @@ Do not use this skill when:
    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.
+5. Apply any returned `effective_preferences` through the sibling
+   `preference_application`. A preference may steer among already-relevant
+   skills inside the same match tier or surgically alter a discretionary
+   presentation, workflow, or strategy choice. It never changes the underlying
+   relevance evidence, tier, or applicability. Required organization guidance
+   is authoritative; an explicit task or opaque project-context preference
+   outranks personal and skill defaults only when it does not conflict with that
+   guidance. Preserve safety, authorization, privacy, applicability, required
+   skill steps, validation, and review. When the user states a durable working
+   preference, call `record_preference`: built-ins need key/value; another
+   preference needs a stable `<effect>.<concept>` key, stable value, short label,
+   normalized behavior, `presentation|workflow|strategy_selection` effect,
+   `prefer|avoid` strength, and definition version. Use `scope: "auto"` unless
+   the user explicitly limited it to a project, skill, or domain. Send only
+   redacted hashes, never raw prompt or feedback text. A missing principal
+   session means personal preferences are unavailable, not that the query
+   failed.
+6. 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.
+7. 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 evidence candidate; do not submit a duplicate suggestion. Direct selections use post-use feedback only and are excluded from query-fit and reranker training.
+8. 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.
+9. 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.
+10. If no suitable skill exists and you create a reusable method, submit it through the same explicit private-versus-public boundary.
+11. If you discover a reusable API, MPP endpoint, MCP server, docs site, package, dataset, service, or tool, submit it as a resource.
+12. If a skill or resource seems duplicated, stale, unsafe, or incomplete, submit evidence or a suggestion. You may include an advisory `routing_hint`, but do not decide or promise whether Remembrance will amend, specialize, fork, or create a skill.
 
 ## Token savings and value proof
 
@@ -160,30 +180,34 @@ 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.
+## Submit evidence; Remembrance chooses the topology
+
+Do not force yourself to decide whether a lesson should amend, specialize,
+fork, or create a skill. Submit immutable evidence with the stable conditions
+that made it true. An optional `routing_hint` is useful context but is never
+authoritative.
+
+Remembrance independently classifies the evidence after static safety,
+duplicate search, target existence, risk, verifier, and organization-policy
+checks:
+
+- a universal correction or reusable detail can **amend** the target;
+- a stable runtime, version, platform, framework, scale, or task-stage
+  condition can become a scoped **specialization**;
+- a genuinely different approach can become a **strategy fork**;
+- a distinct reusable job can become an **independent skill**;
+- a subjective but reusable presentation, workflow, or strategy choice becomes
+  a typed **preference** rather than canonical instructions;
+- a one-off incident or insufficient pattern remains **evidence only**; and
+- uncertainty, missing targets, or safety concerns **hold** for review.
+
+Missing or malformed topology output never mutates a skill. Organization
+evidence can create only private organization artifacts. A specialization is a
+complete reviewed version pinned to the exact parent version with structured
+conditions and readable `use_when`/`avoid_when`; later parent changes produce a
+reviewed compatibility/rebase candidate rather than silently rewriting it. See
+`references/identity-preferences-topology.md` for identity, preference, and
+lineage details.
 
 ## Specialized skills
 
@@ -201,7 +225,7 @@ workflow at `references/<slug>.md`.
    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`.
+   `attestation-rest.md`, and `identity-preferences-topology.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
@@ -381,9 +405,10 @@ 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.
+evidence candidate from the recent pattern and queued it for topology routing,
+normal verification, quality gates, versioning, and admin/enterprise review.
+Treat it as a receipt; it does not mean the live skill changed or predetermine
+whether the result will amend, specialize, fork, create, or remain evidence.
 
 `suggested_update` on a remembrance is honored: when the remembrance itself is
 accepted, Remembrance promotes it into a reviewed suggestion (`amend_skill`,

package/skills/remembrancer/references/attestation-rest.md

@@ -45,11 +45,22 @@ If this file is lost, rerun this REST bootstrap recipe. The new key starts a new
 TOFU subject trust history; the previous verified-tier history is not
 recoverable without the old private key.
 
-## Key registration signing payload v1
+## Key registration signing payload v2
 
-Register a TOFU public key with:
+First fetch the opaque owner binding with the same credential that will own the
+installation, then register the TOFU public key:
 
-`POST https://remembrance.dev/api/v1/agent/keys/register`
+```text
+GET  https://remembrance.dev/api/v1/agent/keys/register
+POST https://remembrance.dev/api/v1/agent/keys/register
+```
+
+The GET response is private and non-cacheable. Include its `owner_binding` in
+both the canonical payload and `proof`. This prevents an anonymous registration
+signature from being replayed to claim the installation for an organization.
+Legacy v1 signatures remain valid only for anonymous registration and an
+already-owned same-scope key; new organization claims and anonymous-to-org
+upgrades require v2.
 
 If `key_id` is omitted, compute:
 
@@ -65,10 +76,11 @@ Sign this canonical object:
 
 ```json
 {
-  "version": "v1",
+  "version": "v2",
   "purpose": "remembrance-agent-key-registration",
   "provider": "other",
   "key_id": "tofu_...",
+  "owner_binding": "areg_...",
   "public_key_hash": "sha256:<hex>",
   "subject": "claude:local-install-stable-id",
   "signed_at": "2026-05-06T12:00:00.000Z"
@@ -85,6 +97,7 @@ Submit:
   "subject": "claude:local-install-stable-id",
   "proof": {
     "algorithm": "ed25519",
+    "owner_binding": "areg_...",
     "signed_at": "2026-05-06T12:00:00.000Z",
     "signature": "base64url-ed25519-signature"
   },
@@ -291,6 +304,23 @@ async function post(path, body, idempotencyKey) {
   return parsed;
 }
 
+async function get(path) {
+  const response = await fetch(`${api}${path}`, {
+    headers: {
+      ...(process.env.REMEMBRANCE_API_KEY
+        ? { "x-remembrance-api-key": process.env.REMEMBRANCE_API_KEY }
+        : {}),
+    },
+  });
+  const parsed = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new Error(
+      `${path} failed with ${response.status}: ${JSON.stringify(parsed)}`,
+    );
+  }
+  return parsed;
+}
+
 async function readOrCreateIdentity() {
   if (existsSync(keyPath)) {
     return JSON.parse(await readFile(keyPath, "utf8"));
@@ -315,12 +345,19 @@ async function readOrCreateIdentity() {
 }
 
 const identity = await readOrCreateIdentity();
+const { owner_binding: ownerBinding } = await get(
+  "/api/v1/agent/keys/register",
+);
+if (!/^areg_[A-Za-z0-9_-]{24,120}$/.test(String(ownerBinding ?? ""))) {
+  throw new Error("Remembrance returned an invalid registration binding");
+}
 const signedAt = new Date().toISOString();
 const registrationPayload = canonicalJson({
-  version: "v1",
+  version: "v2",
   purpose: "remembrance-agent-key-registration",
   provider: identity.provider,
   key_id: identity.key_id,
+  owner_binding: ownerBinding,
   public_key_hash: hashValue(identity.public_key),
   subject: identity.subject,
   signed_at: signedAt,
@@ -332,6 +369,7 @@ await post("/api/v1/agent/keys/register", {
   subject: identity.subject,
   proof: {
     algorithm: "ed25519",
+    owner_binding: ownerBinding,
     signed_at: signedAt,
     signature: signBase64Url(identity.private_key, registrationPayload),
   },

package/skills/remembrancer/references/identity-preferences-topology.md

@@ -0,0 +1,221 @@
+# Installation identity, preferences, and skill topology
+
+Use this reference when an organization shares one API key across engineers or
+agent surfaces, when an agent needs to record a durable presentation
+preference, or when evidence may be too specific to amend a general skill.
+
+## Identity model
+
+The organization API key establishes the tenant and allowed API operations. It
+does not identify a person or an individual runtime. `agent_id` remains
+descriptive metadata and never establishes identity.
+
+Local plugins and stdio MCP use the existing Ed25519 TOFU key as one stable
+**installation principal** per OS/config profile. Registration happens
+automatically and is retried without blocking query or invocation. The local
+client signs a one-time challenge at:
+
+```text
+POST /api/v1/agent/principal-sessions
+```
+
+The exchange returns an opaque, revocable 24-hour token sent as:
+
+```text
+X-Remembrance-Principal-Session: psess_...
+```
+
+`POST /api/v1/agent/economics/session` and
+`X-Remembrance-Economics-Session` remain backward-compatible aliases. Query
+and explicit skill invocation ignore unusable or expired session context and
+continue under the already established API-key or anonymous scope; identity,
+member-link, and preference mutations reject that context.
+An organization-owned principal session is an identity supplement, not a
+tenant credential: every request using it must also send a valid API key for
+the same organization. Without that key, retrieval drops the session and
+continues anonymously; identity and preference mutations reject it.
+Send one session header. If a legacy client sends both, the principal-session
+header takes precedence.
+
+Each installation may have child **runtime profiles** for Codex Desktop, Codex
+CLI, Claude Code, Cursor, OpenClaw, VS Code, OpenCode, raw MCP, or another
+surface. A profile sends only normalized runtime/surface labels, bounded
+versions, and a locally derived opaque profile key. Never send hostnames,
+usernames, config paths, repository paths, or project names. Runtime profiles
+and ephemeral subagents inherit the installation billing principal and do not
+consume additional agent slots.
+
+## Optional member link
+
+An unlinked installation is fully functional and may keep installation-local
+preferences. To let preferences follow an engineer across machines and
+runtimes, use **Dashboard > Agents > Instances > Install on this device**. That
+flow creates a single-use token that expires after ten minutes. The token may be
+included in the principal-session challenge or consumed with the MCP tool
+`link_current_installation` / REST endpoint:
+
+```text
+POST /api/v1/agent/member-links
+```
+
+Reusable organization-key distribution commands must never include a member
+token. Linking does not rotate the organization key or create another billed
+agent. Members can rename their linked installations; organization admins can
+assign, reassign, activate, or deactivate installations and label child runtime
+profiles independently. Automatic runtime check-ins preserve custom profile
+labels. Agent responses never contain member email addresses, Clerk IDs, or
+internal organization IDs.
+
+## Preference contract
+
+Preferences are bounded organization-local working choices, not edits to
+canonical skill instructions. These built-in controls are convenient presets,
+not a closed vocabulary:
+
+- `comment_density`: `sparse`, `balanced`, `detailed`
+- `comment_focus`: `intent_only`, `tricky_logic`, `api_contracts`,
+  `comprehensive`
+- `explanation_depth`: `concise`, `balanced`, `detailed`
+- `output_organization`: `compact`, `structured`, `step_by_step`
+
+Use `get_effective_preferences` or
+`POST /api/v1/agent/preferences/effective` to resolve task-relevant values.
+Normal query and invocation responses also include
+`preference_definition_version`, `effective_preferences`, and, for a selected
+skill, `preference_application`. Extensible settings use a stable dotted key,
+stable value, short label, concise normalized behavior, effect
+(`presentation`, `workflow`, or `strategy_selection`), direction (`prefer` or
+`avoid`), and definition version. Native hooks record recognized built-ins
+silently. For another explicit durable preference, the hook asks the agent to
+call `record_preference` with opaque hashes and `scope: "auto"`; the server binds
+it to the linked member when present and otherwise to the installation.
+
+Resolution order is:
+
+1. universal safety, authorization, privacy, applicability, required skill
+   steps, validation, and review requirements (hard constraints, not
+   preferences);
+2. required organization guidance;
+3. the current explicit task instruction;
+4. an explicit project-context preference;
+5. explicit member + runtime profile;
+6. explicit member;
+7. learned member + runtime profile;
+8. learned member;
+9. explicit installation fallback;
+10. learned installation;
+11. recommended organization guidance;
+12. declared skill default.
+
+Organization admins choose Required or Recommended under \*\*Dashboard > Agents
+
+> Preferences\*\*. Required applies to every organization agent. Recommended is a
+> default that a clear task or personal preference may replace. The API field
+> `project_key` is an opaque local project-context hash, not an administrator
+> policy scope.
+
+Use `record_preference` or `POST /api/v1/agent/preferences` only for an
+built-in or complete bounded extensible setting. Submit an `evidence_hash`,
+`task_hash`, scope, and confidence. Never upload the raw prompt, feedback text,
+source path, or private task content.
+
+Relevance and preference influence remain separate. The normal ranker first
+establishes applicability and the stable `high`, `possible`, or `exploratory`
+tier. Declared skill preference traits can then reorder candidates only inside
+the same tier. The response reports qualitative matched/conflicted traits plus
+`relevance_rank` and `personalized_rank`; it never exposes the internal bounded
+adjustment. A single selected skill still receives a surgical preference
+sidecar for discretionary behavior. A locked skill requirement blocks an
+incompatible personal preference. A locked conflict with Required organization
+guidance makes the skill ineligible. No preference weakens a hard constraint.
+
+- An explicit durable user correction applies immediately.
+- Inferred member or installation values require at least three consistent
+  observations across two tasks and two days with confidence at least `0.85`.
+- A learned member + runtime residual requires four observations across three
+  tasks with confidence at least `0.85`.
+- Learned values stop applying after 180 inactive days.
+- Explicit values persist until changed.
+- Each activation creates a reversible profile revision; the dashboard supports
+  undo and reset.
+
+## Evidence topology
+
+The agent's job is to submit accurate, privacy-safe evidence. It does not need
+to decide the final skill graph operation. `routing_hint` is optional and
+non-authoritative:
+
+```json
+{
+  "routing_hint": {
+    "suggested_action": "specialize",
+    "conditions": [
+      {
+        "dimension": "runtime_version",
+        "operator": "at_least",
+        "value": "2.0"
+      }
+    ]
+  }
+}
+```
+
+Remembrance runs static safety, duplicate search, target existence, risk,
+verifier, and review-policy guards before selecting one route:
+
+- `amend`: a universal correction or reusable detail for an existing skill;
+- `specialize`: guidance that is valid under stable environment/task
+  conditions;
+- `strategy_fork`: a genuinely different approach to the same job;
+- `independent_skill`: a distinct reusable job;
+- `preference`: a subjective but reusable presentation, workflow, or strategy
+  choice represented by a typed preference;
+- `evidence_only`: a one-off incident or pattern that is not ready to shape a
+  skill; or
+- `hold`: uncertainty, missing target, low confidence, or a safety/review gate.
+
+Missing or malformed model topology output falls back to evidence-only or human
+review. It never authorizes an automatic mutation. Organization evidence can
+route only to private organization artifacts; public evidence follows the
+public review pipeline. The public classifier learns only from global-admin
+corrections, while each organization's adapter learns only from that
+organization's admins.
+
+## Specialization lineage and rebase
+
+A specialization is not a patch fragment. It is a complete reviewed version
+with:
+
+- `specialized_from` lineage;
+- the exact parent version used during review;
+- structured scope predicates;
+- readable `use_when` and `avoid_when` guidance; and
+- normal safety, quality, version, and rollback records.
+
+When the parent advances, Remembrance creates a reviewed compatibility/rebase
+candidate. It does not silently rewrite the child. Review cards state the
+proposed operation, exact target or parent, stable conditions, consequence, and
+either the complete new/specialized skill or the exact existing-skill diff.
+
+Operators may temporarily disable preference recording/application with
+`AGENT_PREFERENCES_ENABLED=false` or learned topology routing with
+`SKILL_TOPOLOGY_AUTOMATION_ENABLED=false`. Query and invocation continue; the
+latter control leaves the existing verified review/materialization path in
+place.
+
+## Dashboard and APIs
+
+- **Dashboard > Agents > Instances** lists privacy-safe installation/runtime
+  inventory and member assignments.
+- **Dashboard > Agents > Preferences** lists effective values, confidence,
+  provenance, revisions, undo, and reset.
+- **Dashboard > Verification > Topology** shows proposed routes, targets,
+  stable conditions, classifier versions, and reviewer overrides.
+- `GET/PATCH /api/v1/enterprise/agent-instances` manages visible instances.
+- `POST /api/v1/enterprise/agent-member-link` creates a one-time member token.
+- `GET/PATCH /api/v1/enterprise/agent-preferences` manages dashboard preference
+  revisions.
+
+Hosted MCP cannot read a local TOFU key or invent a human identity. Without a
+client-held principal session it remains organization-level, while normal
+query/invocation behavior continues.

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

@@ -35,12 +35,15 @@
 
 Legacy `attestation_token_hash` is no longer accepted. Verified trust uses `POST /api/v1/agent/attest/challenge` followed by a plugin-signed `evidence.attestation` object.
 
-`suggested_update` is honored when the remembrance itself is ACCEPTED: the
-update is promoted 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 live skill changes only
-after review. `score_adjustment` is ignored (scoring is deterministic); use
-`kind: "none"` when no change is proposed.
+`suggested_update` describes a requested content operation; it does not decide
+the final skill topology. When the remembrance itself is accepted, Remembrance
+creates reviewable evidence through the normal verification pipeline. The
+topology router may amend the target, create a scoped specialization, create a
+strategy fork or independent skill, record a typed preference, retain evidence
+without mutation, or hold for review. The live skill changes only after the
+selected route clears its safety, quality, target, policy, and version guards.
+`score_adjustment` is ignored (scoring is deterministic); use `kind: "none"`
+when no content operation is proposed.
 
 Provider fields are intentionally split:
 
@@ -180,7 +183,8 @@ not discard valid post-use feedback or alter ranking by itself.
 
 The same response may also include `feedback_pattern_suggestion` when repeated
 substantive feedback for the same skill crosses the configured synthesis
-threshold. This is a reviewable candidate update, not a live mutation:
+threshold. This is a reviewable evidence candidate for topology routing, not a
+predetermined metadata update or a live mutation:
 
 ```json
 {
@@ -199,7 +203,8 @@ threshold. This is a reviewable candidate update, not a live mutation:
 ```
 
 Do not submit a duplicate suggestion for the same pattern. Wait for the
-verification/review/versioning result before assuming the active skill changed.
+topology, verification, review, and versioning result before assuming the
+active skill changed.
 
 Local identity recovery: the persisted key file
 `~/.config/remembrance/agent-key.json` is a private key. Back it up like an
@@ -263,11 +268,13 @@ privately, then let an organization admin use the reviewed public-propagation
 flow for a redacted, public-safe version when appropriate.
 
 If host policy blocks repository-derived content before the request reaches
-Remembrance, do not retry it through another network transport. Use local MCP
+Remembrance, do not retry it through another network transport. Report the fixed
+content-free denial alert and do not create a handoff automatically. Only when
+an organization admin explicitly requests one, use local MCP
 `queue_private_skill_import` or the bundled
-`scripts/queue-private-skill-import.mjs` helper, then have an organization admin
-upload the mode-0600 JSON at **Dashboard > Skills > Import**. A local handoff is
-not a server submission receipt.
+`scripts/queue-private-skill-import.mjs` helper, then have the admin upload the
+mode-0600 JSON at **Dashboard > Skills > Import**. A local handoff is not a
+server submission receipt.
 
 ## New skill idea