@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.access.safe-aggregate.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.access.safe-aggregate"
+name: "Access-safe computation"
+user_promise: "Counts, rollups, groups, and aggregates reveal only records the viewer may access."
+primary_user_job: "Understand shared data without private records leaking through a total, relation count, or derived value."
+kind: "primitive"
+state: "exploring"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.access.page-database"]
+related_features: ["content.feature.understand-what-your-data-says"]
+roadmap_boundary: "feature"
+acceptance_summary: "Every derived computation filters inaccessible records and endpoints before traversal, grouping, measure calculation, caching, or rendering."
+proof_requirements:
+  [
+    "Relation traversal and count asymmetry repair",
+    "Access-first rollup, group, Pivot, Chart, and expression tests",
+    "No leakage through empty, error, cache, drill-down, or export states",
+    "Equivalent UI, Action, agent, and API results under changing access",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Access-safe computation
+
+## Why this exists
+
+A total can betray a secret as surely as a sentence can. Analytics must count the authorized world, not calculate privately and hide only the rows.
+
+## Example workflow
+
+A manager groups a pipeline by stage and drills into a total. Restricted opportunities are absent from both the count and the drill-down, even though authorized peers see a larger total.
+
+## Product contract
+
+- Access filters apply before relationship traversal, Query evaluation, grouping, rollup, count, measure, chart, pivot, expression, and export.
+- A result and its drill-down describe the same authorized input set.
+- Caches and precomputed indexes are implementation machinery and may not reveal an inaccessible cardinality or stale value.
+- Known inaccessible direct objects return denial; ambient derived work omits them without a side-channel.
+- UI, agents, APIs, and automations receive the same scoped result or typed failure.
+
+## Boundaries and non-goals
+
+- This record does not define query syntax, Chart presentation, or row-sharing controls.
+- It does not require hiding authorized zero results; a true zero remains meaningful.
+- Performance optimizations cannot weaken the access-before-computation ordering.
+
+## Acceptance stories
+
+### Count only visible relations
+
+Given a visible Page related to one visible and one private Page, when a viewer calculates a relation count, then it reports one and cannot infer the second endpoint from count, error, or timing behavior.
+
+### Drill into the same cohort
+
+Given a grouped aggregate with restricted rows, when a viewer opens drill-down, then every returned row and total matches the viewer-scoped aggregate rather than a wider cached cohort.
+
+## Current evidence
+
+The product architecture requires access before derived work, while the current audit identified relation-count asymmetry as a repair seam. No complete generic aggregate implementation proof exists; this capability remains `exploring`.
+
+## Proof plan
+
+1. Build adversarial fixtures for private rows/endpoints across counts, rollups, groups, expressions, pivots, charts, and exports.
+2. Compare results across UI, Actions, agents, APIs, cache refreshes, and changing access.
+3. Verify drill-down, pagination, empty/error states, and timing do not leak presence.
+4. Test source-backed values and concurrent access changes.
+
+## Open questions
+
+The evaluation and cache design are open. The access-first semantics and equal result/drill-down cohort are not.

package/corpus/templates/content/docs/product/capabilities/content.access.visibility-closure.md

@@ -0,0 +1,79 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.access.visibility-closure"
+name: "Visibility closure"
+user_promise: "Ambient traversal and derived results omit inaccessible objects while known direct links receive an honest denial."
+primary_user_job: "Follow, search, embed, publish, and export work without private neighborhoods spilling into view."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.access.page-database", "content.access.safe-aggregate"]
+related_features:
+  [
+    "content.feature.work-across-every-workspace",
+    "content.feature.publish-with-confidence",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "All ambient discovery and derived surfaces close over authorized objects; direct known targets fail honestly without revealing private existence or contents."
+proof_requirements:
+  [
+    "Traversal, search, Query, embedding, and export closure",
+    "Aggregate and relationship endpoint closure",
+    "Direct-link generic denial distinct from successful absence",
+    "Public, agent, source, cache, and access-change regression coverage",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Visibility closure
+
+## Why this exists
+
+Access must remain true after information starts moving. A private object cannot become visible merely because a backlink, embed, export, or agent happened to pass nearby.
+
+## Example workflow
+
+An author publishes a Page that references internal research. Public readers see the authorized Page with the private reference omitted or safely degraded; a person with the internal link gets a generic denial rather than a plausible empty success.
+
+## Product contract
+
+- Search, traversal, Queries, Views, links, embeds, exports, public projections, and agents operate only over authorized closure.
+- A direct known target may return a generic denial; ambient lists and derived results do not confirm its existence.
+- Closure applies recursively to relationship endpoints and transcluded content before rendering or calculating.
+- Caches, previews, snippets, errors, counts, and pagination preserve the same boundary.
+- Access changes take effect before future reads and cannot be masked as normal emptiness.
+
+## Boundaries and non-goals
+
+- Visibility closure is not a replacement for Page/Database roles or row principals.
+- It does not decide how a public Page is published, only what its reachable projections may reveal.
+- It does not require every broken public reference to be silently invisible; authorized degradation can be meaningful.
+
+## Acceptance stories
+
+### Omit a private neighbor from export
+
+Given a Page with a reference or transclusion to a private neighbor, when an unauthorized viewer exports or opens a public projection, then the neighbor's content, title, and cardinality do not leak.
+
+### Differentiate denial from absence
+
+Given an unauthorized person has a direct private URL, when they request it, then they receive an honest generic denial rather than a successful empty result that callers may mistake for normal absence.
+
+## Current evidence
+
+The architecture and existing access-aware Content paths establish the required direction. Repository evidence does not yet prove closure across every traversal, export, embed, cache, and agent path; this remains `approved_shape`.
+
+## Proof plan
+
+1. Test recursive references, Relationships, transclusions, Views, search, exports, and public output under access changes.
+2. Inspect snippets, counts, errors, caches, pagination, previews, and agent summaries for side channels.
+3. Verify direct denial versus ambient omission through UI and Actions.
+4. Exercise source and integration paths plus reload and concurrent permission changes.
+
+## Open questions
+
+Exact degraded-reference presentation remains open; it must never disclose protected identity or turn denial into false success.

package/corpus/templates/content/docs/product/capabilities/content.action.button.md

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.action.button"
+name: "Action Buttons"
+user_promise: "An owner-governed Button invokes an ordinary action or Rule with typed inputs and visible authority"
+primary_user_job: "Let people trigger a governed operation from the object where its result matters."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.command.fabric", "content.rule.deterministic"]
+related_features: ["content.feature.when-this-happens-that-follows"]
+roadmap_boundary: "feature"
+acceptance_summary: "Buttons are owner-governed command bindings with stable IDs, typed inputs, can-run reasons, confirmation, permission checks, receipts, and Undo where supported."
+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"
+---
+
+# Action Buttons
+
+## Why this exists
+
+A repeated local decision should be visible where people encounter its consequence, with authority and confirmation clear before anyone acts.
+
+## Example workflow
+
+A workspace owner adds an Approve button to a request Page. An editor sees its effect and required confirmation, invokes it, and receives an Event receipt with Undo when the action supports it.
+
+## Product contract
+
+Buttons are owner-governed command bindings with stable IDs, typed inputs, can-run reasons, confirmation, permission checks, receipts, and Undo where supported. They invoke the ordinary command or Rule Action; a Button never owns a private mutation path.
+
+## Boundaries and non-goals
+
+Button configuration and target Actions own behavior. This is not a macro language, hidden automation engine, or permission bypass.
+
+## Acceptance stories
+
+### Deny a button that cannot run
+
+Given an editor without the target Action permission, when they view a Button, then it explains why it cannot run and cannot invoke the operation.
+
+### Receipt and undo after approval
+
+Given a confirmed reversible Button action, when it succeeds, then Content records one ordinary Event and exposes its supported Undo route.
+
+## Current evidence
+
+Template and Action substrate exist, but no complete button insertion, authority, confirmation, receipt, and recovery proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Insert template Buttons and test stable bindings, arguments, and unavailable targets.
+2. Exercise viewer, editor, owner, confirmation, cancellation, denial, receipts, Undo, and reload.
+3. Use keyboard and screen readers to discover a Button, read its effect, and recover from failure.
+
+## Open questions
+
+The exact first Button placement and confirmation copy need interaction design.

package/corpus/templates/content/docs/product/capabilities/content.agent.action-parity.md

@@ -0,0 +1,73 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.agent.action-parity"
+name: "Agent and UI parity"
+user_promise: "Humans and agents use the same operations and visible state"
+primary_user_job: "Use an agent to do ordinary Content work with the same authority, validation, and truthful result a person would receive."
+kind: "primitive"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: []
+related_features:
+  [
+    "content.feature.durable-foundations",
+    "content.feature.when-this-happens-that-follows",
+    "content.feature.collect-structured-input",
+    "content.feature.work-on-content-inside-another-application",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Every operation exposes one typed Action contract for UI, agent, automation, and API callers."
+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"
+---
+
+# Agent and UI parity
+
+## Why this exists
+
+An assistant that succeeds where the editor would fail erodes trust in both surfaces. Content needs one accountable path from request to committed change.
+
+## Example workflow
+
+A person asks an agent to update a Database record. The agent calls the same Action as the editor, receives the same validation failure if it is invalid, and returns the canonical result.
+
+## Product contract
+
+Every operation exposes one typed Action contract for UI, agent, automation, and API callers. Authorization, validation, Events, history, recovery, current context, and error states are shared; caller-specific presentation cannot invent a privileged task engine.
+
+## Boundaries and non-goals
+
+Individual capability records own their concrete workflows. Parity does not mean identical interface affordances or unrestricted agent context.
+
+## Acceptance stories
+
+### Reject an agent-only privilege
+
+Given a viewer denied an edit in the UI, when an agent attempts the same edit, then the same Action denies it without leaking unavailable fields.
+
+### Observe one change from both surfaces
+
+Given an Action succeeds through an agent, when the Page is opened, then it shows one canonical mutation and ordinary history rather than an agent-only copy.
+
+## Current evidence
+
+Existing Actions provide in-progress donor substrate, but per-capability parity evaluations and real-interface proof remain incomplete. This Capability remains `in_progress`.
+
+## Proof plan
+
+1. Compare Page, Database, and collaboration Action inputs, results, and failures.
+2. Test permission changes, field visibility, history, conflict, and unavailable sources in both callers.
+3. Run paired human and agent workflows with accessible UI evidence.
+
+## Open questions
+
+The first cross-surface parity fixture catalog needs implementation design.

package/corpus/templates/content/docs/product/capabilities/content.agent.audience-safe.md

@@ -0,0 +1,91 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.agent.audience-safe"
+name: "Audience-safe synthesis"
+user_promise: "A governed agent run can synthesize from only the resources every intended viewer may access and consent to use for that audience."
+primary_user_job: "Prepare a shared answer for a defined audience without borrowing an owner's private authority or silently carrying excluded material into the result."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  ["content.agent.resource-consent", "content.access.visibility-closure"]
+related_features: ["content.feature.keep-your-private-vault-private"]
+roadmap_boundary: "feature"
+acceptance_summary: "A strict-audience run resolves its inputs through the intended audience's common authorized-and-consented intersection, rechecks it throughout the run, and never exposes excluded inputs through output, cache, metadata, or errors."
+proof_requirements:
+  [
+    "Audience identity and common authorized-and-consented input intersection resolved before retrieval and at every subsequent use",
+    "Strict-audience behavior that never borrows owner, author, agent, or cached private authority",
+    "Cache keys, invalidation, output handling, errors, counts, and provenance that cannot reveal excluded inputs",
+    "Real-interface workflow tests for changing audience membership, access, consent, source availability, and direct inspection",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Audience-safe synthesis
+
+## Why this exists
+
+An author can often see more than the people who will receive an agent's answer. Summarizing with the author's authority and then sharing the result can leak the very material the audience was not allowed to see. A warning after generation is too late; a careful-looking answer may already contain the private detail.
+
+Audience-safe synthesis is a workflow over resource consent and access closure. It constrains the run's inputs to the common intersection for its stated audience before the agent reasons over them.
+
+## Example workflow
+
+A project lead asks for a status update for three collaborators. The agent resolves the intended audience, then gathers only project resources that all three collaborators can access and that are consented for agent context. A private planning note and a resource one collaborator lost access to are excluded. When a fourth collaborator is added during the run, the remaining work is re-evaluated against the smaller intersection. The agent can state that its answer is based on the permitted shared material, but it does not name or count excluded inputs.
+
+## Product contract
+
+### Audience-bound input closure
+
+- A strict-audience run names an intended audience and evaluates every candidate input as the intersection of that audience's current ordinary authorization and effective agent-context consent, including resource, source, and inherited policy ceilings.
+- The run may use only inputs in that common intersection. It does not borrow the initiating owner's, author's, operator's, or agent's broader authority to fill a gap.
+- Audience changes, access changes, consent revocation, source-policy changes, and unavailable authority state are re-evaluated before each remaining retrieval, tool call, context reuse, and output-affecting step. Unreadable authority state is not treated as an empty allowed intersection.
+- Strict-audience mode is an opt-in governed workflow. It may produce a narrower answer, a truthful unavailable state, or a request to revise the audience; it may not silently broaden the audience or switch to owner-authority mode.
+
+### Outputs, caches, and provenance
+
+- Excluded inputs cannot appear in generated output, citations, snippets, titles, tool traces, error messages, counts, timing summaries, or aggregate explanations. The output may identify its declared audience and describe authorized-source limitations only when doing so does not reveal excluded material.
+- Cached retrievals, intermediate context, embeddings, plans, and generated results are scoped to the exact audience/access/consent state that authorized them. Access or consent revocation invalidates them for affected viewers; an owner-private cached result is never reused for a strict-audience run.
+- The workflow records run identity, declared audience representation, policy mode, and safe provenance needed for inspection. Origin/provenance says where an authorized result came from; it is not a review, verification, or truth guarantee.
+- Audience-safe synthesis does not prove that its answer is complete, correct, endorsed, or fit for publication. Review and verification remain separate decisions.
+
+## Boundaries and non-goals
+
+- This is not a new sharing model, an audience-wide permission grant, a way to make private resources public, or an alternative to resource consent/access closure.
+- It does not make an agent's summary authoritative, verified, or approved merely because the input intersection was safe.
+- It does not disclose the identity, existence, count, or cached remnants of resources excluded by access or consent.
+- It does not authorize owner-credential fallbacks, privileged cache reuse, or source reads outside the audience's effective closure.
+
+## Acceptance stories
+
+### Synthesize only from the common intersection
+
+Given an author can access three resources and one intended viewer cannot access one of them, when a strict-audience run creates a status update for that audience, then it uses only the two common authorized-and-consented resources and does not mention the excluded resource or its absence.
+
+### Re-evaluate a changing audience
+
+Given a strict-audience run is gathering material for two viewers, when another viewer is added or a current viewer loses access before the next retrieval, then the run re-evaluates the remaining input closure and neither uses newly excluded context nor reuses a broader cached result.
+
+### Preserve the distinction between provenance and review
+
+Given a strict-audience run produces an answer with safe authorized provenance, when a recipient opens it, then they can inspect permitted origin information appropriate to their access but do not see a claim that the result was reviewed, verified, or true unless another Capability supplied that decision.
+
+## Current evidence
+
+`content.agent.resource-consent` and `content.access.visibility-closure` define required dependencies, but neither is verified as a complete implementation. Current architecture establishes access before computation in `templates/content/docs/product/architecture.md`; no repository evidence yet proves an intended-audience intersection resolver, strict-mode cache partitioning/invalidation, or non-leaking output behavior across agent tools. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Build deterministic resolver tests for multi-viewer intersections across Pages, Databases, Sources, inherited consent ceilings, membership changes, revocation, and authority-read failures.
+2. Verify agent retrieval, search, traversal, tool calls, aggregation, citations, error rendering, and final output use the same strict context and cannot observe excluded identity or counts.
+3. Test cache and intermediate-artifact keys against audience identity, membership/access epoch, consent epoch, source policy, and resource version; prove revocation and audience change invalidate unsafe reuse.
+4. Run real-interface workflows that define an audience, generate a result, alter its membership/access/consent mid-run, inspect safe provenance, and confirm that review/verification status remains distinct.
+
+## Open questions
+
+The durable representation of a dynamic audience, safe wording for partial-result notices, and retention rules for run intermediates remain open implementation choices. They must not weaken common-intersection input selection, strict cache isolation, or the distinction between safe provenance and verification.

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

@@ -0,0 +1,67 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.agent.automation"
+name: "Agent-run automation"
+user_promise: "AI work composes Event → expression/query → action → mutation → Event"
+primary_user_job: "Automate bounded AI work while preserving an accountable owner, visible context, and a recoverable causal chain."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.rule.deterministic", "content.agent.action-parity"]
+related_features: ["content.feature.when-this-happens-that-follows"]
+roadmap_boundary: "feature"
+acceptance_summary: "An agent automation consumes an Event, evaluated expression or Query, scoped context, and typed Action."
+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"
+---
+
+# Agent-run automation
+
+## Why this exists
+
+AI work can travel farther than its initiator intended. Its boundaries must remain inspectable, stoppable, and attributable.
+
+## Example workflow
+
+A Rule detects a new intake record, prepares an owner-scoped brief, and creates a draft through a shared Action. The run shows its inputs, cost limit, resulting Event, and disable control.
+
+## Product contract
+
+An agent automation consumes an Event, evaluated expression or Query, scoped context, and typed Action. Owner authority, dry run, chain and cost limits, receipts, disablement, and supported Undo apply to every run.
+
+## Boundaries and non-goals
+
+Deterministic Rules own non-AI behavior and Action parity owns mutations. This is not background prompt execution without an owner or an unbounded self-triggering loop.
+
+## Acceptance stories
+
+### Stop a self-triggering chain
+
+Given a run reaches its chain limit, when it would emit another triggering Event, then Content stops it and records an explicit limit receipt.
+
+### Preview an owner-scoped draft
+
+Given a dry run, when the automation evaluates its context, then it returns proposed Actions and changes no canonical object.
+
+## Current evidence
+
+No complete owner, context, limit, dry-run, receipt, and recovery proof is recorded. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test owner delegation and revocation with bounded context, dry runs, and effect previews.
+2. Drive chains through duplicate triggers, limits, Action failure, and disablement.
+3. Inspect receipts, retry state, supported Undo, and accessible supervision.
+
+## Open questions
+
+Cost accounting and the first safe context-preview surface need design.

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.