@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.agent.resource-consent.md

@@ -0,0 +1,90 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.agent.resource-consent"
+name: "Agent resource consent"
+user_promise: "Resources independently declare whether agents may use them as context and whether agents may edit them, while inheritable ceilings can narrow either decision."
+primary_user_job: "Let an agent help with selected material without turning ordinary sharing access or a recoverable edit into blanket agent authority."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.access.page-database", "content.event.committed"]
+related_features: ["content.feature.keep-your-private-vault-private"]
+roadmap_boundary: "feature"
+acceptance_summary: "An authorized person can set distinct agent-context and agent-edit consent on a resource; inherited ceilings can only narrow them; every agent read or mutation rechecks the effective decision at use time."
+proof_requirements:
+  [
+    "Independent context and edit decisions through the shared resource/action surface, without adding a Page role",
+    "Inherited resource, container, workspace, and policy ceilings that only narrow effective consent and remain explainable",
+    "Access and consent re-evaluation before every agent read, traversal, synthesis input, and mutation, including mid-run revocation",
+    "Attributable Events and truthful typed failures for denial, revocation, unavailable policy state, and recoverability",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Agent resource consent
+
+## Why this exists
+
+Ordinary sharing answers who may access a resource. It does not answer whether an agent may use that resource as input, nor whether an agent may change it. Those are consequential decisions with different risks: a private note can be visible to its owner yet excluded from an agent's context, and an agent may be allowed to read a brief without being allowed to edit it.
+
+Resource consent supplies those decisions without inventing another Page role or a parallel permission system. It composes with existing access, source policy, and workspace policy; it never broadens them.
+
+## Example workflow
+
+A researcher shares a project brief with collaborators and asks an agent to draft a summary. The brief allows agent context but disallows agent edits. One linked personal note is excluded from agent context, so the run does not read it even though the researcher can. A folder-level policy later disables agent context for its children; the brief's own allowance cannot override that ceiling. If consent is revoked while the run is gathering inputs, its next read fails safely and the agent reports that it must continue without the resource or stop.
+
+## Product contract
+
+### Separate, composable decisions
+
+- Each resource has distinct **agent context** and **agent edit** decisions. Context consent governs use as input, including search, traversal, retrieval, summarization, and synthesis; edit consent governs a proposed or committed agent mutation.
+- Edit consent does not imply context consent, and context consent does not imply edit consent. An edit must satisfy ordinary edit authority, applicable source/write-back policy, effective edit consent, and any required approval/confirmation gate.
+- Effective consent is the intersection of ordinary access, resource consent, source policy, and inherited container, workspace, organization, and framework-policy ceilings. A ceiling may narrow or disable a descendant decision but never grants or widens it.
+- The resource's own decision may be inherited where policy permits. An explicit descendant choice can narrow an inherited allowance, but it cannot escape an inherited denial or ceiling.
+- Consent is evaluated for the acting principal and current run at the point of use. Stored selection, search indexes, precomputed plans, queued work, and recovered runs do not carry a durable permission grant.
+
+### Revocation, accountability, and failure
+
+- Every agent read and every mutation preflight re-evaluates access and effective consent. A mid-run revocation prevents the next affected operation; already committed, authorized changes retain their ordinary Event and recovery history.
+- A denied or revoked resource is omitted from ambient discovery and aggregate inputs according to the normal access contract. A direct request receives a typed, non-leaking denial or unavailable state, never a fabricated empty success.
+- The run records the resource decision that authorized each committed mutation and an attributable Event/Revision. Recoverability makes an authorized mutation easier to undo; it neither grants consent nor substitutes for intent or access.
+- A person can inspect the applicable consent and the narrowest denying ceiling where they are authorized to see it. The explanation must not reveal inaccessible ancestors, resources, or policy details.
+
+## Boundaries and non-goals
+
+- This Capability is not another Page or Database role, a custom role builder, or a replacement for ordinary sharing and source authority.
+- It does not decide whether a request is truthful, appropriate for an audience, reversible, or subject to external confirmation; those are separate contracts.
+- It does not retain private context in a cache after consent or access changes, and it does not make a local device, vault, or provider available merely by recording consent.
+
+## Acceptance stories
+
+### Allow context without allowing edits
+
+Given a person can view a Page and its agent-context decision is allowed while its agent-edit decision is denied, when they ask an agent to summarize it and then ask the agent to rewrite it, then the summary may use the Page, the rewrite is denied before mutation, and no additional Page role has been created.
+
+### Respect an inherited ceiling
+
+Given a child resource allows agent context but an authorized parent policy denies it, when an agent attempts to retrieve the child, then the effective decision is denied, the child is not used, and an authorized policy editor can see that the parent ceiling prevailed without exposing unrelated private structure.
+
+### Stop on mid-run revocation
+
+Given an agent has begun an authorized multi-resource run, when context consent for one remaining resource is revoked, then the next read of that resource is denied, previously committed authorized changes remain attributable and recoverable, and the run neither reads cached private content nor reports an empty successful result.
+
+## Current evidence
+
+The shared architecture establishes access-before-computation and one Action surface in `templates/content/docs/product/architecture.md`. Current repository code contains access and collaboration substrate, but no evidence yet proves independent resource-level agent context/edit decisions, inherited consent ceilings, effective-decision explanations, or mid-run re-evaluation. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Add deterministic Action tests covering every combination of ordinary access, context consent, edit consent, source policy, and inherited ceilings; verify the result is an explicit allow, deny, or unavailable state.
+2. Exercise resource selection, search, traversal, agent context assembly, edits, bulk work, queued/recovered work, and provider-backed resources while consent changes; prove every path rechecks effective authority before use.
+3. Verify inherited decisions and explanation UI through the real interface, including child narrowing, parent denial, inaccessible ancestors, and policy changes.
+4. Verify Events/Revisions, receipts, recovery, and access-safe audit/history after allowed edits, denied writes, and mid-run revocation.
+
+## Open questions
+
+The storage representation for inheritable consent, the precise policy-editor vocabulary, and how a paused run offers its remaining authorized scope are implementation choices. They must preserve the separate decisions, narrowing-only inheritance, use-time re-evaluation, and non-leaking failures above.

package/corpus/templates/content/docs/product/capabilities/content.agent.skill-catalog.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.agent.skill-catalog"
+name: "Skills catalog"
+user_promise: "Governed reusable agent instructions and capabilities can be invoked against compatible Content targets"
+primary_user_job: "Reuse approved organizational know-how against the right target while seeing what it may do before it runs."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.agent.action-parity", "content.template.governance"]
+related_features: ["content.feature.put-your-organizations-know-how-to-work"]
+roadmap_boundary: "feature"
+acceptance_summary: "A Skill has stable identity, version, personal or workspace ownership, declared compatible targets, permissions, effect and mutation contract, preview, and specificity-first contextual ranking."
+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"
+---
+
+# Skills catalog
+
+## Why this exists
+
+Reusable guidance becomes dangerous when its scope and effect are invisible. A catalog makes durable know-how legible as a governed tool.
+
+## Example workflow
+
+An organization publishes a versioned meeting-summary Skill for project Pages. A member previews its declared inputs and effects, invokes it in agent chat, and sees a Version and Event receipt.
+
+## Product contract
+
+A Skill has stable identity, version, personal or workspace ownership, declared compatible targets, permissions, effect and mutation contract, preview, and specificity-first contextual ranking. Invocation uses agent chat and shared Actions with normal Versions and Events.
+
+## Boundaries and non-goals
+
+Template governance owns approval policy and action parity owns execution. This is not arbitrary hidden prompt injection, a secret capability grant, or universal auto-run.
+
+## Acceptance stories
+
+### Rank a compatible project skill
+
+Given two compatible Skills, when a project Page is focused, then the more specific authorized Skill ranks first and its scope is visible.
+
+### Preview a versioned skill before mutation
+
+Given a Skill proposes a mutation, when a person previews it, then the declared effect and required authority appear before any Action runs.
+
+## Current evidence
+
+No complete catalog identity, ranking, preview, execution, and receipt proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test personal and workspace Skills through versioning, compatibility selection, and effect display.
+2. Verify ranking, approval, denial, preview, invocation, Events, Versions, and revocation.
+3. Run agent-chat discovery with incompatible targets and accessible previews.
+
+## Open questions
+
+The version-promotion and organization approval workflow needs design.

package/corpus/templates/content/docs/product/capabilities/content.api.cms.md

@@ -0,0 +1,70 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.api.cms"
+name: "Content API and CMS"
+user_promise: "External clients and websites can use Content without a second, weaker product contract."
+primary_user_job: "Read or change an authorized Content object from another client and receive the same truthful result as the Content interface."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.agent.action-parity", "content.access.page-database"]
+related_features: []
+roadmap_boundary: "supporting"
+acceptance_summary: "A documented typed client surface invokes the same Actions as people and agents, preserves actor and origin, enforces current access and validation, and returns distinguishable success, denial, conflict, and failure outcomes."
+proof_requirements:
+  [
+    "Contract tests proving client calls route through named typed Actions rather than parallel CRUD",
+    "Authorization, validation, audit, idempotency, and error-state parity tests across interface, agent, and external client",
+    "End-to-end client workflow covering read, mutation, denied access, conflict, and receipt",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Content API and CMS
+
+## Why this exists
+
+CMS consumers need Content truth without a shadow datastore or a special permission lane.
+
+## Example workflow
+
+A site editor loads an authorized Page through a typed client, changes its title through an Action, and receives the same validation error or committed receipt they would see in Content.
+
+## Product contract
+
+- The API is a client of the shared typed Action surface; it does not expose route-shaped CRUD as a rival contract.
+- Each request resolves the acting identity and current access before reading, traversing, or mutating Content.
+- Mutations retain actor, origin, idempotency, validation, Events, history, and receipts. Unsupported, denied, conflict, and failed outcomes remain distinct.
+- Public reading is governed by publication and visibility contracts, not by an API key that bypasses them.
+
+## Boundaries and non-goals
+
+This is not a generic database proxy, a provider API replacement, or a promise that every internal Action is public. Publication owns public URLs; embeds own host grants.
+
+## Acceptance stories
+
+### Use the same mutation boundary
+
+Given an authorized external client, when it changes a Page through the typed Action, then Content applies the ordinary validation and records the client origin in the committed receipt.
+
+### Refuse a hidden record
+
+Given a client token without access to a Page, when it requests that Page or a Query containing it, then the result reveals neither the record nor its derived data.
+
+## Current evidence
+
+Donor evidence: `actions/` contains Content operations and shared Action use. No repository proof yet demonstrates a complete external typed client contract, parity matrix, or end-to-end CMS workflow; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define a public, versioned typed client boundary over selected Actions.
+2. Test authorization, validation, audit, idempotency, and error parity.
+3. Run a real client read/change/denial/conflict workflow and retain receipts.
+
+## Open questions
+
+- The initial authentication and client packaging boundary remains to be selected without creating a second authority model.

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

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.author.code"
+name: "Executable Code blocks"
+user_promise: "Let me author, inspect, and deliberately run code in an ordinary document without hidden notebook state."
+primary_user_job: "Author and run bounded code with explicit inputs and inspectable output."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.block", "content.author.media"]
+related_features: ["content.feature.build-new-surfaces"]
+roadmap_boundary: "feature"
+acceptance_summary: "Code blocks keep portable source and optional typed rendering or execution; runs are explicit, isolated, bounded, receipted, and their approved output can become stale."
+proof_requirements:
+  [
+    "Source/highlighting is universal; compatible renderers and runtimes are declared rather than inferred.",
+    "Run never happens on paste, load, collaboration, or public reading; each run pins explicit page-scoped source references.",
+    "Outputs are bounded handles with receipts; changing source or a referenced tab marks prior output stale without erasing history.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Executable Code blocks
+
+## Why this exists
+
+Code belongs beside an explanation, but ordinary document code must not inherit the hidden state, ambient authority, or unreadable output of a notebook. Authors need to see exactly what source was run, with which inputs, and whether a displayed result is still trustworthy.
+
+## Example workflow
+
+Ava adds a Mermaid Code block to a design Page, changes a referenced Code tab, and sees the prior approved diagram marked stale until a deliberate new run.
+
+## Product contract
+
+- Source/highlighting is universal; compatible renderers and runtimes are declared rather than inferred.
+- Run never happens on paste, load, collaboration, or public reading; each run pins explicit page-scoped source references.
+- Outputs are bounded handles with receipts; changing source or a referenced tab marks prior output stale without erasing history.
+
+## Boundaries and non-goals
+
+- `content.object.block` owns Code Block identity and portable source; renderer and runtime adapters add capabilities without changing that identity.
+- Code Blocks do not create an ambient kernel, execute on open/paste/public render, or turn successful runs into Custom Blocks automatically.
+
+## Acceptance stories
+
+### Reject ambient execution
+
+Given pasted JavaScript, when another collaborator or a public reader opens the Page, then no runtime starts.
+
+### Pin source inputs
+
+Given a run with referenced tabs, when one tab changes, then the receipt keeps the original revisions and the output becomes stale.
+
+## Current evidence
+
+`app/components/editor/extensions/CodeBlockNode.tsx` provides Lowlight Code source; no tabs, isolated runtime, receipts, or approved-output state exists.
+
+## Proof plan
+
+1. Test Source/Rendered/Console/Split capability gating.
+2. Run explicit tabs and verify hashes, stale invalidation, and cycles.
+3. Deny network, secrets, filesystem, DOM, worker, timeout, and oversized output.
+4. Test manual Run, preview rerun, saved output, export fallback, and fences.
+
+## Open questions
+
+First runtime scope is open; a shared notebook kernel is not.

package/corpus/templates/content/docs/product/capabilities/content.author.document-editor.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.author.document-editor"
+name: "Document editor"
+user_promise: "Write and revise a rich document with blocks, comments, collaboration, media, and agent help in one humane surface."
+primary_user_job: "Revise a shared rich document without losing structure or history."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.page", "content.object.blocks-field"]
+related_features: ["content.feature.durable-foundations"]
+roadmap_boundary: "feature"
+acceptance_summary: "The visual editor preserves canonical document content through edits, reloads, collaboration, comments, authorized agent changes, and export."
+proof_requirements:
+  [
+    "One visual document surface edits the canonical Blocks field and retains stable Page and block identity.",
+    "Agent proposals use the ordinary action, review, and history path; they are not a private inline editor.",
+    "Collaborators see reconciliation and failures honestly rather than silently losing edits.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Document editor
+
+## Why this exists
+
+Writing falls apart when the editor treats structure, comments, collaboration, media, and agent edits as separate temporary surfaces. A Page needs one humane place where those changes remain attributable and recoverable after the tab closes.
+
+## Example workflow
+
+Ravi turns a paragraph into a callout, anchors a Comment, accepts an agent edit, reloads, and finds both the block and comment anchor intact.
+
+## Product contract
+
+- One visual document surface edits the canonical Blocks field and retains stable Page and block identity.
+- Agent proposals use the ordinary action, review, and history path; they are not a private inline editor.
+- Collaborators see reconciliation and failures honestly rather than silently losing edits.
+
+## Boundaries and non-goals
+
+- `content.object.page` and `content.object.blocks-field` own identity and body history; Comments, media, and agent actions use their own shared contracts.
+- This does not add a raw-source editing mode, a second agent composer, or a private inline mutation engine.
+
+## Acceptance stories
+
+### Reconcile collaboration
+
+Given two editors change adjacent text while one is offline, when reconnecting, then no edit is silently lost.
+
+### Export canonical content
+
+Given media, comments, and an agent mutation, when export runs, then visible content reflects the canonical body.
+
+## Current evidence
+
+`app/components/editor/VisualEditor.tsx`, `DocumentEditor.tsx`, `actions/edit-document.ts`, and `actions/update-document.ts` are donors; a joined end-to-end workflow is unproved.
+
+## Proof plan
+
+1. Edit rich blocks and media then reload and compare canonical serialization.
+2. Test reconnect, anchors, and attribution.
+3. Compare UI and Action edits for access/history parity.
+4. Export mixed content with declared fallbacks.
+
+## Open questions
+
+A minimal real-interface collaboration script needs selection.

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.