@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.automation.scheduled.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.automation.scheduled"
+name: "Scheduled automation"
+user_promise: "Scheduled queries and recurring heartbeats over current state"
+primary_user_job: "Run a bounded recurring check at the intended time without duplicate work or timezone ambiguity."
+kind: "workflow"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.rule.deterministic", "content.time.types"]
+related_features: ["content.feature.when-this-happens-that-follows"]
+roadmap_boundary: "feature"
+acceptance_summary: "One scheduler evaluates bounded current-state Queries with explicit timezone semantics, schedule identity, idempotency keys, retry policy, and causal lineage."
+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"
+---
+
+# Scheduled automation
+
+## Why this exists
+
+Recurring work should survive restarts, retries, and clock changes. A client timer cannot carry that promise.
+
+## Example workflow
+
+A project owner schedules a weekday overdue-task query in its selected timezone. The scheduler records a causal run, deduplicates a retry, and invokes the ordinary Rule Action once.
+
+## Product contract
+
+One scheduler evaluates bounded current-state Queries with explicit timezone semantics, schedule identity, idempotency keys, retry policy, and causal lineage. Scheduled work uses Rules and shared Actions.
+
+## Boundaries and non-goals
+
+Time types own date semantics and Rules own subscriptions. This is not a client timer, a second queue, or permissionless background execution.
+
+## Acceptance stories
+
+### Deduplicate a repeated schedule window
+
+Given a delayed retry for a scheduled run, when the same schedule window repeats, then idempotency prevents a duplicate mutation and retains the original lineage.
+
+### Run across a daylight-saving boundary
+
+Given a DST transition, when a recurring schedule reaches its local time, then Content applies its declared timezone policy and records the actual run time.
+
+## Current evidence
+
+Current scheduler substrate is in progress, but complete timezone, bounded-query, dedupe, and lineage proof is absent. This Capability remains `in_progress`.
+
+## Proof plan
+
+1. Test timezone recurrence, bounded query windows, schedule edits, pauses, and restart behavior.
+2. Simulate duplicate delivery, retries, missed windows, DST, and failed Rules.
+3. Verify owner controls, receipts, disablement, and unavailable-state recovery.
+
+## Open questions
+
+The missed-run and DST policy vocabulary needs design.

