@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.template.update.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.template.update"
+name: "Template updates"
+user_promise: "Review what changed in a template and selectively bring compatible improvements into my owned instance."
+primary_user_job: "Selectively apply template improvements without losing local work."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.template.graph", "content.diff.in-place"]
+related_features: ["content.feature.evolve-systems-safely"]
+roadmap_boundary: "feature"
+acceptance_summary: "Template instances never auto-update; they show a structural, typed, provenance-aware diff and permit dependency-safe selective apply or reset while preserving local additions."
+proof_requirements:
+  [
+    "An update compares the pinned/adopted source version with the proposed version and identifies affected objects, formulas, Rules, Views, and dependencies.",
+    "The owner chooses follow, pin, selectively apply, or reset; local additions remain unless the owner deliberately removes them.",
+    "Partial apply is dependency-safe, receipt-backed, previewed for impact, and never a silent remote overwrite.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Template updates
+
+## Why this exists
+
+A template improvement is useful only if an instance owner can see its consequences before accepting it. Remote changes must not overwrite the local adaptations that made the template fit real work.
+
+## Example workflow
+
+Kai reviews a template update, applies a formula but not a view, and keeps a locally added property untouched.
+
+## Product contract
+
+- An update compares the pinned/adopted source version with the proposed version and identifies affected objects, formulas, Rules, Views, and dependencies.
+- The owner chooses follow, pin, selectively apply, or reset; local additions remain unless the owner deliberately removes them.
+- Partial apply is dependency-safe, receipt-backed, previewed for impact, and never a silent remote overwrite.
+
+## Boundaries and non-goals
+
+- `content.template.graph` owns source/instance graph identity and `content.diff.in-place` owns review presentation; this record owns update notice, impact, and selective apply/reset.
+- Updates never auto-apply, overwrite local additions silently, or use a remote version as a new permission authority.
+
+## Acceptance stories
+
+### Never auto-update
+
+Given a new approved version, when an owner opens the instance, then instance remains pinned until owner acts.
+
+### Require dependencies
+
+Given selected change needs a property, when the owner applies it, then Content applies it or explains why partial apply cannot commit.
+
+## Current evidence
+
+`docs/product/features/content.feature.evolve-systems-safely.md` records donors; typed graph diff/impact/apply/recovery are absent.
+
+## Proof plan
+
+1. Diff graph versions including formulas, Rules, views, dependencies.
+2. Preview consumers and local additions.
+3. Selectively apply/reset with receipts/recovery.
+4. Test conflicts, denial, and retry without overwrite.
+
+## Open questions
+
+Conflict presentation and reset granularity remain open.

package/corpus/templates/content/docs/product/capabilities/content.time.types.md

@@ -0,0 +1,85 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.time.types"
+name: "Dates, times, and durations"
+user_promise: "Date, Instant, ranges, Duration, and explicit timezone conversion"
+primary_user_job: "Represent time accurately for the meaning I intend and see its conversion, filtering, rendering, and export without silent timezone drift."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.property.typed"]
+related_features:
+  [
+    "content.feature.data-that-keeps-itself-right",
+    "content.feature.plan-work-across-time",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Typed Date, Instant, ranges, Duration, and explicit timezone conversion preserve distinct semantics through storage, filters, rendering, Actions, and export."
+proof_requirements:
+  [
+    "Date-only, instant, range, duration, timezone, validation, storage, and round-trip coverage",
+    "Filter, sort, expression, renderer, Action, export, import, and agent-context semantic coverage",
+    "DST, locale, invalid value, missing zone, reload, and recovery workflows",
+  ]
+evidence:
+  [
+    "../../../app/components/editor/database/calendar-timeline.ts",
+    "../../../app/components/editor/DocumentDatabase.test.ts",
+  ]
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Dates, times, and durations
+
+## Why this exists
+
+“Tuesday” and “Tuesday at 09:00 in a zone” are different promises. Content must retain
+that difference from storage to a person reading an export months later.
+
+## Example workflow
+
+An editor records a date-only deadline and a zoned meeting instant, filters both in a
+Timeline, travels to another timezone, and exports them with their distinct meaning intact.
+
+## Product contract
+
+- Date, Instant, range, Duration, and timezone are typed values with non-interchangeable semantics.
+- Date-only values do not acquire a hidden timezone; Instants retain an explicit conversion context.
+- Filters, sorts, expressions, renderers, Actions, import/export, and agents preserve the declared type.
+- Invalid, ambiguous, missing-zone, stale, and unavailable values are explicit rather than coerced into success.
+
+## Boundaries and non-goals
+
+Typed Properties own general value storage. This is not a calendar provider, scheduling
+policy, or permission model.
+
+## Acceptance stories
+
+### Preserve a date-only value
+
+Given a date-only deadline, when a viewer changes timezone and filters or exports it,
+then Content retains the same calendar date rather than shifting it as an Instant.
+
+### Convert an Instant explicitly
+
+Given a zoned meeting Instant, when a viewer changes display timezone, then its displayed
+local time changes by explicit conversion while its stored instant and history remain stable.
+
+## Current evidence
+
+`calendar-timeline.ts` and Database tests provide date-window donor behavior. They do
+not prove the complete typed storage, timezone, expression, import/export, and recovery
+contract; this Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test every type through validation, storage, round trip, filters, sorts, and expressions.
+2. Verify rendering, Actions, import/export, agents, and type-preserving history.
+3. Exercise DST, locale, invalid/missing zone, reload, unavailable input, and recovery workflows.
+
+## Open questions
+
+The serialized interchange representation and display-zone preference policy need design.

package/corpus/templates/content/docs/product/capabilities/content.version.branching.md

@@ -0,0 +1,151 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.version.branching"
+name: "Named Page Versions"
+user_promise: "Multiple named body versions evolve in parallel under one Page identity and shared properties"
+primary_user_job: "Explore and review a substantial alternative without disturbing the current Page or splitting the work across duplicate Pages."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.version.field-history", "content.diff.in-place"]
+related_features:
+  [
+    "content.feature.living-references",
+    "content.feature.explore-alternatives-safely",
+    "content.feature.read-and-annotate-anything",
+    "content.feature.publish-with-confidence",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "One Page can hold named alternative bodies with narrower access, independent history, in-place comparison and selective merge, explicit canonical promotion, Version-aware collaboration, and lossless recovery."
+proof_requirements:
+  [
+    "Stable Page and Version identity with shared title, Properties, sharing ceiling, and Discussion",
+    "Independent body history, in-place compare, bidirectional selective merge, durable review decisions, and canonical promotion",
+    "Version-aware Comments, Discussion, Annotations, receipts, search, agents, publication, and exports under access intersection",
+    "Archive, restore, failure recovery, and lossless round-trip of the Version graph",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Named Page Versions
+
+## Why this exists
+
+People need to explore a meaningful alternative without changing the current or published work before the alternative is ready. Copying the Page solves isolation by breaking everything else: identity, Properties, access, Discussion, source provenance, and history drift into parallel objects.
+
+Named Versions keep the work on one Page. They add deliberate alternative bodies and review workflows above ordinary Blocks-field history; they do not turn every autosave into a branch.
+
+## Example workflow
+
+A team has a published article and wants to attempt a larger rewrite. An editor creates a private Version called `Rewrite`, leaves Comments for an agent, and lets the agent edit that Version while the canonical article remains unchanged. The team compares `Rewrite` with the current Version inside the ordinary Page interface, accepts some changes and rejects others, then promotes `Rewrite` when it is ready. The former current Version remains intact and addressable, and publication stays pinned until someone explicitly updates it.
+
+## Product contract
+
+### One Page, deliberate alternatives
+
+- The Page retains one stable ID and URL across every Version.
+- The Page title, top-level Properties, Database memberships, source identity, and sharing boundary remain Page-owned and common across Versions.
+- Each named Version has stable identity, a human label, Version-specific body state, its own revision history, and a place in the Page's Version graph.
+- Exactly one authorized Version is current or canonical. Promoting another Version changes that pointer; it does not overwrite or delete the former current Version.
+- A named Version is not an Event, logical Revision, recovery snapshot, duplicate Page, source representation, or publication. Those concepts may refer to a Version but retain their own identities and lifecycles.
+- Ordinary Blocks-field history continues independently beneath every named Version and exists even on Pages that never create an alternative.
+
+### Versions in the ordinary Page interface
+
+- Opening Versions changes the normal Page surface. Selecting a Version renders that body in the ordinary editor rather than in a separate diff application.
+- Comparing two authorized Versions shows typed differences in place while retaining unchanged context.
+- Review may accept or reject one change, all currently visible changes, or a safe filtered set. Compatible changes may move in either direction.
+- Accepted and rejected decisions persist immediately with actor, origin, and Version context. Retrying an already-applied decision is idempotent.
+- Selective merge does not collapse the two Version identities. Each body and its history remain independently addressable afterward.
+- If either side changes after a comparison was prepared, Content shows a stale, refresh, rebase, or typed conflict state. It never silently applies a change against a different base or converts a failed comparison into `no differences`.
+
+### Collaboration stays with the Page
+
+- A Page has one Discussion across all Versions. It is not cloned per alternative.
+- A Discussion message records the named Version and exact Revision/Event cursor visible when it was posted. The shared feed may be filtered to the current Version or all authorized Versions.
+- Replies inherit the root message's Version scope. A person who cannot access a private Version cannot infer its messages through counts, unread state, participants, notifications, search, summaries, or agents.
+- Comments remain Page-owned and target stable Blocks, precise ranges, the named Version and Revision, and quoted fallback context. Deleting or replacing the target text never deletes the Comment.
+- Annotations retain exact Version and source-revision context. Ordinary edits may relocate an anchor within that Version; sibling Versions never inherit it silently.
+- A filtered visible set of Comments or Annotations may be carried to another Version. Preview distinguishes exact matches, proposed relocations, and unresolved anchors. Accepting a mapping adds a destination target to the same contribution identity and preserves the original target and conversation.
+- Execution receipts and other Version-aware contributions keep the Version context visible when reviewed later.
+
+## Access and publication
+
+- Versions inherit Page access by default. A named Version may restrict access to fewer people but can never be shared more broadly than its Page.
+- Effective authority is the intersection of Page access and the Version restriction. Page identity and top-level Properties remain visible according to Page access; the Version body, history, diffs, attachments, receipts, and Version-scoped contributions inherit the narrower boundary.
+- Inaccessible Versions are absent from ambient discovery. Their labels, participants, counts, backlinks, Query membership, search results, notifications, summaries, and agent context do not leak.
+- A known opaque Version link returns an honest access-denied state without exposing private metadata and may offer the normal request-access path when policy permits.
+- Search, Queries, references, embeds, agents, compare, merge, export, and source synchronization apply Version access before reading or computing.
+- Ordinary Revisions inherit their named Version's access and are not independently shareable.
+- Publication is separately pinned to an explicitly selected Version and exact Revision. Promoting the collaborative current Version does not silently alter what is public.
+
+## Promotion, archive, recovery, and export
+
+- Promotion requires the relevant edit/structural authority, commits atomically, and leaves exactly one current Version.
+- The replaced current Version remains a normal alternative with its body, history, access, and collaboration anchors intact.
+- Non-current Versions can be archived and restored without changing stable identity or losing history.
+- Recovery failures cannot leave a half-promoted state or a Page with ambiguous current identity.
+- A lossless Content archive preserves authorized Version identities, graph/ancestry information, bodies, per-field history, Discussion, Comments, Annotations, receipts, access metadata, provenance, and assets or stable handles.
+- Static or compatibility exports resolve as the acting user. They include only authorized material and report unresolved dependencies rather than silently presenting an incomplete export as complete.
+
+## Boundaries and non-goals
+
+- Named Versions do not replace per-Blocks-field revision history, Undo, recovery snapshots, or queryable History.
+- Versions is the product surface; typed diffs, filtered review, merge, and comparison are modes or supporting capabilities beneath it.
+- Creating a Version does not duplicate the Page, title, Properties, membership, source identity, or Discussion.
+- Publication state is not inferred from which Version is current.
+- Comments and Annotations are not copied automatically into sibling Versions. Carry-forward is an explicit, provenance-preserving operation.
+- This Capability does not define a second permission, event, Action, or export engine.
+
+## Acceptance stories
+
+### Work privately beside a stable canonical body
+
+Given a Page with a current Version, when an editor creates a restricted `Rewrite` Version and changes its body, then the Page ID, title, Properties, memberships, sharing ceiling, and Discussion remain common while the current body's content remains unchanged.
+
+### Compare and merge without destroying either alternative
+
+Given two authorized Versions containing typed Block additions, edits, moves, and deletions, when a reviewer compares them in the normal Page interface and accepts only selected changes, then only those compatible changes move, both Version identities remain, and every decision has durable attribution. Retrying an accepted decision does not duplicate it.
+
+### Promote without publishing by accident
+
+Given a public artifact pinned to Version A at revision R, when an authorized editor promotes Version B to current, then B becomes the sole collaborative current Version, A remains addressable, and the public artifact remains pinned to A/R until explicitly updated.
+
+### Keep private Versions truly private
+
+Given a Page viewer without access to restricted Version B, when they open Discussion, search, run a Query, ask an agent, follow an embed, inspect notifications, compare Versions, or export the Page, then neither B nor its derived counts, labels, participants, content, or contributions are disclosed. A known direct link yields only an honest denial.
+
+### Carry forward research without losing its origin
+
+Given a filtered Annotation rail containing exact, relocatable, and unresolved anchors from Version A, when an authorized person chooses **Carry visible to this version** for Version B and accepts a subset, then accepted contributions gain B targets with mapping provenance, unresolved anchors remain unresolved, and every original A target and conversation stays intact.
+
+### Recover the complete Page state
+
+Given a Page with several Versions, independent Blocks-field histories, archived alternatives, Version-scoped collaboration, and assets, when an authorized lossless export is restored, then stable Page and Version identities, current designation, bodies, access, histories, anchors, receipts, and authorized dependencies remain coherent.
+
+## Current evidence
+
+Content currently preserves whole-document snapshots and can restore earlier title/body state. Those snapshots are useful recovery donor machinery, not named Versions: they do not prove stable alternative identities, parallel bodies, Version-specific access, a revision graph, in-place selective merge, promotion, or Version-aware collaboration. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Create, rename, edit, compare, merge, promote, archive, restore, and address named Versions through both the interface and shared Actions.
+2. Verify Page-shared title, Properties, memberships, source identity, access ceiling, and Discussion while independently editing Version bodies and Blocks-field histories.
+3. Exercise additions, deletions, moves, structured Blocks, partial review, all-visible review, retries, stale bases, incompatible dependencies, concurrent promotion, and persistence failure.
+4. Verify Discussion, Comments, Annotations, receipts, carry-forward, orphan recovery, and exact Version/Revision links across ordinary edits and promotion.
+5. Run the complete access matrix through direct reads, search, Queries, counts, notifications, references, embeds, agents, comparisons, publication, and exports.
+6. Round-trip a lossless archive and verify stable identity, current state, access, histories, collaboration, provenance, and authorized assets.
+7. Complete the Feature workflow through the real Page UI with keyboard and assistive technology, not only schema or Action tests.
+
+## Open questions
+
+- A named Version's exact payload still needs one decision: the primary body only, every Page-owned Blocks field, or an explicitly selected set. Whatever is chosen must not overload Versions to represent separate media/source formats.
+- Branch-from rules, ancestry representation, naming collisions, rename behavior, and whether merge creates a distinct graph node remain open.
+- Dependency behavior for partially accepting structurally dependent changes needs a precise oracle.
+- Concurrent promotion and archiving/restoring the current Version need atomic rules.
+- The exact portable Markdown/MDX representation of several named Versions and per-field histories remains open even though the lossless archive obligation is settled.
+- Version-specific role grammar, carry-forward authority, anchor relocation thresholds, and the detailed filter/re-anchor controls remain product decisions.

package/corpus/templates/content/docs/product/capabilities/content.version.field-history.md

@@ -0,0 +1,103 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.version.field-history"
+name: "Blocks-field revision history"
+user_promise: "Every Blocks field preserves attributable comparison and recovery independently of later named Page Versions."
+primary_user_job: "Understand, compare, and recover how any rich-content field changed without turning every edit into a named alternative."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.object.blocks-field", "content.event.committed"]
+related_features:
+  [
+    "content.feature.durable-foundations",
+    "content.feature.explore-alternatives-safely",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Every editable Blocks field retains stable Block identity, attributable causal Revisions, comparison, and recovery across ordinary editing and named-Version operations."
+proof_requirements:
+  [
+    "Independent attributable revision history for every Blocks field",
+    "Stable Block and field identity through edits, reorder, deletion, and recovery",
+    "Causal Revision grouping distinct from Events, snapshots, and named Versions",
+    "In-place comparison and recovery through UI and shared Actions",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Blocks-field revision history
+
+## Why this exists
+
+Rich content appears in Page bodies, additional Blocks Properties, Comments, Discussion messages, annotations, and other Content objects. People need to know what changed and recover mistakes in any of those bodies without making every keystroke a named Version or every field a miniature Page.
+
+## Example workflow
+
+A Page contains a primary article body and a separate research-notes Blocks field. An agent edits both in one run. The editor can inspect each field's attributable history, compare the relevant Revisions in place, and restore only the research notes without replacing the article body, Page title, or Properties. If the Page later gains named Versions, each alternative continues to retain its own field history.
+
+## Product contract
+
+- Every editable rich-content body is a Blocks field with stable identity and one canonical owning object.
+- Every Block retains stable identity through ordinary text edits, structured edits, and reordering. Deleted content remains addressable through authorized history.
+- A committed Event is one atomic fact. A logical Revision groups causally related edits by actor, intent, action, or agent run. A recovery snapshot is persistence machinery. A named Version is a deliberate alternative. The interface never treats these as synonyms merely because they happened near the same time.
+- Each Blocks field owns its own attributable revision sequence, comparison, and recovery boundary.
+- A single action may causally touch several fields while preserving which changes belong to each field. Restoring one field does not silently replace unrelated Page state.
+- History records the actual actor, authority, origin, and causal run. Agent work is attributable as agent work rather than being flattened into the signed-in person's authorship.
+- Comparison renders through the ordinary typed editor and renderer for that field. Unknown or unavailable Block renderers preserve their source and produce an explicit degraded state rather than dropping content.
+- Creating, promoting, archiving, restoring, or merging a named Page Version never erases the underlying field histories.
+- Comments, Annotations, references, and other anchors retain their historical Block/field/Revision targets even when current content changes or is deleted.
+
+## Permissions and failure behavior
+
+- History reads and restores use the owning object's access plus any narrower named-Version boundary.
+- A person or agent cannot recover a field into a state they may inspect but lack authority to edit.
+- Inaccessible or pruned history is not reported as an empty successful timeline. Known direct references return an honest denial without leaking content.
+- A failed restore leaves the current field and its history unchanged. Recovery is one atomic, attributable Revision and can itself be inspected or undone.
+- Concurrent current edits cannot be silently overwritten by a restore prepared against an older state; Content exposes a stale/conflict state or applies a contractually safe merge.
+
+## Boundaries and non-goals
+
+- Field history does not create a named Version for every edit.
+- Snapshot timing does not decide Revision boundaries; causality and editing intent do.
+- A Blocks field is not a full Page and does not acquire independent top-level Properties, sharing, or Database membership.
+- This Capability does not define the Page-level branching graph, selective cross-Version merge, or canonical promotion owned by `content.version.branching`.
+- Queryable History may project these Revisions across objects, but it is not the source of truth for the field's identity.
+
+## Acceptance stories
+
+### Recover one field without replacing its Page
+
+Given a Page with two Blocks fields and unrelated top-level Properties, when an editor restores an earlier Revision of one field, then only that field changes, the other field and Properties remain intact, and the restore produces a new attributable Revision.
+
+### Preserve anchors after deletion
+
+Given a Comment anchored to a Block range, when the range and then the Block are deleted, then the Comment remains durable and can open the historical field Revision showing the original target rather than being auto-archived or attached to plausible-looking new text.
+
+### Keep agent edits attributable
+
+Given one agent run edits several Blocks in two fields, when a reviewer opens History, then the changes are grouped by causal run while remaining inspectable per field and are attributed to the agent and authorizing context.
+
+### Survive named-Version operations
+
+Given two named Versions with independent edits to the same logical field, when one is promoted and the other archived and restored, then both field histories, Block identities, anchors, and actors remain intact.
+
+## Current evidence
+
+Current whole-document snapshots and restore behavior demonstrate useful recovery substrate. They do not prove independently addressable Blocks-field history, causal Revision grouping, stable Block identity across every edit, cross-field selective recovery, or preservation through named Versions. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Exercise text and structured Block edits, moves, deletions, and restores in every Blocks-field-owning object.
+2. Verify Event-to-Revision grouping for human, agent, automation, API, and integration actors.
+3. Compare and restore one field while other fields, title, Properties, memberships, and concurrent edits remain intact.
+4. Verify Comment, Annotation, reference, and execution-receipt anchors before and after edits, deletion, restore, and named-Version operations.
+5. Test access denial, stale restore, persistence interruption, Undo, reload, export, and lossless round-trip.
+6. Run the workflow through the real editor and shared Actions, including keyboard and assistive-technology inspection.
+
+## Open questions
+
+The remaining major seam is how one named Page Version selects or groups several independently versioned Blocks fields. Physical snapshot cadence, storage layout, compaction, and indexing remain implementation choices as long as the causal and recovery contract survives.

package/corpus/templates/content/docs/product/capabilities/content.view.canvas.md

@@ -0,0 +1,94 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.canvas"
+name: "Canvas"
+user_promise: "Canvas lets people intentionally arrange reusable Content objects in a spatial View without copying them or accidentally asserting semantic relationships."
+primary_user_job: "Lay out notes, sources, media, and views to think visually, while deciding explicitly which tentative connections should become durable shared knowledge."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.object.reference",
+    "content.relationship.edge",
+    "content.view.query",
+  ]
+related_features: ["content.feature.sketch-connections-keep-whats-true"]
+roadmap_boundary: "feature"
+acceptance_summary: "Canvas stores an intentional View-local arrangement of canonical objects, sections, and freeform connectors; only an explicit promotion creates a typed Relationship, and its visual layout never changes shared semantics."
+proof_requirements:
+  [
+    "Stable object reuse, multi-Canvas membership, position and section persistence, and canonical-record drill-in without copies",
+    "View-local connector creation, editing, deletion, and explicit promotion to a selected typed Relationship",
+    "Access-scoped placement, query-backed population, collaboration, deletion, unavailable-object, and recovery behavior",
+    "Keyboard and assistive-technology spatial navigation plus bounded loading and real-interface arrangement workflows",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Canvas
+
+## Why this exists
+
+People often need to arrange evidence, ideas, and work spatially before they know what every connection means. Canvas supplies that intentional visual workspace without copying the underlying Content objects or turning each sketch into a database fact. A line can remain a private-to-the-View thought until someone deliberately promotes it.
+
+## Example workflow
+
+A researcher drags canonical notes, source excerpts, images, and a saved query onto a Canvas. They place material into sections for competing explanations, draw informal lines between pieces of evidence, and add a small annotation. Once a line clearly means `contradicts`, they choose **Promote to relationship**, select that type, and confirm the authorized endpoints. The semantic edge then appears in Graph and Connections; removing the original Canvas line later does not remove it.
+
+## Product contract
+
+- Canvas is a View over reusable canonical Pages, Blocks, Sources, Annotations, media handles, and embedded Views. It owns placement, size, sections, stacks, presentation overrides, and view-local connectors, never a duplicate of the object’s data or identity.
+- An object may appear in many Canvases. Moving, resizing, grouping, or removing its occurrence changes only that Canvas unless a separate canonical edit is made.
+- Drawing a freeform line creates a view-local connector by default. It may be renamed, styled, moved, or deleted without invoking the Relationship system.
+- **Promote to relationship** requires an explicit typed Relationship selection and an authorized shared mutation. Promotion creates or connects to the canonical edge; it does not silently reinterpret every similar line.
+- A Canvas may intentionally show canonical semantic edges alongside freeform connectors, but the two remain distinguishable and independently editable.
+- A Canvas may populate from an authorized saved query and may filter, group, or style visible semantic edges by type. Query membership does not give the Canvas authority to change source records.
+- Manual arrangement, mind-map hierarchy, and optional auto-layout adjust View-owned layout only. They never manufacture or rewrite semantic Relationships.
+- Canvas preserves an honest distinction among removed objects, inaccessible objects, unavailable sources, and empty query results; it does not convert each into a generic blank card.
+
+## Boundaries and non-goals
+
+- `content.view.graph` owns semantic relationship exploration and editing over a relationship query; Canvas is not a semantic Graph mode.
+- `content.relationship.edge` owns canonical typed edges and their authorization. Canvas owns draft connector lifecycle and invokes that Capability only on explicit promotion.
+- `content.view.query` owns typed query definitions and access-scoped result contracts; Canvas consumes authorized results.
+- `content.view.chart` owns analytical charts, and Mermaid remains an authored code diagram rather than a Canvas feature.
+- Canvas does not create a parallel datastore, permissions model, relationship inference engine, or a promise that every spatial arrangement is a shared semantic model.
+
+## Acceptance stories
+
+### Reuse one object in two contexts
+
+Given a Page placed on two Canvases, when an editor rearranges it or removes it from one Canvas, then the other Canvas and the canonical Page stay unchanged. Opening either occurrence reaches the same authorized record.
+
+### Keep brainstorming local until promotion
+
+Given two objects connected by a freeform Canvas line, when a contributor deletes or restyles the line, then no canonical Relationship changes. When they explicitly promote it with an authorized `supports` type, then one typed edge is created and remains after the local line is removed.
+
+### Preserve access and source truth
+
+Given a query-populated Canvas whose source later becomes unavailable and one result becomes inaccessible, when the viewer returns, then Canvas identifies each condition without leaking the inaccessible object or silently presenting the unavailable query as empty.
+
+### Collaborate without layout becoming a semantic conflict
+
+Given two collaborators arranging the same Canvas while one edits a canonical Relationship through another authorized surface, when changes settle, then layout updates merge or surface a recoverable View conflict and the canonical relationship retains its own history.
+
+## Current evidence
+
+Existing object references, Views, and relationship concepts are useful substrate. There is no current evidence that proves multi-Canvas identity, connector promotion, collaboration, access closure, or accessible spatial interaction as one complete workflow. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Place each supported object kind in multiple Canvases, edit its canonical source, and verify occurrence reuse, source truth, deletion, and restoration behavior.
+2. Create, edit, remove, and promote freeform connectors; prove that only explicit typed promotion invokes the Relationship Action and that visual deletion never removes an edge.
+3. Exercise query-backed population, filters, semantic-edge overlays, empty results, access changes, source unavailability, bounded loading, and retry.
+4. Test concurrent arrangement, section changes, stack changes, and canonical edits with durable history and recovery behavior.
+5. Complete keyboard and assistive-technology workflows for placement, selection, grouping, connectors, promotion, errors, and opening canonical records.
+
+## Open questions
+
+The exact spatial input model, collision behavior, collaboration merge representation, and supported media affordances remain implementation choices. They must not weaken object reuse, explicit promotion, access closure, or layout-only semantics.

package/corpus/templates/content/docs/product/capabilities/content.view.chart.md

@@ -0,0 +1,91 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.chart"
+name: "Chart View"
+user_promise: "Chart turns authorized typed query results into understandable analytical visualizations that remain usable as saved Views, embedded Blocks, dashboards, and static output."
+primary_user_job: "See a trustworthy pattern in typed records, inspect the contributing canonical rows, and reuse the same analysis wherever the work is discussed."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  ["content.view.grouping-aggregation", "content.view.renderer-conformance"]
+related_features:
+  [
+    "content.feature.understand-what-your-data-says",
+    "content.feature.build-living-dashboards",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Chart uses a typed analytical specification over access-scoped query results, supports saved View, embedded Block, dashboard, and static-output presentations, and drills into the canonical records that produced each mark."
+proof_requirements:
+  [
+    "Typed chart specification validation for dimensions, measures, grouping, aggregation, sort, missing values, and incompatible input",
+    "Identical saved-View, embedded-Block, dashboard, and static-output behavior from one specification",
+    "Access-safe marks, aggregates, drill-down, empty, stale, unavailable, and export-fallback behavior",
+    "Real-interface interaction, keyboard, accessibility, responsive, and renderer-conformance workflows",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Chart View
+
+## Why this exists
+
+Tables expose records; Charts make patterns in typed measures and groups easier to see. Chart View provides analytical visualization without creating a separate analytics datastore or a snapshot that loses its route back to the canonical records.
+
+## Example workflow
+
+A manager saves a Chart View that groups authorized work by status and measures item count over time. They embed the same typed chart as a Block in a weekly document and place it on a dashboard. Clicking a bar opens the access-scoped canonical rows that contributed to that mark. When the dashboard is exported or viewed where the interactive renderer is unavailable, the same specification provides a readable static fallback and accessible summary.
+
+## Product contract
+
+- A Chart is a typed analytical specification over an authorized Database or Query result: dimensions, measures, grouping, aggregation, sort, filters, display choices, and drill-down mapping are validated against typed input.
+- One specification can render as a saved View, embedded Block, dashboard component, and static output. These are presentations of the same analysis, not separately maintained charts.
+- A mark drills into the canonical records contributing to it through an access-scoped query. A chart never grants access to records that its viewer could not otherwise read.
+- Aggregates, labels, totals, empty states, and exported summaries are computed only from authorized input. Hidden rows cannot leak through counts, bins, axes, or a drill-down result.
+- Incompatible fields, invalid aggregation, no data, stale results, unavailable sources, and renderer failures remain distinct states with repair or retry guidance; none is rendered as a convincing zero.
+- Chart supports analytical visuals such as bars, lines, areas, and other compatible presentations chosen by the specification. Compatibility, accessibility, and export fallback are provided through Typed Renderers.
+
+## Boundaries and non-goals
+
+- `content.view.grouping-aggregation` owns typed grouping and aggregate semantics; Chart owns their analytical visual presentation and mark-to-record interaction.
+- `content.renderer.typed` and `content.view.renderer-conformance` own renderer compatibility, inheritance, accessibility, and output conformance; Chart does not define a new renderer registry.
+- `content.view.graph` explores typed Relationships, while `content.view.canvas` arranges objects spatially. Mermaid is authored diagram source, not a Chart input or output model.
+- Chart does not create a parallel business-intelligence warehouse, change query semantics, expose unauthorized data, or replace custom dashboard layout ownership.
+
+## Acceptance stories
+
+### Reuse one analysis across surfaces
+
+Given a valid chart specification saved on an authorized Query, when a person opens it as a View, embeds it as a Block, and adds it to a dashboard, then each surface renders the same measure, grouping, filters, labels, and drill-down contract.
+
+### Drill into only contributing records
+
+Given a bar representing an aggregate over accessible and inaccessible source rows, when a viewer activates that bar, then the drill-down contains only accessible canonical records and the aggregate, axis, and accessible-text summary reveal no hidden contribution.
+
+### Fail loudly rather than imply no work
+
+Given a saved chart whose required field was removed or source is temporarily unavailable, when it renders, then it shows a typed invalid or unavailable state with repair or retry guidance rather than a zero-valued chart.
+
+### Produce an accessible static presentation
+
+Given a chart rendered in a noninteractive export context, when the interactive renderer is unavailable, then the output includes a compatible static representation and accessible textual summary derived from the same authorized specification.
+
+## Current evidence
+
+The catalog defines typed properties, views, grouping, aggregation, renderer conformance, and dashboards as related substrate. Current code may include isolated charts or visualization components, but no evidence proves the unified typed specification across all surfaces, safe drill-down, static fallback, or full failure contract. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Validate specifications across compatible and incompatible fields, grouping, measures, aggregation, sorting, filtering, missing values, and schema changes.
+2. Render one specification as a saved View, embedded Block, dashboard item, responsive surface, and static export; verify semantic and visual conformance.
+3. Exercise mark drill-down, totals, labels, bins, empty data, access changes, stale data, deleted fields, source failure, renderer failure, and retry.
+4. Verify access-first aggregates and drill-down under changing permissions, including export and agent-accessible output.
+5. Complete mouse, keyboard, and assistive-technology interaction tests, including an accessible static fallback.
+
+## Open questions
+
+Supported chart families, formatting controls, sampling thresholds, and exact static-output formats remain open. They must fit the typed specification and preserve access-safe drill-down and truthful failure behavior.