@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.renderer.typed.md

@@ -0,0 +1,92 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.renderer.typed"
+name: "Typed renderers"
+user_promise: "Compatible renderers present typed Content values consistently across surfaces while preserving meaning, accessibility, inheritance, and export fallback."
+primary_user_job: "Choose or inherit a useful presentation for a typed value and still understand or export it when the preferred visual renderer is unavailable."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.typed"]
+related_features:
+  [
+    "content.feature.see-your-information-your-way",
+    "content.feature.build-new-surfaces",
+    "content.feature.understand-what-your-data-says",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Typed Renderers provide a registry that validates compatible presentations for typed values, resolves inherited choices predictably, and supplies accessible and export-safe fallbacks without changing query or relationship semantics."
+proof_requirements:
+  [
+    "Typed renderer registry, compatibility checks, registration failure behavior, and stable renderer identity",
+    "Inheritance and local override resolution across property, View, Block, embed, and output contexts",
+    "Accessible semantic presentation, keyboard behavior, text alternatives, and degraded-runtime fallback",
+    "Portable export, SSR or static output, unavailable-renderer behavior, and preservation of canonical typed values",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Typed renderers
+
+## Why this exists
+
+The same typed value may be useful as text, a badge, a date, a chart mark, a map point, or an accessible export summary. Without a shared compatibility and fallback contract, each surface invents a display rule and eventually treats a renderer failure as missing data. Typed Renderers make presentation reusable while leaving the underlying value and its meaning intact.
+
+## Example workflow
+
+A workspace uses a status renderer for a typed status Property in a table, card, and embedded record. A saved View locally overrides the renderer for a compact display without changing the Property’s value or other Views. When the record is exported to a static format where that renderer cannot run, Content emits a compatible text representation and accessible label. An incompatible renderer selection is rejected before it can produce a misleading display.
+
+## Product contract
+
+- A renderer has a stable identity, declared accepted typed inputs, presentation capabilities, semantic text alternative, and supported interactive, static, and export behaviors.
+- The registry accepts only compatible renderer/value pairings. An unsupported or unavailable renderer returns a typed failure or compatible fallback; it never silently converts a value to empty content.
+- Renderer selection resolves through explicit local override and inherited defaults. A View, Block, embed, or export context may choose a compatible presentation without mutating the canonical Property definition or typed value.
+- Renderers present values; they do not own query evaluation, aggregation, relationship traversal, access decisions, or source synchronization. Those inputs arrive already authorized and typed.
+- Every interactive renderer has keyboard and assistive-technology behavior appropriate to its semantic role. Every nontextual presentation provides a meaningful text alternative or accessible equivalent.
+- Public, SSR, static, and export contexts use a compatible renderer or declared fallback from the same typed value. A rendering runtime failure is visible as a failure state where no safe fallback exists.
+- Custom and built-in renderers use the same registry contract; registration does not create a second Action surface or grant access to values.
+
+## Boundaries and non-goals
+
+- `content.property.typed` owns value types, validation, and canonical storage. Typed Renderers own presentation compatibility, not coercion of an invalid stored value.
+- Chart owns analytical specifications and drill-down; Graph owns relationship exploration; Canvas owns spatial arrangement. This Capability supplies their common presentation substrate only.
+- Mermaid remains an authored code renderer. Typed Renderers do not define a diagram language, query syntax, semantic edge model, or analytics engine.
+- This Capability does not make every renderer universally applicable, bypass access control, duplicate source data, or turn a visual fallback into proof that interactive behavior worked.
+
+## Acceptance stories
+
+### Reject incompatible presentation honestly
+
+Given a renderer that accepts numeric measures and a text Property, when a person selects that renderer, then Content rejects the incompatible pairing with repair guidance and preserves the existing typed value and renderer choice.
+
+### Inherit without rewriting the source
+
+Given a Property default renderer and a saved View with a compatible local override, when the View is rendered beside another View, then each uses its resolved presentation while both retain the same canonical value and Property identity.
+
+### Keep information available when a renderer cannot run
+
+Given an export or static context where an interactive renderer is unavailable, when the value is rendered, then Content uses its declared compatible fallback with accessible text. If none exists, it shows a distinct unavailable-renderer state rather than blank content.
+
+### Preserve authorization at the input boundary
+
+Given a renderer used by a Chart, Graph, or embedded View, when the viewer lacks access to part of the input, then the renderer receives only the authorized typed result and cannot expose omitted values through labels, summaries, or fallback output.
+
+## Current evidence
+
+The repository already identifies typed properties and several presentation surfaces, and individual renderer implementations may be reusable donor substrate. No evidence currently proves one registry, cross-surface inheritance, accessible degradation, export behavior, and failure handling as an atomic capability. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Register built-in and custom renderer fixtures, validate accepted input types and capabilities, and verify incompatible, missing, and runtime-failure states.
+2. Resolve defaults and overrides across Properties, Views, Blocks, embeds, dashboards, and export contexts without mutating canonical values.
+3. Test interactive keyboard behavior, semantic roles, accessible names, text alternatives, reduced-capability modes, and assistive-technology reading paths.
+4. Render compatible static, SSR, and export outputs; verify declared fallbacks and distinct unavailable states when no fallback exists.
+5. Exercise Charts, Graphs, Canvas, and ordinary Properties with access changes to prove renderers cannot widen their typed authorized input.
+
+## Open questions
+
+Registry storage, extension packaging, renderer sandboxing, and the exact inheritance precedence are implementation choices. They must retain stable renderer identity, explicit compatibility, accessible fallback, and the separation from query and relationship semantics.

package/corpus/templates/content/docs/product/capabilities/content.research.annotation.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.research.annotation"
+name: "Annotations"
+user_promise: "Highlights, excerpts, and research notes remain anchored to the exact material and revision they interpret."
+primary_user_job: "Mark a precise passage or moment, add meaning, and find it later without pretending an edited source is unchanged."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.reference", "content.version.field-history"]
+related_features:
+  [
+    "content.feature.explore-alternatives-safely",
+    "content.feature.read-and-annotate-anything",
+    "content.feature.sketch-connections-keep-whats-true",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Annotations are durable anchored contributions with purpose distinct from comments, stable text/page/region/time selectors, source representation and named Version/revision context, explicit visibility, relocation and orphan states, and searchable projections."
+proof_requirements:
+  [
+    "Selector, revision/version, visibility, persistence, and anchored-contribution data tests",
+    "Edit relocation, orphan repair, parallel-version, source-adapter, export, and access tests",
+    "Reader and annotation-rail workflow with search, filtering, re-anchor, and shared/private scope",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Annotations
+
+## Why this exists
+
+An annotation is evidence of attention, not a comment that happens to sit near a sentence.
+
+## Example workflow
+
+A researcher highlights a paragraph on a named Version, writes a private note, later searches the Annotation rail, and chooses whether to carry a repaired anchor to a new Version.
+
+## Product contract
+
+- Annotations share an anchored-contribution substrate with Comments and revision notes but retain their own purpose and lifecycle.
+- Each records source representation, selector, named Version and exact revision context where available, author, scope, and provenance.
+- Quiet in-content marks open to a searchable, filterable Annotation rail; annotations can project to Databases and Canvas without becoming copies.
+- Ordinary edits attempt relocation. Unresolved anchors are explicit orphan/repair states; parallel Versions never silently merge annotation meaning.
+
+## Boundaries and non-goals
+
+Reader owns reading interaction; citations own formal source references; comments own feedback threads. An Annotation is not automatically public, shared, or portable to an incompatible source.
+
+## Acceptance stories
+
+### Preserve an exact revision anchor
+
+Given a highlight on a named Page Version, when that Page later changes, then the Annotation retains its original revision context and either relocates with evidence or appears as needing repair.
+
+### Respect private scope
+
+Given a private Annotation on a shared Page, when another collaborator opens the Page or an aggregate, then the Annotation and any derived count are not exposed.
+
+## Current evidence
+
+Donor evidence: anchored Comments and revision history provide related primitives. No durable Annotation object, rail, revision-aware selector, or carry-forward proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define anchored contribution and multimodal selector models.
+2. Test scope, edits, orphaning, re-anchor, parallel Versions, exports, and access-safe projections.
+3. Verify Reader highlight-to-rail-to-repair workflow.
+
+## Open questions
+
+- Automatic relocation confidence thresholds and batch carry-forward UI remain open.

package/corpus/templates/content/docs/product/capabilities/content.research.citation.md

@@ -0,0 +1,70 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.research.citation"
+name: "Citations"
+user_promise: "A citation retains a durable source-and-locator identity even when its style or surrounding document changes."
+primary_user_job: "Cite exact evidence once and render it as a link, footnote, number, author-date reference, or bibliography without re-entering the source."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.reference", "content.knowledge.links"]
+related_features: ["content.feature.cite-what-you-found"]
+roadmap_boundary: "feature"
+acceptance_summary: "A semantic citation references a stable source record plus optional page, section, figure, timestamp, transcript, or range locator; rendering styles and bibliographies derive from that identity while access and round-trip behavior remain explicit."
+proof_requirements:
+  [
+    "Citation identity, locator, promotion, style, bibliography, and round-trip tests",
+    "Access, missing-source, locator-validation, import/export, and renderer-separation tests",
+    "Writer workflow promoting a link, changing style, and verifying bibliography output",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Citations
+
+## Why this exists
+
+A footnote is a costume; the citation is the durable relationship underneath it.
+
+## Example workflow
+
+A writer promotes a research link, adds a page locator, switches from author-date to footnotes, and sees a bibliography recompute from the same cited source identity.
+
+## Product contract
+
+- Citation identity points to a durable source record and optional precise locator: page, chapter, section, figure, timestamp, transcript range, or text range.
+- An ordinary link can be promoted without losing its original anchor. The citation remains separate from its renderer and bibliography placement.
+- Styles may render linked blog, numeric, author-date, footnote, and bibliography forms, including CSL-compatible behavior where supported.
+- Access is checked when source details render or export; missing or inaccessible data is represented honestly rather than fabricated.
+
+## Boundaries and non-goals
+
+Annotations record interpretation; references link Content objects; this record owns formal citation identity. It does not promise to maintain every bibliography style by hand.
+
+## Acceptance stories
+
+### Change style without changing evidence
+
+Given a document with semantic citations, when the writer changes its style from author-date to footnotes, then the cited source identities and locators remain unchanged while rendered references and bibliography update.
+
+### Preserve a locator through export
+
+Given a citation to a video timestamp, when the document exports to a supported format, then the source identity and timestamp survive or the conversion report identifies the fidelity limit.
+
+## Current evidence
+
+Donor evidence: ordinary links, references, source metadata, rich text, and export machinery can support citation work. No first-class citation object, locator, bibliography, or end-to-end rendering proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define citation/source/locator identity and link-promotion behavior.
+2. Test styles, bibliography, access, imports, exports, and unavailable sources.
+3. Verify writer promotion and style-switch workflow in the editor and public/export renderers.
+
+## Open questions
+
+- The initial CSL engine and Zotero interchange scope remain open.

package/corpus/templates/content/docs/product/capabilities/content.review.code.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.review.code"
+name: "Code review"
+user_promise: "Review typed code and file changes in the same in-place, filterable, durable-decision interface"
+primary_user_job: "Review a portable code change in context and leave decisions attached to stable files and hunks."
+kind: "primitive"
+state: "exploring"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.diff.in-place", "content.author.code"]
+related_features: ["content.feature.review-changes-in-place"]
+roadmap_boundary: "feature"
+acceptance_summary: "Code review uses a portable file/source model, typed change graph, syntax-aware renderers, authority checks, durable in-place decisions, and canonical source provenance."
+proof_requirements:
+  [
+    "Typed contract, authorization, validation, Event/history, and recovery coverage",
+    "Cross-surface UI, Action, agent-context, reload, and failure-state coverage",
+    "Real-interface keyboard and assistive-technology workflow coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Code review
+
+## Why this exists
+
+Review decisions need durable anchors that survive refreshes without claiming custody of the underlying repository.
+
+## Example workflow
+
+A reviewer opens a proposed file change, filters to unresolved hunks, leaves an in-place decision, and later reopens the same decision after the source refreshes.
+
+## Product contract
+
+Code review uses a portable file/source model, typed change graph, syntax-aware renderers, authority checks, durable in-place decisions, and canonical source provenance. AI summaries are enhancing work, not a prerequisite claim.
+
+## Boundaries and non-goals
+
+In-place diffs and code authoring own their primitives. This is not a Git-host replacement, provider custody claim, or auto-merge authority.
+
+## Acceptance stories
+
+### Reattach a decision after an unrelated refresh
+
+Given a source refresh changes unrelated lines, when a reviewer reopens a decision, then its stable change anchor either resolves or reports a truthful orphaned state.
+
+### Report an orphaned hunk truthfully
+
+Given a viewer lacking file access, when they open a review, then no code, hunk count, or summary leaks through filters or review metadata.
+
+## Current evidence
+
+This remains `exploring`; no complete portable-source, syntax, authority, and durable-decision proof is recorded.
+
+## Proof plan
+
+1. Test portable file identities, change graphs, syntax rendering, filters, and anchors.
+2. Verify decisions, authority, provenance, refresh reconciliation, and inaccessible files.
+3. Exercise orphaned hunks, unavailable sources, keyboard review, and diff navigation.
+
+## Open questions
+
+The initial portable file identity and change-anchor strategy remain exploratory.

package/corpus/templates/content/docs/product/capabilities/content.revision.suggestions.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.revision.suggestions"
+name: "Suggestions"
+user_promise: "Suggested changes remain authored pending Revisions until an authorized person accepts, rejects, defers, or supersedes them."
+primary_user_job: "Propose reversible human or agent work without mutating the canonical Page before review."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.diff.in-place", "content.history.queryable"]
+related_features: ["content.feature.review-changes-in-place"]
+roadmap_boundary: "feature"
+acceptance_summary: "Suggestions preserve authored pending Revision identity, target/basis, scope, permissions, conflict state, and durable disposition through in-place review and History."
+proof_requirements:
+  [
+    "Pending Revision identity with actor, time, origin, target, basis, and change set",
+    "In-place typed review and Event/History disposition",
+    "Permission, author edit window, stale basis, and conflict behavior",
+    "Human/agent parity, concurrent review, recovery, and notification coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Suggestions
+
+## Why this exists
+
+People and agents need room to offer work before it becomes canonical. A suggestion is a real authored proposal, not an ephemeral chat message or a secret second document.
+
+## Example workflow
+
+An agent proposes edits to an article and its metadata. The proposal remains pending as one authored Revision. The editor accepts stronger passages, rejects an incorrect Property change, leaves another suggestion pending, and can later see every decision in History.
+
+## Product contract
+
+- A Suggestion is a pending logical Revision with stable identity, author, authority/origin, time, targets, observed basis, typed change set, and disposition.
+- Human and agent suggestions use one model; neither receives a private document or review path.
+- Pending suggestions do not mutate canonical target state until authorized acceptance.
+- Author editing follows an explicit time/permission policy and preserves visible history rather than erasing the proposal.
+- Acceptance, rejection, deferment, supersession, conflict, and expiry are durable Events/History states.
+- A stale target exposes rebase, refresh, or conflict behavior; it never silently applies to a moved target.
+
+## Boundaries and non-goals
+
+- Suggestions are not every Event, snapshot, or named Page Version.
+- This record does not define filtered-set review or AI summaries.
+- A pending suggestion does not widen access to its target or its underlying evidence.
+
+## Acceptance stories
+
+### Keep a proposal pending until review
+
+Given an agent proposes a Block and Property change, when the proposal is created, then the canonical Page is unchanged and the editor can inspect one attributable pending Revision in place.
+
+### Handle a moved target without overwrite
+
+Given an editor changes a target after a suggestion's observed basis, when another reviewer accepts the suggestion, then Content presents a rebase, refresh, or conflict state and does not silently overwrite the newer canonical change.
+
+## Current evidence
+
+Current document snapshots and source-review machinery provide useful proposed-change donors. The repository does not yet prove generic authored pending Revisions, typed suggestion review, or conflict semantics across Content; this remains `approved_shape`.
+
+## Proof plan
+
+1. Create, edit, submit, accept, reject, defer, supersede, and expire human and agent suggestions.
+2. Test author windows, target permissions, access changes, Notifications, History, and recovery.
+3. Race concurrent author edits, reviewer decisions, target edits, and retries.
+4. Verify typed body/Property/Block rendering through UI and shared Actions.
+
+## Open questions
+
+The exact author edit window and rebase UX remain open. Pending identity, durable disposition, and no-silent-overwrite behavior are settled.

package/corpus/templates/content/docs/product/capabilities/content.rule.deterministic.md

@@ -0,0 +1,79 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.rule.deterministic"
+name: "Rules"
+user_promise: "Event plus typed condition plus action"
+primary_user_job: "Define repeatable operational behavior that is explicit, authorized, idempotent, and explainable."
+kind: "workflow"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.event.committed",
+    "content.expression.language",
+    "content.agent.action-parity",
+  ]
+related_features:
+  [
+    "content.feature.when-this-happens-that-follows",
+    "content.feature.collect-structured-input",
+    "content.feature.capture-into-action",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Rules are versioned subscriptions from committed Events through one expression language to typed Actions."
+proof_requirements:
+  [
+    "Typed contract, authorization, validation, Event/history, and recovery coverage",
+    "Cross-surface UI, Action, agent-context, reload, and failure-state coverage",
+    "Real-interface keyboard and assistive-technology workflow coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Rules
+
+## Why this exists
+
+A Rule turns a recurring intention into a visible promise: one committed event, one typed condition, and one authorized action.
+
+A Rule makes an operational promise visible: one committed event, one typed condition, one authorized action.
+
+## Example workflow
+
+A Database update emits a committed Event, a versioned Rule evaluates a typed condition, and an Action assigns a follow-up property once. The receipt identifies the event, Rule version, authority, and outcome.
+
+## Product contract
+
+Rules are versioned subscriptions from committed Events through one expression language to typed Actions. They have owner authority, idempotency, causal receipts, disablement, retries, and visible failures.
+
+## Boundaries and non-goals
+
+Events own committed triggers, expressions own conditions, and Actions own mutations. This is not client-side scripting, hidden retries that look successful, or unrestricted recursive automation.
+
+## Acceptance stories
+
+### Record a duplicate Event delivery
+
+Given the same Event is delivered twice, when a Rule would mutate a record, then idempotency commits at most one canonical effect and records the duplicate receipt.
+
+### Surface an unevaluable condition
+
+Given a Rule condition cannot be evaluated, when its source is unavailable, then Content records an explicit failure or retry state rather than an empty successful run.
+
+## Current evidence
+
+Rule substrate is in progress, but complete subscription, idempotency, authority, receipt, and recovery proof is incomplete. This Capability remains `in_progress`.
+
+## Proof plan
+
+1. Test versioned subscriptions from committed Events through typed expressions to Actions.
+2. Simulate duplicates, false and unevaluable conditions, retries, recursion, and disablement.
+3. Inspect causal history, owner controls, failure states, reload recovery, and no-success-on-failure.
+
+## Open questions
+
+The initial retry and dead-letter policy need design.

package/corpus/templates/content/docs/product/capabilities/content.schedule.constraints.md

@@ -0,0 +1,81 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.schedule.constraints"
+name: "Schedule constraints"
+user_promise: "Planning surfaces detect dependency and date violations, explain them, and apply only explicit policy or accepted repairs."
+primary_user_job: "Understand whether a plan conflicts with its dates and dependencies, then choose a visible repair rather than accepting a hidden schedule rewrite."
+kind: "primitive"
+state: "exploring"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.relationship.edge",
+    "content.time.types",
+    "content.expression.language",
+  ]
+related_features: ["content.feature.plan-work-across-time"]
+roadmap_boundary: "feature"
+acceptance_summary: "Planning Views evaluate typed date and dependency constraints, explain violations and uncertainty, and apply only explicit policy or accepted canonical repairs."
+proof_requirements:
+  [
+    "Typed date/range and Relationship constraint evaluation, cycle, missing-data, and uncertainty coverage",
+    "Access-safe violation disclosure, repair proposal, policy, Action, history, and recovery coverage",
+    "Real-interface planning workflow for Timeline composition, unavailable inputs, reload, and assistive access",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Schedule constraints
+
+## Why this exists
+
+Planning needs honest friction: a date conflict should be explainable, not silently “fixed”
+by a renderer that decides on behalf of the work.
+
+## Example workflow
+
+A planner moves a task before a blocking task ends. Timeline identifies the violation,
+shows the dependency and dates involved, and offers a policy-backed repair only for approval.
+
+## Product contract
+
+- Constraint evaluation consumes canonical typed Relationships, dates, ranges, and expressions.
+- Planning Views distinguish violation, uncertainty, missing input, unavailable source, and no conflict.
+- A policy may propose repairs; only an explicit accepted shared Action changes canonical records.
+- Access applies before constraints, explanations, counts, previews, exports, and agent context.
+
+## Boundaries and non-goals
+
+Dependencies and time types own inputs; Timeline is a consumer. This is not automatic
+project management, a hidden date inference system, or a separate scheduler datastore.
+
+## Acceptance stories
+
+### Explain a blocking conflict
+
+Given a task scheduled before an accessible blocker completes, when a planner opens the
+planning View, then Content identifies the typed dependency and conflicting dates clearly.
+
+### Refuse a hidden repair
+
+Given a policy offers a later start date, when the planner declines it, then no canonical
+date changes; accepting it creates one attributable shared Action and history entry.
+
+## Current evidence
+
+This record remains `exploring`; no complete constraint evaluator or repair contract is
+proven by current Timeline donor code.
+
+## Proof plan
+
+1. Test dates, ranges, dependencies, cycles, missing inputs, and uncertainty.
+2. Verify access-safe explanations, explicit repair Actions, history, and recovery.
+3. Exercise planning UI, Timeline composition, unavailable sources, reload, and accessibility.
+
+## Open questions
+
+The initial constraint policy catalog and repair proposal language remain exploratory.

package/corpus/templates/content/docs/product/capabilities/content.security.private-vault.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.security.private-vault"
+name: "Private vault encryption"
+user_promise: "Private-vault custody can be user-held and fail closed without disguising unresolved recovery, collaboration, or agent authority problems."
+primary_user_job: "Keep selected work unreadable to the service while retaining understandable device, recovery, sharing, agent, and exit choices."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "desktop"
+dependencies:
+  ["content.agent.resource-consent", "content.portability.vault-export"]
+related_features: ["content.feature.keep-your-private-vault-private"]
+roadmap_boundary: "feature"
+acceptance_summary: "A reviewed private-vault system establishes user-held cryptographic custody, explicit enrollment and device authorization, fail-closed decryption and recovery, bounded agent plaintext access, revocation, collaboration semantics, and portable exit without claiming readiness before production proof."
+proof_requirements:
+  [
+    "Threat model, protocol, key lifecycle, enrollment, recovery, revocation, and fail-closed tests across supported architectures",
+    "Agent-consent, collaboration, merge, export, and unavailable-key authorization tests",
+    "Independent security review plus production-like end-to-end device, recovery, revocation, and exit evidence",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Private vault encryption
+
+## Why this exists
+
+Private custody is a promise about who can read, not a decorative lock icon.
+
+## Example workflow
+
+A person enrolls a trusted device, opens a private vault locally, grants one local agent a bounded task, revokes the device, and exports readable authorized material without exposing plaintext to the service.
+
+## Product contract
+
+- User-held cryptographic custody, key enrollment, device authorization, rotation, revocation, and recovery are explicit ceremonies with fail-closed behavior.
+- Clients decrypt only vaults and operations they are currently authorized to handle; unavailable keys never coerce to empty or apparently successful content.
+- Agent plaintext access is separate bounded consent, not an implication of ordinary sharing or recoverable edit access.
+- Collaboration, Versions, comments, access changes, and portable exit must preserve the custody claim or state their limitation plainly.
+
+## Boundaries and non-goals
+
+This is a paused product lane, not a claim that current experiments are production-ready. Vault export owns package semantics; resource consent owns agent scope.
+
+## Acceptance stories
+
+### Fail closed on an unenrolled device
+
+Given a device without the vault key, when it opens a private-vault resource, then it receives an explicit unavailable/enrollment state and no plaintext or plausible empty document.
+
+### Revoke bounded access
+
+Given a device and an agent were separately authorized, when the owner revokes their grants, then subsequent decrypt or task attempts fail and the audit record distinguishes device revocation from agent consent.
+
+## Current evidence
+
+Donor evidence: repository feature records retain the historical research and fork boundary. No repository-local audited protocol, integration, cross-architecture proof, or production receipt supports a complete claim; this record remains `in_progress` and the Feature is paused.
+
+## Proof plan
+
+1. Publish a sanitized protocol and implementation wayfinder with threat boundaries.
+2. Test key lifecycle, recovery, revocation, agent consent, collaboration, and portable exit across architectures.
+3. Obtain independent review and production-like end-to-end evidence before changing state.
+
+## Open questions
+
+- Recovery ceremony, collaboration cryptography, and supported-device order remain material decisions.