@agent-native/core 0.130.2 → 0.131.3

package/corpus/templates/content/docs/product/capabilities/content.renderer.custom-block.md

@@ -0,0 +1,81 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.renderer.custom-block"
+name: "Custom Blocks"
+user_promise: "Name, govern, and reuse a safe renderer without making it a hidden application."
+primary_user_job: "Adopt a governed renderer with explicit inputs and origin."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.typed", "content.source.adapters"]
+related_features: ["content.feature.build-new-surfaces"]
+roadmap_boundary: "feature"
+acceptance_summary: "Custom Blocks have one catalog identity with personal or organization ownership and Content-managed, repository-backed, or provider-backed origin; typed props are optional, discovery is shared, runtime authority is origin-aware, one-off Artifacts promote explicitly, and export is deterministic."
+proof_requirements:
+  [
+    "Ownership scope governs reuse and approval; origin says where source truth lives, and the axes remain independent.",
+    "Slash discovery exposes governed metadata, optional typed inputs, provenance, availability, and a useful preview or fallback.",
+    "Content-managed bundles receive explicit props only in a strict sandbox; source-backed code needs a trusted adapter renderer or visible fallback, and Artifact promotion creates a new catalog identity.",
+    "Extensions retain their visible grants and identity; deterministic export never grants execution authority.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Custom Blocks
+
+## Why this exists
+
+Reusable components must be discoverable and governable without becoming opaque bundles of code with accidental powers. The source of a component and the people allowed to reuse it are separate questions that must remain visible.
+
+## Example workflow
+
+An operations lead approves a repository-backed status card, inserts it from slash search, binds typed props, and gets adapter fallback instead of repository execution.
+
+## Product contract
+
+- Ownership scope governs reuse and approval; origin says where source truth lives, and the axes remain independent.
+- Every entry has stable identity plus name, description, aliases, category, compatibility, icon, ownership, origin, and optional preview metadata. Slash insertion searches that contract; `@` remains for references and expressions.
+- Props are optional. A block may be a fixed renderer with no inputs or expose typed inputs that the editor validates and binds explicitly.
+- Content-managed bundles receive explicit props only in a strict sandbox; source-backed code needs a trusted adapter renderer or visible fallback.
+- **Save as Custom Block** promotes a page-owned Artifact into a new catalog entry while preserving provenance. Copying an Artifact alone never enrolls it in the catalog.
+- An Extension is a more capable application with grants and is never silently presented as a Custom Block.
+- Public or static output uses a deterministic declared fallback and never executes merely because the Custom Block is visible.
+
+## Boundaries and non-goals
+
+- Source adapters own repository/provider synchronization; the Custom Block catalog owns reusable renderer identity, governance, origin metadata, and typed props.
+- Artifact Blocks own one-off page-local HTML/CSS/JS and promotion. Built-in Blocks may implement the same discovery contract but do not masquerade as editable Custom Blocks.
+- Custom Blocks are renderers, not Extensions: they do not acquire arbitrary Actions, ambient Content data, filesystem, parent DOM, secrets, cookies, or network authority.
+
+## Acceptance stories
+
+### Keep axes independent
+
+Given a personal repository-backed block is shared, when scope changes, then repository origin remains unchanged.
+
+### Do not disguise Extensions
+
+Given an Extension has grants, when embedded, then it remains a visible Extension embed.
+
+### Promote one Artifact deliberately
+
+Given a page-owned Artifact has no catalog record, when its owner chooses Save as Custom Block, then Content creates one governed catalog identity with provenance and leaves ordinary copied Artifacts local.
+
+## Current evidence
+
+`app/components/editor/extensions/LocalMdxComponentNode.tsx`, `actions/list-local-component-files.ts`, `actions/write-local-component-file.ts`, and `app/blocks/contentBlockRegistry.tsx` are donors, not a hosted catalog.
+
+## Proof plan
+
+1. Test managed, repository, and provider origins with no props, typed props, local aliases, and origin-preserving scope changes.
+2. Test slash discovery and insertion across compatibility, permissions, preview, validation, unavailable origin, Versions, and provenance.
+3. Deny ambient data, Actions, cookies, secrets, DOM, filesystem, and network; verify trusted adapter fallback without executing repository code in the sandbox.
+4. Promote a one-off Artifact, copy it without promotion, export every origin deterministically, and distinguish built-ins and Extensions.
+
+## Open questions
+
+Catalog version/update policy and the first trusted-adapter eligibility rules still need a dedicated Shape. Network grants remain Extension territory rather than a Custom Block option.

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

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.renderer.graph"
+name: "Collection graph renderers (superseded)"
+user_promise: "Historical umbrella for graph and chart rendering, now split into distinct semantic Graph and analytical Chart capabilities"
+primary_user_job: "Follow the lineage from the former combined renderer concept to the precise modern capability that owns the work."
+kind: "surface"
+state: "superseded"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.typed", "content.view.grouping-aggregation"]
+related_features: []
+roadmap_boundary: "superseded"
+acceptance_summary: "No implementation should target this ambiguous umbrella; analytical rendering belongs to Chart View, semantic relationship exploration belongs to Graph View, and reusable compatibility/export mechanics belong to Typed Renderers."
+proof_requirements:
+  [
+    "Every former analytical responsibility resolves to content.view.chart or content.renderer.typed",
+    "Every former semantic-relationship responsibility resolves to content.view.graph",
+    "No Feature or implementation treats this record as an active contract",
+  ]
+evidence: []
+superseded_by: "content.view.chart"
+last_reviewed: "2026-07-29"
+---
+
+# Collection graph renderers (superseded)
+
+## Why this exists
+
+The early catalog used `Graph` to mean both an analytical chart over grouped records and a semantic network of Pages and Relationships. Those are different user jobs, interaction models, dependencies, and proof gates. Keeping the umbrella active would make an implementer guess which meaning was intended.
+
+## Example workflow
+
+A developer asked to add a bar chart follows `content.view.chart`. A developer asked to let someone explore and edit `supports` relationships follows `content.view.graph`. Both reuse `content.renderer.typed` for compatibility, accessibility, and export behavior.
+
+## Product contract
+
+- `content.view.chart` owns analytical visualizations over typed Query results, grouping, measures, drill-down, saved Views, embedded Blocks, dashboards, and static output.
+- `content.view.graph` owns query-selected canonical nodes, typed Relationship edges, semantic exploration, and authorized edge editing.
+- `content.view.canvas` owns intentional spatial arrangement, view-local connectors, and explicit connector promotion.
+- `content.renderer.typed` owns the shared renderer registry, typed compatibility, inheritance, accessible degradation, and export fallback.
+- Authored Mermaid diagrams remain Code blocks with a Mermaid renderer; they are neither analytical Charts nor semantic Graphs.
+
+## Boundaries and non-goals
+
+- Do not add new dependencies, Features, or implementation evidence to this record.
+- Do not use `Graph` as a synonym for `Chart` in new product contracts.
+- Do not delete this record; it preserves stable-ID lineage for older references.
+
+## Acceptance stories
+
+### Route analytical work correctly
+
+Given a change that renders grouped measures as bars, lines, or another statistical graphic, when product context is resolved, then the active contract is Chart View plus Typed Renderers and this record is not treated as implementable.
+
+### Route semantic work correctly
+
+Given a change that traverses or edits typed Page Relationships, when product context is resolved, then the active contract is Graph View plus the graph-query and Relationship capabilities.
+
+## Current evidence
+
+The modern catalog already contains separate Chart, Graph, Canvas, and Typed Renderer records. This lineage correction changes no runtime behavior and makes no implementation claim.
+
+## Proof plan
+
+Validate that no Feature requires this ID, repository guidance resolves both historical meanings to active records, generated projections label it superseded, and the dependency graph retains valid one-target lineage through `content.view.chart` while naming `content.view.graph` in this body.
+
+## Open questions
+
+The schema currently permits one `superseded_by` target. This record points to Chart because its original dependencies were analytical; the body preserves the separate Graph lineage. Supporting several replacement IDs may be considered later if the broader catalog needs it.

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.