@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.history.queryable.md

@@ -0,0 +1,79 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.history.queryable"
+name: "History"
+user_promise: "History is a full-height, access-scoped surface for inspecting and recovering meaningful change."
+primary_user_job: "Find what changed, compare it in context, and recover safely without reconstructing the story from notifications."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.event.committed"]
+related_features:
+  [
+    "content.feature.durable-foundations",
+    "content.feature.review-changes-in-place",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "History queries access-scoped Events, logical Revisions, snapshots, and receipts with filters, grouping, typed diffs, and recovery routes while preserving their distinct meanings."
+proof_requirements:
+  [
+    "Access-scoped event/revision/snapshot/receipt query model",
+    "Filter, group, sort, and stable permalink behavior",
+    "Typed body and property diff plus recovery routes",
+    "UI/Action parity, denial, concurrency, and export evidence",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# History
+
+## Why this exists
+
+Collaboration needs an exhaustive place to ask what happened and recover from it. A friendly timeline can summarize, but it cannot quietly become the only evidence.
+
+## Example workflow
+
+An editor filters a Page's History to one agent run, expands its logical Revision into atomic Events, compares a changed Property and Block in their ordinary renderers, then restores only the authorized field.
+
+## Product contract
+
+- History is an access-scoped projection over committed Events, logical Revisions, recovery snapshots, and execution receipts.
+- It supports filtering, grouping, sorting, stable links, and typed comparison in the normal Page/Database renderer.
+- Events are atomic facts; Revisions are causal review units; snapshots are recovery mechanics; named Versions are deliberate alternatives. History preserves those distinctions.
+- Recovery invokes shared Actions and creates attributable new change rather than rewriting the past.
+- Inaccessible history is denial or omission according to access context, never a successful empty timeline.
+
+## Boundaries and non-goals
+
+- Discussion is a curated collaboration projection, not the exhaustive recovery authority.
+- History does not decide suggestion review disposition or Page Version promotion.
+- It does not require every low-level persistence operation to be user-visible.
+
+## Acceptance stories
+
+### Compare a causal Revision in place
+
+Given an agent Revision containing Block and Property changes, when an editor opens it in History, then they can inspect grouped Events and typed diffs in the ordinary surface without losing actor or causal context.
+
+### Recover without leaking another Version
+
+Given a person can read a Revision but lacks authority to edit a narrower Version, when they choose restore, then it is denied and the current content remains unchanged.
+
+## Current evidence
+
+Current document versions, restore actions, and editor history UI demonstrate snapshot-oriented substrate. They do not prove access-scoped Event/Revision queryability, typed diffs, or complete recovery semantics; this remains `approved_shape`.
+
+## Proof plan
+
+1. Query and compare Events, Revisions, snapshots, and receipts across Page, Database, source, and agent work.
+2. Test filters, grouping, sort, links, pagination, access changes, and private data closure.
+3. Restore fields and whole states under conflict, undo, and concurrent editing.
+4. Verify UI and Actions with keyboard and assistive-technology paths.
+
+## Open questions
+
+Retention, compaction, and default grouping are implementation choices as long as authorized history stays attributable and recoverable.

package/corpus/templates/content/docs/product/capabilities/content.home.global.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.home.global"
+name: "Global Home"
+user_promise: "Home belongs to the person and composes authorized work across Personal and organization contexts without pretending it all shares one Workspace."
+primary_user_job: "See my authorized work across contexts while retaining clear provenance and the ability to stay within one context."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.workspace.multi-scope", "content.query.object"]
+related_features:
+  [
+    "content.feature.find-your-place-again",
+    "content.feature.work-across-every-workspace",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Person-owned Home composes explicitly scoped, authorized Personal and organization results with visible origin and opt-in cross-context retrieval."
+proof_requirements:
+  [
+    "Personal, current-context, and explicit global scope selection and provenance coverage",
+    "Access, organization opt-out, result isolation, agent-context, and audit coverage",
+    "Real-interface empty, unavailable, revoked-access, reload, keyboard, and recovery workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Global Home
+
+## Why this exists
+
+A person's work often crosses contexts, but a useful overview must not flatten Personal
+and organization ownership into one imaginary Workspace.
+
+## Example workflow
+
+A person opens Home, selects an explicitly global task section, sees origin badges, and
+opens one result in its owning context. An organization that opts out contributes nothing.
+
+## Product contract
+
+- Home is owned by the person; it composes authorized results rather than owning their objects.
+- Current-context and global retrieval are visible modes, with origin/provenance for every result.
+- Cross-context retrieval is opt-in and honors organization policy, access, and audit boundaries.
+- Revoked, deleted, unavailable, and stale items disappear or report their state without residue.
+
+## Boundaries and non-goals
+
+Multi-scope owns context and access semantics. Home is not a super-workspace, shared
+organization dashboard, or cross-context mutation shortcut.
+
+## Acceptance stories
+
+### Keep origins visible
+
+Given authorized work in Personal and two organizations, when a person opens global Home,
+then each result identifies its origin and opens with that context's authority.
+
+### Honor an opt-out
+
+Given an organization that disallows global retrieval, when Home refreshes, then no row,
+count, search suggestion, or agent context exposes its work.
+
+## Current evidence
+
+No complete person-owned cross-context Home proof is recorded. This Capability remains
+`approved_shape`.
+
+## Proof plan
+
+1. Test current/global mode, provenance, opt-in policy, access changes, and audit records.
+2. Verify result isolation through cards, counts, search, agents, and direct navigation.
+3. Exercise empty, unavailable, revoked, reload, keyboard, and recovery workflows.
+
+## Open questions
+
+The initial Home modules and per-context opt-in controls need implementation design.

package/corpus/templates/content/docs/product/capabilities/content.job.durable.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.job.durable"
+name: "Durable Content jobs"
+user_promise: "Long-running import, export, sync, and enrichment work survives interruption and tells the truth about partial progress."
+primary_user_job: "Start substantial Content work, leave it safely, and later resume or repair it without duplicates or a false completed state."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "configured"
+dependencies: ["content.event.committed", "content.agent.action-parity"]
+related_features:
+  [
+    "content.feature.capture-into-action",
+    "content.feature.collect-structured-input",
+    "content.feature.move-without-starting-over",
+    "content.feature.take-the-whole-vault-with-you",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Durable jobs persist an authorized immutable intent, checkpoints, item outcomes, cancellation and recovery state; retries are idempotent and completion is reported only after the declared closure is terminal."
+proof_requirements:
+  [
+    "Persistence, lease, checkpoint, idempotency, cancellation, resume, and duplicate-delivery tests",
+    "Authorization, bounded payload, progress visibility, partial-failure, and receipt tests",
+    "Interrupted import or export workflow resumed through the real interface",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Durable Content jobs
+
+## Why this exists
+
+Large work needs a memory longer than a browser tab.
+
+## Example workflow
+
+An administrator exports an authorized vault, closes the browser midway, returns later, and resumes from checkpoints. The report distinguishes exported, skipped, failed, and still-pending objects.
+
+## Product contract
+
+- A job persists authorized intent, stable idempotency keys, declared scope, checkpoints, leases, item outcomes, and receipts outside a request lifetime.
+- Workers re-check access and freshness at safe boundaries. Retry cannot duplicate accepted effects.
+- Progress is granular enough to repair partial failure. Cancelled, paused, queued, failed, conflicted, and complete are different states.
+- Completion means the declared work reached terminal item outcomes; a truncated run never masquerades as success.
+
+## Boundaries and non-goals
+
+Individual Actions own domain semantics; jobs provide orchestration, not a second mutation policy. This is not an unbounded background-agent channel.
+
+## Acceptance stories
+
+### Resume without duplicates
+
+Given an import stops after accepted items, when it resumes with the same job identity, then it continues at the checkpoint and does not create duplicate Pages or memberships.
+
+### Report a partial export honestly
+
+Given one authorized asset cannot be resolved during export, when the job finishes, then the package report identifies that unresolved item and the job is not presented as a complete archive.
+
+## Current evidence
+
+Donor evidence: Builder source execution and refresh actions include progress and recovery-focused tests, including `actions/execute-builder-source-execution.test.ts`. No shared durable job substrate proves all Content workloads; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define persisted job, item, checkpoint, lease, and receipt models.
+2. Test interruption, retries, authorization changes, cancellation, and partial failure.
+3. Verify a real large import or export resume and conversion report.
+
+## Open questions
+
+- Queue backend and retention policy remain open while preserving portable job semantics.

package/corpus/templates/content/docs/product/capabilities/content.knowledge.graph.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.knowledge.graph"
+name: "Graph queries"
+user_promise: "Graph navigation and query over typed links, mentions, relations, and authority edges"
+primary_user_job: "Traverse a meaningful authorized network without confusing observed connection with declared governance."
+kind: "primitive"
+state: "exploring"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.relationship.edge", "content.access.visibility-closure"]
+related_features: ["content.feature.sketch-connections-keep-whats-true"]
+roadmap_boundary: "feature"
+acceptance_summary: "Graph queries use stable object and typed-edge vocabulary for access-scoped traversal, paths, ranking, and pattern matching."
+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"
+---
+
+# Graph queries
+
+## Why this exists
+
+Citation, governance, mention, and observed use carry different meanings that must remain distinct even when people explore them together.
+
+## Example workflow
+
+A researcher starts at a source Page, follows `cites` and `supports` edges, filters the path to a decision, and opens the same canonical objects in Graph and Canvas.
+
+## Product contract
+
+Graph queries use stable object and typed-edge vocabulary for access-scoped traversal, paths, ranking, and pattern matching. They distinguish observed usage from declared governance and feed renderers without a second canonical datastore.
+
+## Boundaries and non-goals
+
+Relationships own edge truth and visibility closure owns disclosure. This is not a graph database replacement, automatic authority inference, or a renderer-specific relation store.
+
+## Acceptance stories
+
+### Traverse without exposing a private bridge
+
+Given a traversal with an inaccessible intermediate node, when a viewer asks for a path, then no endpoint, degree, path length, or ranking leaks that node.
+
+### Keep observed use distinct from authority
+
+Given a declared governance edge and an observed usage edge, when they are queried together, then Content labels their distinct semantics rather than treating usage as authority.
+
+## Current evidence
+
+This remains `exploring`; no complete recursive query, ranking, access-closure, and renderer proof is recorded.
+
+## Proof plan
+
+1. Test typed traversal, paths, patterns, ranks, cycles, and stable-object resolution.
+2. Verify closure through expansions, counts, exports, Graph, Canvas, and agents.
+3. Exercise inaccessible bridges, unavailable edges, stale indexes, and path inspection.
+
+## Open questions
+
+The initial graph query grammar and ranking semantics remain exploratory.

package/corpus/templates/content/docs/product/capabilities/content.knowledge.links.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.knowledge.links"
+name: "Links and backlinks"
+user_promise: "Stable links, outline, backlinks, forward links, external-link health, and link-aware navigation through the Page Info rail"
+primary_user_job: "Follow and maintain references that survive renames and reveal whether a target is still usable."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.reference"]
+related_features: ["content.feature.living-references"]
+roadmap_boundary: "feature"
+acceptance_summary: "Internal links use stable identities and portable links; outlines, forward links, backlinks, source links, and target-state taxonomy are access-scoped."
+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"
+---
+
+# Links and backlinks
+
+## Why this exists
+
+A reference promises a route back to the right thing after titles move and sources age. Backlinks make that promise visible from the other side.
+
+## Example workflow
+
+An editor links a Page by stable ID, renames the target, then opens its backlinks in the Info rail. An external link health check reports stale status without changing the original URL.
+
+## Product contract
+
+Internal links use stable identities and portable links; outlines, forward links, backlinks, source links, and target-state taxonomy are access-scoped. External health is cached observation, not a rewrite of source content.
+
+## Boundaries and non-goals
+
+References own link targets. This is not a crawler, an access bypass, or a claim that a failed external check deletes the link.
+
+## Acceptance stories
+
+### Resolve a link after a rename
+
+Given a renamed Page, when a backlink is opened, then its stable link resolves to the renamed canonical target.
+
+### Report a stale external target without rewriting it
+
+Given an inaccessible backlink source, when a viewer opens Info, then it contributes no title, count, or preview.
+
+## Current evidence
+
+No complete link taxonomy, health, embedded rendering, and recovery proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test ID links through rename, move, delete, outline, and backlink changes.
+2. Verify Info rail, embeds, access changes, health states, and URL preservation.
+3. Exercise stale targets, reload, keyboard navigation, and target-state announcements.
+
+## Open questions
+
+The initial external-health cadence and status-retention policy need design.

package/corpus/templates/content/docs/product/capabilities/content.knowledge.search.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.knowledge.search"
+name: "Search"
+user_promise: "Fast access-aware search across titles, bodies, rows, sources, and later comments/review"
+primary_user_job: "Find the most useful authorized evidence quickly and understand where it came from and how fresh it is."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.access.visibility-closure"]
+related_features: ["content.feature.durable-foundations"]
+roadmap_boundary: "feature"
+acceptance_summary: "Search performs indexed lexical retrieval first across eligible objects, returns access-scoped snippets and highlights with source and freshness, and shares ranking semantics between people and agents.."
+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"
+---
+
+# Search
+
+## Why this exists
+
+Search is how a system remembers aloud. It must be quick without ever pronouncing information a viewer may not read.
+
+## Example workflow
+
+A contributor searches a phrase, opens an indexed Page snippet, filters to a connected Source, and sees that one result is stale rather than treating it as current.
+
+## Product contract
+
+Search performs indexed lexical retrieval first across eligible objects, returns access-scoped snippets and highlights with source and freshness, and shares ranking semantics between people and agents.
+
+## Boundaries and non-goals
+
+Visibility closure owns authorization. This is not semantic-answer generation, a source-truth override, or a leakage-prone global index.
+
+## Acceptance stories
+
+### Suppress a private matching title
+
+Given a private matching Page, when a viewer searches its title and body, then no result, highlight, count, or ranking inference exposes it.
+
+### Label a stale connected result
+
+Given a stale connected Source result, when it appears, then its freshness state is visible and opening it follows the Source policy.
+
+## Current evidence
+
+Existing search paths are in progress donor substrate, but complete indexed, freshness, ranking, and agent-parity proof is incomplete. This Capability remains `in_progress`.
+
+## Proof plan
+
+1. Index titles, bodies, rows, and Sources; test lexical queries, snippets, highlights, and pages.
+2. Verify private-match suppression, human/agent ranking, freshness, provenance, and opening.
+3. Exercise stale indexes, source refresh, reload, keyboard traversal, and result summaries.
+
+## Open questions
+
+The first ranking signals beyond lexical relevance need design.

package/corpus/templates/content/docs/product/capabilities/content.layout.responsive.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.layout.responsive"
+name: "Responsive Page layout"
+user_promise: "Pages arrange, resize, and reorder Blocks in columns that remain coherent on smaller screens and in exports."
+primary_user_job: "Arrange a Page for the work at hand while retaining readable, accessible content on any supported surface."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.blocks-field", "content.renderer.typed"]
+related_features:
+  [
+    "content.feature.build-living-dashboards",
+    "content.feature.work-on-content-inside-another-application",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Page layout stores responsive Block arrangement separately from Block content and renders coherent, accessible columns across supported sizes and exports."
+proof_requirements:
+  [
+    "Column create, resize, reorder, persistence, conflict, and recovery coverage",
+    "Responsive, embed, export, keyboard, and assistive-technology coverage",
+    "Shared Action authorization, history, and canonical Block identity coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Responsive Page layout
+
+## Why this exists
+
+Pages need room to breathe on a wide screen without becoming a pile of clipped fragments
+on a narrow one.
+
+## Example workflow
+
+An editor arranges live Blocks in two columns, reorders one, then opens the Page on a
+smaller screen. The readable order is preserved; each Block remains its canonical content.
+
+## Product contract
+
+- Layout stores arrangement and responsive rules separately from canonical Blocks and their content.
+- Authorized edits use shared Actions, history, recovery, and concurrent-change behavior.
+- Small surfaces and exports use a deterministic readable order, not hidden or duplicated content.
+- Keyboard and assistive technology can inspect and change supported layout operations.
+
+## Boundaries and non-goals
+
+Blocks fields own content. This is not a freeform Canvas, slide engine, or alternate Page
+identity.
+
+## Acceptance stories
+
+### Reflow a column layout
+
+Given a two-column Page, when a viewer opens it on a narrow surface, then Blocks appear
+once in a readable deterministic order without inaccessible overflow.
+
+### Keep Blocks canonical
+
+Given an editor reorders a Block, when another authorized View opens the Page, then it
+observes the same Block identity and changed layout without copied content.
+
+## Current evidence
+
+The product boundary is shaped, but no complete layout, responsive, export, and recovery
+proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test layout edits, persistence, undo, conflicts, and canonical Block identity.
+2. Test responsive and embed/export rendering across supported breakpoints.
+3. Exercise keyboard, screen reader, permission, reload, and failure recovery workflows.
+
+## Open questions
+
+The initial supported layout primitives and export fidelity thresholds need design.

package/corpus/templates/content/docs/product/capabilities/content.navigation.sidebar.md

@@ -0,0 +1,86 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.navigation.sidebar"
+name: "Personal sidebar"
+user_promise: "The sidebar is a personal navigation surface with pinned references and query-backed dynamic sections, not object hierarchy."
+primary_user_job: "Return to my important work and discover authorized dynamic collections without changing shared object structure."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.reference", "content.query.object"]
+related_features:
+  [
+    "content.feature.find-your-place-again",
+    "content.feature.make-the-workspace-yours",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "A personal sidebar stores pinned References and dynamic query sections, supports intentional expansion and order, and never treats navigation placement as object parentage or shared mutation."
+proof_requirements:
+  [
+    "Personal pin, order, expand, collapse, query-section, and reload coverage",
+    "Access-safe section results, counts, previews, stale references, and dynamic recovery coverage",
+    "Keyboard, screen-reader, responsive, agent-context, and shared-mutation-denial workflows",
+  ]
+evidence:
+  [
+    "../../../app/components/sidebar/document-sidebar-sections.test.ts",
+    "../../../app/components/editor/database/sidebar.tsx",
+  ]
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Personal sidebar
+
+## Why this exists
+
+Navigation should remember what matters to a person without quietly rewriting the
+workspace's structure. The sidebar is a map, not the territory; maps are allowed taste.
+
+## Example workflow
+
+A viewer pins a Page, reorders their personal references, expands an intentional
+reference, and opens a dynamic query section. Another viewer's order and the Page's
+parentage remain unchanged.
+
+## Product contract
+
+- Pinned entries are personal References; dynamic sections are access-scoped query results.
+- Personal ordering, expansion, and collapse do not reparent Pages, change Database membership, or grant shared edit authority.
+- Intentional references may expand; the sidebar is not a general-purpose object renderer.
+- Missing, deleted, inaccessible, stale, and unavailable entries are handled honestly and recoverably.
+
+## Boundaries and non-goals
+
+References and Queries own target and result meaning. This does not define Page hierarchy,
+general Tree View, or a hidden shared workspace organizer.
+
+## Acceptance stories
+
+### Reorder a personal pin
+
+Given two pinned References, when a viewer changes their order, then only that person's
+navigation preference changes and neither target Page's parentage nor membership changes.
+
+### Open an access-scoped section
+
+Given a dynamic section with inaccessible items, when a viewer expands it, then its rows,
+counts, and previews disclose only authorized results.
+
+## Current evidence
+
+Existing sidebar section tests and sidebar rendering show useful donor behavior. They do
+not prove the full Reference/query, access, recovery, and personal-state contract; this
+Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test pin, reorder, expand, query sections, reload, and stale-reference recovery.
+2. Verify access closure and that personal operations cannot mutate shared structure.
+3. Exercise keyboard, ARIA navigation, responsive behavior, agent context, and unavailable sources.
+
+## Open questions
+
+The first dynamic-section catalog and section-level personalization controls need design.

package/corpus/templates/content/docs/product/capabilities/content.notification.source.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.notification.source"
+name: "Notifications"
+user_promise: "Canonical notifications exposed as queryable Content source and Views"
+primary_user_job: "Receive and organize meaningful notices without confusing them with Tasks or losing their read state."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.event.committed"]
+related_features:
+  [
+    "content.feature.collaborate-in-context",
+    "content.feature.run-projects-your-way",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Notifications have stable identity, actor and origin, read and archive state, access-scoped routing Rules, and queryable Source/View representation."
+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"
+---
+
+# Notifications
+
+## Why this exists
+
+A notification is a trace of something that happened to a person, not an assignment pretending to be urgent. Its read state belongs to that trace.
+
+## Example workflow
+
+A person receives a comment notification, opens its canonical target, marks the notice read, and archives it. A notification View updates without turning the item into My Tasks.
+
+## Product contract
+
+Notifications have stable identity, actor and origin, read and archive state, access-scoped routing Rules, and queryable Source/View representation. Their target remains canonical and My Tasks stays separate.
+
+## Boundaries and non-goals
+
+Committed Events own origins and routing owns delivery. This is not a task assignment engine, a duplicated inbox record, or a bypass around target access.
+
+## Acceptance stories
+
+### Read a comment notice without creating a task
+
+Given a notification target becomes inaccessible, when the list refreshes, then the notice follows its policy without leaking the target title or preview.
+
+### Remove a notice when target access is revoked
+
+Given a person marks one notice read, when they reopen another View, then the same canonical notification state appears without altering task membership.
+
+## Current evidence
+
+No complete notification identity, routing, state, and recovery proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test committed-event notices, target routes, read/archive state, and routing Rules.
+2. Verify target access changes, queryable Views, duplicate delivery, and task separation.
+3. Exercise revocation, archive retention, device conflicts, and accessible navigation.
+
+## Open questions
+
+The archive-retention and multi-device read-conflict policies need design.