@agent-native/core 0.130.2 → 0.131.3

package/corpus/templates/content/docs/product/capabilities/content.agent.expression-authoring.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.agent.expression-authoring"
+name: "Agent-authored Expressions"
+user_promise: "Ask an agent to draft or repair a typed expression without giving it a private execution or save path."
+primary_user_job: "Collaborate on a validated expression before saving it."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.expression.language", "content.agent.action-parity"]
+related_features: ["content.feature.put-your-organizations-know-how-to-work"]
+roadmap_boundary: "feature"
+acceptance_summary: "The agent inspects authorized live schema and expression context, produces a typed candidate, validates and previews it, explains failures, and saves only through an explicit authorized action."
+proof_requirements:
+  [
+    "The agent uses the same expression language, validators, permissions, and mutation receipts as a person.",
+    "A candidate remains a preview until the user or authorized workflow explicitly saves it.",
+    "Missing schema, denied data, type errors, and unsafe dependencies are named failures, not invented expressions or successful empty previews.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Agent-authored Expressions
+
+## Why this exists
+
+An agent can make configuration more approachable, but a plausible-looking formula based on invented schema is worse than no formula. Its suggestions need the same evidence, preview, and save boundary as human-authored work.
+
+## Example workflow
+
+Sam asks for an overdue formula; the agent inspects authorized fields, previews dependencies, repairs an error, and saves only after confirmation.
+
+## Product contract
+
+- The agent uses the same expression language, validators, permissions, and mutation receipts as a person.
+- A candidate remains a preview until the user or authorized workflow explicitly saves it.
+- Missing schema, denied data, type errors, and unsafe dependencies are named failures, not invented expressions or successful empty previews.
+
+## Boundaries and non-goals
+
+- `content.expression.language` owns parsing, typechecking, preview semantics, and persistence; the agent is an authorized client of that contract.
+- Agent authoring does not invent schema, bypass confirmation, or persist speculative candidates.
+
+## Acceptance stories
+
+### Refuse invented schema
+
+Given a target is denied or deleted, when the agent reads its schema, then it reports it instead of guessing.
+
+### Save only deliberately
+
+Given a correct preview is declined, when Sam closes it, then no field changes; accepted save creates a normal receipt.
+
+## Current evidence
+
+`actions/configure-document-property.ts` and the action framework donate mutation seams; no authorized schema/agent preview action exists.
+
+## Proof plan
+
+1. Draft from live authorized schema and inspect AST/bindings/dependencies.
+2. Test type, cycle, denied, and unavailable failures without persistence.
+3. Compare agent and human preview diagnostics.
+4. Save, reject, and repair with receipt/history parity.
+
+## Open questions
+
+No product question remains.

package/corpus/templates/content/docs/product/capabilities/content.agent.presence.md

@@ -0,0 +1,103 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.agent.presence"
+name: "Agent presence"
+user_promise: "One accountable agent presence gives authorized collaborators an ephemeral view of a run's current locations without replacing durable attribution, review, or the real mutation."
+primary_user_job: "See where an active agent run is working right now, including concurrent locations, without exposing private work or mistaking a live indicator for history or approval."
+kind: "surface"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.agent.action-parity", "content.event.committed"]
+related_features: ["content.feature.collaborate-in-context"]
+roadmap_boundary: "feature"
+acceptance_summary: "Authorized collaborators can see one ephemeral presence for an accountable active run and its currently authorized locations; presence may degrade or fail without delaying an authorized mutation, while Events/History retain durable attribution and review state."
+proof_requirements:
+  [
+    "A run-scoped presence model that represents one run across multiple current locations and removes inaccessible locations per viewer",
+    "Lifecycle proof for starting, progressing, stopping, canceling, failure, completion, linger/expiry, and concurrent locations",
+    "Best-effort transport/storage behavior proving presence failure neither blocks nor reclassifies an authorized mutation",
+    "Real-interface and access tests that distinguish live presence from Events, History, review, and reversible change",
+  ]
+evidence:
+  [
+    "packages/core/src/collab/agent-presence.ts",
+    "packages/core/src/collab/agent-presence.spec.ts",
+    "packages/core/src/collab/awareness-store.ts",
+    "packages/core/src/collab/ydoc-manager.ts",
+    "packages/toolkit/src/collab-ui/AgentPresenceChip.tsx",
+  ]
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Agent presence
+
+## Why this exists
+
+Live collaboration benefits from a small, current-state answer to “where is the agent working?” That answer is not the same as attribution, history, a review decision, or an audit record. Treating a transient cursor as any of those would make important work disappear with the network.
+
+Agent presence therefore visualizes the present moment over an accountable run. Events, Revisions, Versions, receipts, and History remain the durable record of who changed what and what was reviewed.
+
+## Example workflow
+
+An agent run updates two authorized Pages and a structured record. Collaborators who can access each location see one running agent with the applicable current locations and short-lived recent-edit cues. A collaborator without access to one Page sees only the locations they may access. If the presence channel drops, the authorized mutations still commit through the normal action path and later appear in History. Stopping a run prevents further work; canceling ends pending work; reverting is a later, separate authorized change to committed results.
+
+## Product contract
+
+### Ephemeral, run-scoped current state
+
+- One accountable run has one presence identity and may report multiple simultaneous current locations. A location is a current working target, not a durable claim that every prior change belongs to the viewer's visible activity feed.
+- Presence is ephemeral and may linger briefly to make a just-completed change legible, then expires. Completion, failure, loss of transport, or process restart never erase the durable Events/History produced by real actions.
+- A viewer sees only locations and descriptors they are currently authorized to access. Hidden, revoked, or inaccessible locations are omitted without names, counts, ordering gaps, or other existence leaks.
+- Presence describes activity, not review state. It does not mark a change accepted, rejected, verified, reverted, or recoverable; those meanings belong to durable Events, Revisions, Versions, and their owning surfaces.
+
+### Lifecycle and mutation independence
+
+- Starting, progressing, completing, failing, stopping, and canceling a run have distinct current-state semantics. **Stop** requests no further work; **cancel** ends pending work according to the run contract; **revert** is a separate, authorized mutation over already committed work and does not mean that presence was stopped.
+- Presence publication, cross-instance mirroring, polling, and expiry are best effort. Their failure must not block, delay, roll back, or falsely report failure for an otherwise authorized real mutation.
+- An action may update presence before, during, or after its mutation, but its durable Event/Revision and result must not depend on presence transport success. A failed mutation must not leave a convincing active or completed presence state; the run reports its actual terminal condition when known.
+- A run that loses access to a location removes it from future presence projection and cannot use that loss as permission to continue work there.
+
+## Boundaries and non-goals
+
+- Presence is not a generic agent activity panel, run history, audit log, review queue, approval mechanism, or substitute for Events/Versions/History.
+- It does not expose per-character imitation as the primary collaboration model, and it does not make lingering visual cues durable attribution.
+- It does not broaden access, reveal inaccessible locations, guarantee delivery, or change a mutation's authorization/recoverability semantics.
+- It does not define stop, cancellation, rollback, or recovery mechanics beyond presenting their current run state accurately.
+
+## Acceptance stories
+
+### Show one run in several authorized locations
+
+Given one active agent run is modifying two Pages and a record that a collaborator can access, when the collaborator opens the relevant surfaces, then they see one run-scoped presence with its authorized current locations rather than separate unaccountable agents or a fabricated single location.
+
+### Hide private concurrent work
+
+Given the same run also works in a Page the collaborator cannot access, when presence updates arrive, then the collaborator sees no title, count, timing clue, placeholder, or recent-edit descriptor for that Page while authorized viewers can see their permitted projection.
+
+### Keep mutation truth durable when presence fails
+
+Given an authorized agent mutation succeeds while the presence mirror or poll transport fails, when the action completes, then the mutation result and durable Event/History remain available, the UI reports presence degradation truthfully if observable, and no mutation waits for presence to recover.
+
+### Keep stopping, canceling, and reverting distinct
+
+Given a run has committed one change and has later work pending, when a user stops it, cancels it, or separately reverts the committed change, then each operation has its own status and Event behavior; reverting does not claim the run was canceled, and canceling does not silently undo committed work.
+
+## Current evidence
+
+There is meaningful but narrower substrate. `packages/core/src/collab/agent-presence.ts` maintains per-document agent awareness, heartbeat, reference-counted enter/leave, lingering removal, and recent-edit metadata; `packages/core/src/collab/agent-presence.spec.ts` exercises those lifecycle details. `packages/core/src/collab/ydoc-manager.ts` automatically touches agent presence for agent-sourced collaborative writes. `packages/core/src/collab/awareness-store.ts` mirrors awareness best-effort and explicitly prevents presence failures from failing an edit. `packages/toolkit/src/collab-ui/AgentPresenceChip.tsx` provides a small reusable display component.
+
+This substrate is document-scoped, uses one agent client identity, and does not yet prove accountable run identity, multi-location aggregation, viewer-specific location filtering, terminal-state semantics, or a Content UI that distinguishes presence from durable attribution and review. The Capability therefore remains `in_progress`.
+
+## Proof plan
+
+1. Introduce deterministic run-scoped presence tests for one run across concurrent Pages/records, nested work, terminal states, linger/expiry, restart, and transport loss.
+2. Exercise access changes and viewer-specific projections across every presence surface; prove inaccessible locations and descriptors cannot leak through labels, counts, timing, events, or caches.
+3. Fault-inject awareness persistence, polling, and client rendering while running authorized mutations; prove action result, committed Event/Revision, and recovery semantics remain independent.
+4. Complete real-interface flows for active work, multiple locations, stop, cancel, failure, completion, and revert; verify the UI routes inspection/review/history to their durable surfaces instead of presence.
+
+## Open questions
+
+The exact run/location data shape, UI placement, stale indicator language, and cross-device aggregation strategy remain open. They must preserve one accountable ephemeral presence, access-safe projection, distinct terminal operations, and durable attribution outside the presence channel.

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.