@agent-native/core 0.130.1 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.author.footnotes.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.author.footnotes"
+name: "Footnotes"
+user_promise: "Add a durable explanatory or citation note without manually managing superscript text."
+primary_user_job: "Add and navigate durable semantic notes beside prose."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.block", "content.object.reference"]
+related_features: ["content.feature.cite-what-you-found"]
+roadmap_boundary: "feature"
+acceptance_summary: "Footnotes have stable anchors, visual editing, automatic numbering, bidirectional navigation, accessibility, and provider-neutral source/export parity."
+proof_requirements:
+  [
+    "A footnote reference and body are semantic authoring objects, not ordinary superscript text.",
+    "Numbering and back-links derive from the document order while anchors retain identity through edits.",
+    "Editor, reader, and export use the shared source representation and expose an accessible fallback.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Footnotes
+
+## Why this exists
+
+Writers need to qualify a claim without breaking the reading flow or hand-numbering fragile markers. Notes need to stay attached through revision and remain usable to readers who navigate by keyboard or assistive technology.
+
+## Example workflow
+
+A historian inserts a footnote, reorders paragraphs, and exports; numbering updates while readers can move from reference to note and back.
+
+## Product contract
+
+- A footnote reference and body are semantic authoring objects, not ordinary superscript text.
+- Numbering and back-links derive from the document order while anchors retain identity through edits.
+- Editor, reader, and export use the shared source representation and expose an accessible fallback.
+
+## Boundaries and non-goals
+
+- Citation records own source metadata and bibliography policy; Footnotes own inline note anchors, authoring, navigation, and source representation.
+- Footnotes are not superscript text, Custom Blocks, or a reason to add general raw-source editing.
+
+## Acceptance stories
+
+### Preserve anchor identity
+
+Given prose is revised and notes reorder, when saving, then identity survives while numbering updates.
+
+### Export a readable fallback
+
+Given a destination lacks footnotes, when exporting, then the note is not flattened into unexplained superscript text.
+
+## Current evidence
+
+No footnote extension exists under `app/components/editor/extensions/`; `app/components/editor/VisualEditor.tsx` and `shared/nfm.ts` are donors.
+
+## Proof plan
+
+1. Insert/edit/delete/reorder notes and verify anchors and links.
+2. Test keyboard and screen-reader traversal.
+3. Round-trip through source and export adapters.
+4. Test copy/paste and concurrent edits.
+
+## Open questions
+
+No product question remains.

package/corpus/templates/content/docs/product/capabilities/content.author.math.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.author.math"
+name: "Math and equations"
+user_promise: "Write an equation inline or as a block and have it stay intelligible everywhere I read or export it."
+primary_user_job: "Create equations that remain readable across representations."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.block", "content.renderer.typed"]
+related_features: []
+roadmap_boundary: "supporting"
+acceptance_summary: "Inline and display math use one editable source value with KaTeX rendering, accessible MathML, visible invalid-source fallback, and source/export parity."
+proof_requirements:
+  [
+    "Inline selection can become an equation and reopen the same source editor.",
+    "Invalid math preserves visible source and a diagnostic instead of disappearing or looking valid.",
+    "Math remains a built-in Block identity and is not a Custom Block.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Math and equations
+
+## Why this exists
+
+An equation is both source a writer must correct and meaning a reader must understand. Rendering cannot be allowed to hide malformed notation or make one surface silently disagree with another.
+
+## Example workflow
+
+A scientist selects `E = mc^2`, corrects LaTeX in the inline equation editor, and exports readable math; invalid source stays visible with its error.
+
+## Product contract
+
+- Inline selection can become an equation and reopen the same source editor.
+- Invalid math preserves visible source and a diagnostic instead of disappearing or looking valid.
+- Math remains a built-in Block identity and is not a Custom Block.
+
+## Boundaries and non-goals
+
+- The typed renderer substrate owns presentation; Math owns equation source, inline/display authoring, and accessible fallback.
+- Math is a built-in Block capability, not a Custom Block, arbitrary code executor, or a new formula language.
+
+## Acceptance stories
+
+### Show invalid source
+
+Given malformed LaTeX, when KaTeX rejects it, then the source and diagnostic stay visible.
+
+### Preserve one value
+
+Given copied math is read in editable and read-only surfaces, then both derive from the same LaTeX.
+
+## Current evidence
+
+`app/components/editor/MathRenderer.tsx`, `math-rendering.spec.ts`, `MathRenderer.test.tsx`, and `SlashCommandMenu.tsx` prove KaTeX, MathML, and creation; public/export parity remains unjoined.
+
+## Proof plan
+
+1. Test selection promotion, slash insertion, source editing, and display mode.
+2. Assert MathML and invalid fallback in SSR/client output.
+3. Copy/paste, source-round-trip, and provider-sync equations.
+4. Verify HTML/PDF rendering or fallback.
+
+## Open questions
+
+No product question remains; surface proof is pending.

package/corpus/templates/content/docs/product/capabilities/content.author.media.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.author.media"
+name: "Media Blocks"
+user_promise: "Put images, audio, video, files, embeds, captions, and source-aware assets in a document without losing access or provenance."
+primary_user_job: "Attach authorized media with provenance and honest fallbacks."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.block"]
+related_features: ["content.feature.read-and-annotate-anything"]
+roadmap_boundary: "feature"
+acceptance_summary: "Media Blocks use stable asset handles, access-aware rendering, upload/paste/drop intake, captions and provenance, and honest export degradation."
+proof_requirements:
+  [
+    "Large media lives in configured blob storage; records retain handles and metadata, never embedded payload bodies.",
+    "Every view checks access before loading or previewing an asset and carries captions and known source provenance.",
+    "Unsupported destinations expose a declared fallback rather than silently dropping the media.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Media Blocks
+
+## Why this exists
+
+An asset is not just a preview: it has storage, access, caption, provenance, and export consequences. Authors need to place media naturally without leaking a private asset or losing the context that makes it useful.
+
+## Example workflow
+
+Leah drops an interview recording on a research Page, captions it, shares it with an editor, and exports a linked fallback.
+
+## Product contract
+
+- Large media lives in configured blob storage; records retain handles and metadata, never embedded payload bodies.
+- Every view checks access before loading or previewing an asset and carries captions and known source provenance.
+- Unsupported destinations expose a declared fallback rather than silently dropping the media.
+
+## Boundaries and non-goals
+
+- Storage owns bytes and Content stores only handles/metadata; source adapters own source truth and write-back policy.
+- Media Blocks do not grant access through Page embedding or promise identical playback on every export destination.
+
+## Acceptance stories
+
+### Enforce asset access
+
+Given a private asset appears on a shared Page, when an unauthorized viewer opens it, then no bytes or hidden metadata leak.
+
+### Keep bytes in storage
+
+Given a large pasted video, when saved, then Content stores only a stable handle and metadata.
+
+## Current evidence
+
+`app/components/editor/extensions/AudioBlock.tsx`, `VideoBlock.tsx`, and `ImageBlock.tsx` are donors; unified handle/access/provenance/export behavior is absent.
+
+## Proof plan
+
+1. Upload, paste, and drop supported media and verify handles/captions/provenance.
+2. Test owner, shared, and denied reader behavior.
+3. Export every class with its declared fallback.
+4. Exercise replacement, deletion, retry, and unavailable storage.
+
+## Open questions
+
+Initial embed providers remain open.

package/corpus/templates/content/docs/product/capabilities/content.author.mermaid.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.author.mermaid"
+name: "Mermaid diagrams"
+user_promise: "Insert a diagram as ordinary Mermaid source and read a faithful rendered diagram when possible."
+primary_user_job: "Create portable Mermaid diagrams from ordinary Code source."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.author.code", "content.renderer.typed"]
+related_features: []
+roadmap_boundary: "supporting"
+acceptance_summary: "`/Diagram (Mermaid)` creates a normal Code block with `language = mermaid`; the built-in renderer provides Source and Rendered views, source round trips, accessible/static fallback, and shared export behavior."
+proof_requirements:
+  [
+    "Mermaid is a Code language plus built-in renderer, not a Custom Block or a separate diagram datastore.",
+    "The renderer may prefer an Agent Native style but falls back to faithful Mermaid; errors preserve source and diagnostics.",
+    "Public and exported documents never execute source and use a pinned static rendering or readable source fallback.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Mermaid diagrams
+
+## Why this exists
+
+A diagram should remain editable, portable source rather than becoming a picture that only one editor understands. Authors also need an honest fallback when a renderer does not support the diagram they wrote.
+
+## Example workflow
+
+Noor uses `/Diagram (Mermaid)`, edits its ordinary Code source, and exports a diagram that either renders faithfully or retains source and error.
+
+## Product contract
+
+- Mermaid is a Code language plus built-in renderer, not a Custom Block or a separate diagram datastore.
+- The renderer may prefer an Agent Native style but falls back to faithful Mermaid; errors preserve source and diagnostics.
+- Public and exported documents never execute source and use a pinned static rendering or readable source fallback.
+
+## Boundaries and non-goals
+
+- `content.author.code` owns source and optional runtime behavior; Mermaid owns a compatible built-in renderer for `language = mermaid`.
+- Mermaid is not a Custom Block, graph database, Canvas replacement, or a license to execute diagram source for viewers.
+
+## Acceptance stories
+
+### Preserve Code identity
+
+Given an imported fenced Mermaid file, when re-exported, then it remains `language = mermaid` Code, not a Custom Block.
+
+### Try compatible fallbacks
+
+Given preferred styling fails, when rendering, then Mermaid fallback runs before source/error display.
+
+## Current evidence
+
+`app/blocks/contentBlockRegistry.tsx` is the Mermaid donor; `app/components/editor/extensions/CodeBlockNode.tsx` supplies Code identity. Fence mapping, SSR, accessibility, and export remain gaps.
+
+## Proof plan
+
+1. Create/import Mermaid blocks and verify fences/captions.
+2. Test preferred, Mermaid, and double-failure paths.
+3. Verify sanitizer, theme, accessibility, SSR, and static export.
+4. Confirm no Custom Block catalog entry.
+
+## Open questions
+
+Renderer Auto versus explicit preference remains open.

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.