package/corpus/templates/content/docs/product/capabilities/content.capture.enrich.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.capture.enrich"
+name: "Capture and enrichment"
+user_promise: "Send material to a chosen Database and let its own rules turn it into durable context."
+primary_user_job: "Capture a link, file, identifier, or note once without later wondering where it went or whether enrichment changed the original capture."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.source.catalog",
+    "content.template.graph",
+    "content.event.committed",
+  ]
+related_features: ["content.feature.capture-into-action"]
+roadmap_boundary: "feature"
+acceptance_summary: "Every entrance resolves or creates one canonical Page in an explicit or remembered Database, preserves provenance and idempotency, commits its own receipt, and starts target-owned enrichment that can retry independently."
+proof_requirements:
+  [
+    "Cross-entrance idempotency and canonical identifier tests",
+    "Database destination, template, permission, provenance, Event, and receipt tests",
+    "End-to-end capture with delayed enrichment failure, retry, and repair",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Capture and enrichment
+
+## Why this exists
+
+Capture should be one reliable doorway, not a collection of tiny inboxes that lose provenance in the rain.
+
+## Example workflow
+
+A person shares an interview URL to Research. Capture reuses its canonical Page, records the URL and snapshot handle, adds Database membership, and a Research rule later extracts questions; a failed extraction is visible and retryable.
+
+## Product contract
+
+- Browser, share sheet, Clips, file, identifier, agent, email, and provider entrances call one deterministic Capture contract.
+- The caller chooses a Database or uses a visible remembered default; destination permissions, templates, defaults, and validation apply before membership commits.
+- Canonical URLs and identifiers deduplicate idempotently, with a deliberate-copy escape hatch. Large assets and snapshots live in file storage, not SQL bodies.
+- Capture commits provenance, causality, membership, and a receipt before target-owned Rules or agents enrich. Enrichment never makes capture appear incomplete and retries without duplicating the Page.
+
+## Boundaries and non-goals
+
+The Database owns rules and routing; Sources own provider fidelity. An Inbox is a user or template choice, not capture infrastructure.
+
+## Acceptance stories
+
+### Reuse a canonical capture
+
+Given the same normalized URL already exists in the chosen Database, when it is captured again, then Capture reuses the Page and records a new provenance-aware receipt unless the caller explicitly asks for a copy.
+
+### Repair enrichment separately
+
+Given Capture committed a Page but its downstream classifier fails, when the person retries classification, then the original Page and capture receipt remain intact and only enrichment reruns.
+
+## Current evidence
+
+Donor evidence: `actions/import-content-source.ts`, `actions/import-content-source.db.test.ts`, and source actions establish several intake paths. No common Capture Action or complete entrance-to-enrichment proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Route representative entrances through one Action and test identity normalization.
+2. Test destination selection, access, assets, provenance, Events, and receipts.
+3. Exercise delayed enrichment, retry, duplicate delivery, and repair in the interface.
+
+## Open questions
+
+- The exact remembered-destination scope per entrance remains open.

package/corpus/templates/content/docs/product/capabilities/content.command.fabric.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.command.fabric"
+name: "Unified commands"
+user_promise: "Slash, Cmd+K, menus, shortcuts, Buttons, and agents discover the same scoped commands and Actions"
+primary_user_job: "Discover the right permitted operation from any surface and understand its effect before committing it."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.agent.action-parity"]
+related_features: ["content.feature.put-your-organizations-know-how-to-work"]
+roadmap_boundary: "feature"
+acceptance_summary: "Commands have stable IDs, typed arguments, scope, ranking, can-run reasons, effects, confirmation, permission, receipt, and Undo metadata."
+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"
+---
+
+# Unified commands
+
+## Why this exists
+
+The same verb should not change its authority or side effect when reached through a palette, shortcut, menu, Button, or agent.
+
+## Example workflow
+
+A person opens Cmd+K on a Page, finds Archive, sees that confirmation is needed, and runs the same command available from the page menu and agent chat.
+
+## Product contract
+
+Commands have stable IDs, typed arguments, scope, ranking, can-run reasons, effects, confirmation, permission, receipt, and Undo metadata. Every invocation resolves to the same shared Action.
+
+## Boundaries and non-goals
+
+Action parity owns operation semantics and Buttons bind commands. This is not a separate menu mutation API or a guarantee that every command appears in every surface.
+
+## Acceptance stories
+
+### Explain a disabled command
+
+Given a command unavailable for the focused Page, when it is searched in Cmd+K, then Content explains the scope or permission reason and does not run it.
+
+### Invoke Archive from two entry points
+
+Given an agent and menu invoke the same command, when both are authorized, then they produce equivalent Action results and Events.
+
+## Current evidence
+
+No complete command discovery, ranking, confirmation, and cross-surface proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test command ID stability, arguments, ranking, and can-run explanations.
+2. Compare menu, palette, shortcut, Button, slash, and agent invocation results.
+3. Test confirmation, cancellation, denial, Undo, shortcut collisions, and reload.
+
+## Open questions
+
+The command ranking model and shortcut conflict policy need design.

package/corpus/templates/content/docs/product/capabilities/content.comment.page-owned.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.comment.page-owned"
+name: "Comments"
+user_promise: "Threaded Comments stay owned by a Page while targeting one or more precise Blocks."
+primary_user_job: "Give exact feedback that remains intelligible after the document changes or appears elsewhere."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.page", "content.object.blocks-field"]
+related_features: ["content.feature.collaborate-in-context"]
+roadmap_boundary: "feature"
+acceptance_summary: "Comments preserve authoritative Page context, thread identity, rich body, precise historical Block anchors, access, and resolution across references, embeds, edits, and deletion."
+proof_requirements:
+  [
+    "Page-owned thread and multi-Block anchor identity",
+    "Anchor repair and historical target behavior after edits/deletion",
+    "Access, mentions, replies, resolution, and notification behavior",
+    "Shared Action/UI, embed/reference, concurrency, and recovery tests",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Comments
+
+## Why this exists
+
+Feedback should remain attached to the sentence, image, or Block it concerns, even when the work is embedded in another place. Otherwise discussion becomes a trail of vague ghosts.
+
+## Example workflow
+
+A reviewer comments on two Blocks in a brief, replies with a Page reference, and resolves the thread after revision. Later the brief is embedded elsewhere; the comment still opens under the original Page context and its historical target.
+
+## Product contract
+
+- A Comment thread is owned by one Page and may target one or several Blocks or ranges in its Blocks fields.
+- Rich Comment bodies use the shared Blocks-field grammar; replies and mentions retain the same Page authority.
+- Anchors follow stable Block identity where possible and preserve historical target context after deletion rather than attaching to plausible new text.
+- Resolve, reopen, edit, reply, and notification operations use shared Actions and record attributable change.
+- References and embeds display the authoritative Page-owned thread; they do not clone or re-home it.
+
+## Boundaries and non-goals
+
+- Comments are exact-material feedback, not the Page-wide Discussion timeline.
+- A comment does not create a Page, Database membership, or independent share policy.
+- This capability does not define named Version access, although Comments retain Version context.
+
+## Acceptance stories
+
+### Preserve a deleted anchor
+
+Given a Comment on a Block range, when the range and Block are deleted, then the Comment remains resolvable and opens authorized historical context instead of moving to a new nearby range.
+
+### Keep one authoritative thread across an embed
+
+Given a Page with a Comment thread is referenced or embedded elsewhere, when a viewer opens the thread from either occurrence, then they see the same Page-owned thread and access decision.
+
+## Current evidence
+
+`document_comments` schema and editor Comment UI/actions provide anchored threaded-comment substrate. Stable multi-Block anchors, rich universal fields, historical repair, and embed authority are not fully proven; this remains `approved_shape`.
+
+## Proof plan
+
+1. Create, reply, mention, resolve, reopen, edit, and delete Comments through UI and Actions.
+2. Test anchors through Block editing, move, split, deletion, restore, and named-Version context.
+3. Verify references, embeds, access changes, notifications, agents, and exports.
+4. Exercise concurrent replies/resolution, reload, keyboard, and assistive technology.
+
+## Open questions
+
+Anchor matching heuristics may evolve, but they may never silently claim a new target is the old one.

package/corpus/templates/content/docs/product/capabilities/content.diff.ai-assist.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.diff.ai-assist"
+name: "Agent-assisted review"
+user_promise: "Agents can summarize and guide large review sets without bypassing the authority to decide them."
+primary_user_job: "Understand a large proposal quickly while keeping evidence, scope, and final review control visible."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.diff.filtered-review", "content.agent.action-parity"]
+related_features: ["content.feature.review-changes-in-place"]
+roadmap_boundary: "feature"
+acceptance_summary: "Agent assistance consumes an access-scoped typed change graph, cites inspectable change evidence and uncertainty, and uses the same authorized review Actions as a person."
+proof_requirements:
+  [
+    "Access-scoped typed change graph and evidence links",
+    "Summary, grouping, risk, and uncertainty behavior grounded in actual changes",
+    "No authority bypass; shared confirmation and decision Actions",
+    "Stale context, adversarial input, retry, audit, and human-interface tests",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Agent-assisted review
+
+## Why this exists
+
+Large review sets exhaust attention. An agent can make the shape visible, but it must remain a lamp beside the road, not a hand on the steering wheel.
+
+## Example workflow
+
+An editor asks an agent to summarize a large proposed update. The agent groups changes, links each claim to typed diffs, identifies uncertain or risky items, and prepares a filtered review; the editor still makes every decision through the same authorized Actions.
+
+## Product contract
+
+- Assistance reads only the viewer-authorized typed change graph and its scoped evidence.
+- Summaries distinguish observed change facts, inferences, risks, and uncertainty; each recommendation links back to inspectable changes.
+- An agent may prepare filters and explain dependencies but cannot bypass review authority or fabricate a completion receipt.
+- Accept/reject/defer operations call the same Action surface, policy, confirmation, Events, and History as human review.
+- Stale, unavailable, or incomplete evidence is reported as such, not coerced to a clean summary.
+
+## Boundaries and non-goals
+
+- This is not an autonomous publishing or approval capability.
+- It does not replace in-place diffs, filtered review, or human accountability.
+- Model choice and prose style are not proof of review correctness.
+
+## Acceptance stories
+
+### Ground a recommendation in visible evidence
+
+Given an agent recommends accepting a Property change, when the editor opens the recommendation, then it identifies the exact typed diff, dependencies, and uncertainty rather than citing inaccessible or invented context.
+
+### Preserve review authority
+
+Given an agent prepares an all-visible acceptance, when it lacks the editor's authority or confirmation, then no change applies and the same Action denial/confirmation boundary appears as in the UI.
+
+## Current evidence
+
+Current agent Action infrastructure and source review substrate demonstrate adjacent machinery. A trustworthy generic typed change graph, scoped evidence synthesis, and end-to-end review parity are not yet proven; this remains `approved_shape`.
+
+## Proof plan
+
+1. Test summaries against known typed change fixtures, including omissions, uncertainty, and conflicting changes.
+2. Verify every cited item is accessible and opens its ordinary diff.
+3. Exercise authorization, confirmation, stale context, adversarial content, retries, and audit receipts.
+4. Validate the complete UI-plus-agent review workflow with accessible controls.
+
+## Open questions
+
+Ranking and summary presentation remain open. The agent may never substitute a plausible narrative for evidence or authority.

package/corpus/templates/content/docs/product/capabilities/content.diff.filtered-review.md

@@ -0,0 +1,79 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.diff.filtered-review"
+name: "Filtered change review"
+user_promise: "A reviewer can accept or reject one change or an exact visible set without accidentally deciding newer or hidden changes."
+primary_user_job: "Review a manageable subset of a large proposal while preserving dependency safety and auditability."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.diff.in-place"]
+related_features:
+  [
+    "content.feature.review-changes-in-place",
+    "content.feature.explore-alternatives-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Filtered bulk review snapshots the exact eligible change identities and bases, validates dependencies and authority atomically, and records idempotent decisions without sweeping in concurrent matches."
+proof_requirements:
+  [
+    "Exact filter/selection snapshot semantics",
+    "Dependency and mixed-authority preflight",
+    "Idempotent atomic apply with durable Event receipts",
+    "Concurrent additions, stale changes, retry, undo, and UI/Action coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Filtered change review
+
+## Why this exists
+
+Large change sets need a humane slice, but “accept all visible” must mean exactly what the reviewer saw—not whatever happened to match later.
+
+## Example workflow
+
+An editor filters an agent proposal to changes in one section, selects the visible compatible changes, and accepts them. A new change that arrives while review is open remains pending; a hidden prerequisite is surfaced rather than silently applied.
+
+## Product contract
+
+- A filtered decision resolves exact eligible change IDs, observed bases, and filter context at selection time.
+- New matching changes do not enter an already prepared bulk decision.
+- Preflight checks dependencies, stale bases, source policy, and authority for the full intended set.
+- Mixed permissions or incompatible dependencies produce an explicit repair/narrowing state, never an invisible partial commit.
+- Repeated delivery of the same approved decision is idempotent and emits durable receipts.
+
+## Boundaries and non-goals
+
+- This does not decide the typed rendering of a single change or generate proposals.
+- It is not a generic Database bulk-edit engine, though both need exact selection semantics.
+- Agents may narrow scope only when faithful to the request and must report skipped work.
+
+## Acceptance stories
+
+### Freeze the visible set
+
+Given a reviewer filters to five pending changes, when a sixth matching change arrives before **Accept visible** completes, then only the five resolved IDs are decided and the sixth remains pending.
+
+### Refuse unsafe partial approval
+
+Given a selected change depends on an inaccessible or stale prerequisite, when the reviewer accepts the set, then no subset silently applies and Content explains the dependency or authority repair path.
+
+## Current evidence
+
+Existing source-review and bulk-operation machinery offers useful examples of selection and audit behavior. It does not prove generic filtered review snapshot, dependency, and idempotent decision semantics; this remains `approved_shape`.
+
+## Proof plan
+
+1. Exercise single, selected, filtered, and all-visible decisions across typed change kinds.
+2. Race concurrent additions, edits, removals, retries, and duplicate requests.
+3. Test dependencies, mixed authority, source locks, stale bases, undo, and Event/History receipts.
+4. Verify UI and agent Action parity, accessibility, and clear scope reporting.
+
+## Open questions
+
+Filter language and progress presentation may vary; exact selection snapshot and no-silent-partial behavior may not.

package/corpus/templates/content/docs/product/capabilities/content.diff.in-place.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.diff.in-place"
+name: "In-place typed review"
+user_promise: "Changes are reviewed inside the ordinary Page, Database, Board, template, source, or code surface that gives them meaning."
+primary_user_job: "Evaluate a proposed change in context rather than translating it from a generic red/green destination."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.event.committed", "content.renderer.typed"]
+related_features:
+  [
+    "content.feature.review-changes-in-place",
+    "content.feature.explore-alternatives-safely",
+    "content.feature.evolve-systems-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Typed change identities and dependencies render in the normal object surface, retain causal/actor context, and record durable authorized review decisions."
+proof_requirements:
+  [
+    "Typed change model for bodies, Blocks, Properties, memberships, and structured values",
+    "Ordinary renderer integration and accessible in-place comparison",
+    "Durable accept/reject/defer/supersede Events with authority",
+    "Stale, dependency, conflict, source, and agent-run coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# In-place typed review
+
+## Why this exists
+
+A property, Block, membership, and source proposal carry different meaning. Review should meet each where it lives instead of flattening all work into an unreadable universal diff.
+
+## Example workflow
+
+An agent proposes article copy and Status changes. The editor sees copy changes in the Page editor, the Status change in its Property renderer, accepts one, rejects the other, and History records the durable decisions with the run context.
+
+## Product contract
+
+- A change has stable identity, target type, dependencies, actor/origin, causal context, before/after material, and disposition.
+- Body, Block, Property, membership, and structured changes render through their ordinary typed surfaces.
+- Accept, reject, defer, and supersede are authorized durable decisions that emit Events and preserve why a proposal ended.
+- A stale target, incompatible dependency, source authority restriction, or conflict is explicit; no review button silently applies a plausible partial result.
+- Agent and human proposals use the same review model and Actions.
+
+## Boundaries and non-goals
+
+- This capability does not define filtered-set selection, AI assistance, or named Version branching.
+- It does not replace low-level Events, logical Revisions, or recovery snapshots.
+- A typed renderer may degrade honestly; review may not discard unknown source content.
+
+## Acceptance stories
+
+### Review mixed typed changes in context
+
+Given a proposal changes a paragraph and a select Property, when an editor opens review, then each difference renders in its ordinary surface and the editor can decide independently where dependencies allow.
+
+### Surface a stale conflict honestly
+
+Given a proposal is based on a Block another editor changed, when review attempts acceptance, then Content shows a stale/rebase/conflict state and does not overwrite the newer change.
+
+## Current evidence
+
+Source change sets, document snapshots, and Builder review machinery are donor substrate. The repository does not yet prove one generic typed in-place diff system across Content objects, so this remains `approved_shape`.
+
+## Proof plan
+
+1. Propose and render each supported change type through UI and shared Actions.
+2. Test dependency ordering, stale bases, conflicts, source locks, permission changes, and Undo.
+3. Verify Events, History, agent attribution, recovery, and accessible comparison.
+4. Exercise reload, concurrent decisions, portable output, and unavailable renderers.
+
+## Open questions
+
+The internal change representation and exact visual affordances remain open; typed context and durable authorized disposition are settled.

package/corpus/templates/content/docs/product/capabilities/content.discussion.page.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.discussion.page"
+name: "Page Discussion"
+user_promise: "Every Page has one continuing Discussion for humane, Page-wide collaboration and curated activity."
+primary_user_job: "Discuss the larger meaning of work without losing the Page and revision context that gives the conversation sense."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.object.page",
+    "content.object.blocks-field",
+    "content.event.committed",
+  ]
+related_features: ["content.feature.collaborate-in-context"]
+roadmap_boundary: "feature"
+acceptance_summary: "A lazily materialized canonical Page Discussion supports rich messages, bounded threads, reactions, Page-version cursors, selected Event/Comment activity, access, and notifications without replacing Comments or History."
+proof_requirements:
+  [
+    "Canonical Page Discussion identity across current and future Versions",
+    "Rich message, reply, mention, reaction, and bounded-thread behavior",
+    "Revision/Event cursor and curated activity projection",
+    "Access, notification, permalink, UI/Action, and concurrency coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Page Discussion
+
+## Why this exists
+
+Exact comments are not enough for the larger conversation: why the change matters, what was decided, and what should happen next. Discussion gives that conversation one durable home.
+
+## Example workflow
+
+A teammate starts a Page Discussion about an unclear strategy, replies in one focused sub-thread, links a relevant Comment thread, and later opens “view the Page then” to see the revision cursor that existed when the message was posted.
+
+## Product contract
+
+- Every Page has one canonical Discussion identity, created lazily on first use and authoritative across current and future Page Versions.
+- Messages use Blocks fields; they may reply to or mention a message or actor, while one message opens at most one focused sub-conversation rather than infinite nesting.
+- A message may connect to Comment threads without moving those Comments out of their Page-owned context.
+- Each message records quiet Page Version and Revision/Event cursor context; UI reveals historical Page/diff on demand.
+- Discussion curates selected collaboration Events and grouped Comment activity. History remains exhaustive; Comments remain exact anchors.
+
+## Boundaries and non-goals
+
+- Discussion is not another body Block, Database membership, task engine, or named Version.
+- It does not replace Comments, Info, Annotations, Versions, or History; these are separate rails/modes.
+- Curated activity does not duplicate Event authority or expose inaccessible details.
+
+## Acceptance stories
+
+### Continue one conversation across Versions
+
+Given a Page has a Discussion and later receives a named Version, when a collaborator opens either Version, then the same Discussion is available with each message's appropriate Version cursor preserved.
+
+### Keep a focused thread bounded
+
+Given a Discussion message has replies, when a reply starts a sub-conversation, then subsequent replies remain understandable in that bounded thread and do not build an infinitely nested tree.
+
+## Current evidence
+
+Current Comments, mentions, notifications substrate, and document history provide adjacent pieces. A universal canonical Discussion, rich message grammar, cursors, and curated activity projection are not yet proven; this remains `approved_shape`.
+
+## Proof plan
+
+1. Create canonical Discussions, messages, replies, mentions, reactions, and Comment links across Page lifecycle operations.
+2. Verify cursors, historical Page/diff links, selected Event grouping, and History separation.
+3. Test access changes, notifications, permalinks, agents, external continuation boundaries, and deletion.
+4. Exercise concurrent messages/reactions, reload, keyboard, and assistive technology.
+
+## Open questions
+
+Default grouping and activity-selection rules remain product refinement; they cannot make Discussion the recovery authority or create a second Page identity.