@agent-native/core 0.130.2 → 0.131.3

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.

package/corpus/templates/content/docs/product/capabilities/content.view.dynamic-create.md

@@ -0,0 +1,137 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.dynamic-create"
+name: "View-derived creation defaults"
+user_promise: "Creating through a View starts new records with safe contextual values without turning that View's filters into hidden validation."
+primary_user_job: "Capture a new record where I am working and have it start in the right context without losing the ability to make a valid exception."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.view.query", "content.property.constraints"]
+related_features: ["content.feature.data-that-keeps-itself-right"]
+roadmap_boundary: "feature"
+acceptance_summary: "Creation through an effective View seeds only deterministic positive equality, membership, contextual, and renderer-placement values; Database validation remains the sole hard gate, and valid edits may move records into or out of results with truthful feedback."
+proof_requirements:
+  [
+    "Typed effective-View analysis for positive seeds and refusal of ambiguous inference",
+    "Shared UI and Action creation with Database permissions, validation, defaults, Events, revisions, and Undo",
+    "Real-interface workflows for conflicting seeds, post-create exclusion, and valid edits that leave or re-enter results",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# View-derived creation defaults
+
+## Why this exists
+
+People often create work from a focused list, Board lane, or Calendar date.
+That surface should provide a useful starting context, but a filter only says
+which records are included in a result. Treating it as a hidden mutation rule
+would make a View unexpectedly own data validity and block legitimate work.
+
+## Example workflow
+
+An editor opens an `Active` Board filtered to `Active = true` and chooses a
+lane for `Status = Planned`. New work begins with both values. The editor then
+turns `Active` off because that is the correct valid state. Content commits the
+change through the Database, removes the record from the active View, and shows
+**Moved out of this View · Undo**; it does not reject the change or delete the
+record.
+
+## Product contract
+
+### Seed only what is deterministic
+
+- Creation uses the effective View: its saved definition, applicable personal
+  arrangement, and renderer placement. Human and agent creation receive the
+  same analysis and shared Action behavior.
+- Exact positive equality, positive membership, contextual equality, and an
+  explicit renderer placement may seed stored values when they have an
+  unambiguous writable route. Examples include `Active = true`, `Tags contains
+Urgent`, `Assignee = current actor`, a Board lane, or a Calendar date.
+- `OR`, negation, ranges, full-text search, aggregate conditions, arbitrary
+  formulas, and other non-deterministic expressions never manufacture a stored
+  value merely because a record might satisfy them.
+- Seeds are starting values, not locked fields. Explicit user intent may change
+  them before or after creation whenever the owning Database permits the
+  resulting mutation.
+
+### Inclusion is not validation
+
+- Query and View filters control result inclusion. The owning Database owns
+  membership, Properties, defaults, constraints, permissions, Rules, and the
+  canonical create/write path; only those rules decide whether a value is
+  valid.
+- A View over a Query cannot seed or validate outside the Query's declared
+  creation routes. A composed Query with no applicable route is truthfully
+  read-only, and a View cannot invent a target.
+- If valid creation or a later valid edit no longer matches the effective
+  result, Content preserves the record, refreshes the result, and gives light
+  feedback such as **Created, but not shown in this View** or **Moved out of
+  this View**, with an appropriate Open or Undo route.
+- Conflicting automatic seeds never cause a guess. Quick capture expands to the
+  normal creation editor, explains the conflict, and lets Database validation
+  and explicit intent resolve it.
+
+## Boundaries and non-goals
+
+- Database and Query Views own presentation, downstream filters, and the
+  effective View; Database constraints and Rules own validity.
+- Reusable Queries own intrinsic filters and creation routes. This Capability
+  applies those routes in a View; it does not define cross-source write routing.
+- This is not a bulk-update, schema-default, task-template, permission, or
+  second Action system.
+
+## Acceptance stories
+
+### Seed a Board capture without locking it
+
+Given an authorized Board View filtered to `Active = true` with a `Planned`
+lane, when a person creates a record in that lane, then the record starts with
+`Active = true` and `Status = Planned`. When they validly set `Active = false`,
+then the Database commits it and the record leaves the View with Undo feedback.
+
+### Refuse to infer an ambiguous filter
+
+Given a View filtered by `Priority = High OR Priority = Urgent` and a date
+range, when a person starts quick capture, then Content does not choose a
+priority or fabricate a date from those expressions; it opens the normal editor
+with only independently deterministic defaults.
+
+### Resolve conflicting seeds visibly
+
+Given a View's positive filter and renderer placement propose incompatible
+writable values, when an authorized person creates a record, then no arbitrary
+value is committed and the normal editor identifies the mismatch. If the person
+chooses a valid value outside the View, the record is created and truthfully
+reported as not shown.
+
+## Current evidence
+
+Existing filters, saved Views, Board/Calendar rendering, and creation paths are
+useful donor substrate. They do not yet prove typed seed analysis, identical
+human/agent behavior, conflict expansion, result-transition feedback, or the
+complete Database-validation boundary. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test equality, membership, contextual, Board, and Calendar seeds through UI
+   and Actions, including permissions, defaults, constraints, Rules, Events,
+   revisions, reload, and Undo.
+2. Assert that OR, negation, ranges, search, aggregates, formulas, unavailable
+   fields, ambiguous routes, and inaccessible values produce no invented seed.
+3. Exercise post-create exclusion, editing records out of and back into Database
+   and Query Views, conflicting seeds, and composed Query zero/one/many routes.
+4. Verify accessible feedback and keyboard capture without turning View
+   inclusion into a hidden mutation failure.
+
+## Open questions
+
+- The exact precedence and presentation for multiple compatible defaults,
+  Database defaults, and renderer placement need implementation design.
+- The compact creation editor for conflicting seeds and the exact Undo scope
+  need interaction design, while preserving the settled ownership boundary.

package/corpus/templates/content/docs/product/capabilities/content.view.fast-capture.md

@@ -0,0 +1,82 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.fast-capture"
+name: "Fast keyboard capture"
+user_promise: "Keyboard-fluent List and Table capture"
+primary_user_job: "Capture and revise a record at keyboard speed without leaving the current authorized View."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.view.query", "content.agent.action-parity"]
+related_features:
+  [
+    "content.feature.see-your-information-your-way",
+    "content.feature.run-projects-your-way",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "List and Table capture create and edit canonical records through the shared Action surface, preserve keyboard focus, and roll back an unsuccessful optimistic update visibly."
+proof_requirements:
+  [
+    "Keyboard-only create, edit, Enter, Tab, escape, navigation, and focus-return coverage",
+    "Shared Action authorization, validation, history, error, and optimistic rollback coverage",
+    "Real-interface assistive-technology and concurrent-refresh workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Fast keyboard capture
+
+## Why this exists
+
+Quick capture keeps a small thought from becoming a ceremony while retaining the
+Database's rules and the record's canonical identity.
+
+## Example workflow
+
+An editor tabs to the last row of a filtered List, presses Enter, types a title,
+and moves through editable cells with Tab. A rejected change returns focus and
+an explanation; it does not leave a convincing but unsaved row behind.
+
+## Product contract
+
+- List and Table are keyboard editors of canonical Database records, not local drafts.
+- Enter, Tab, arrow navigation, escape, selection, and focus restoration are predictable and accessible.
+- Creation and edits use the same authorized Action, validation, Events, history, and failure behavior as an agent.
+- Optimistic UI is reversible; denied, invalid, stale, or unavailable work is visibly distinct from success.
+
+## Boundaries and non-goals
+
+View-derived creation defaults own contextual seeds. This Capability does not define
+bulk editing, a new inline data store, or a permission bypass.
+
+## Acceptance stories
+
+### Capture a record without a mouse
+
+Given an editable List, when a person enters a title and tabs through a writable field,
+then one valid canonical record is created and focus advances predictably.
+
+### Recover from a rejected edit
+
+Given an optimistic inline edit that fails validation, when the Action rejects it, then
+the rendered value rolls back, focus remains useful, and the failure is announced.
+
+## Current evidence
+
+Existing Database editing and View machinery are donor substrate. No complete proof yet
+covers keyboard semantics, Action parity, rollback, accessibility, and recovery; this
+Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test keyboard creation and editing across List and Table with validation and permissions.
+2. Verify Action/UI parity, Events, history, stale writes, rollback, and reload.
+3. Exercise screen-reader announcements, focus order, and concurrent result refreshes.
+
+## Open questions
+
+The compact editor's exact escape and multi-cell paste semantics need interaction design.

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

@@ -0,0 +1,95 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.graph"
+name: "Graph View"
+user_promise: "Graph lays out query-selected canonical objects and typed Relationships for access-safe exploration and editing."
+primary_user_job: "Explore a meaningful neighborhood of connected records, understand why they relate, and make an authorized semantic change without treating a visual line as the source of truth."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.knowledge.graph",
+    "content.relationship.edge",
+    "content.view.renderer-conformance",
+  ]
+related_features: ["content.feature.sketch-connections-keep-whats-true"]
+roadmap_boundary: "feature"
+acceptance_summary: "Graph renders an access-scoped saved relationship query as canonical nodes and typed edges, supports authorized typed-edge editing, and keeps every layout operation separate from semantic truth."
+proof_requirements:
+  [
+    "Access-scoped graph-query results, traversal, expansion, filtering, and empty or unavailable states",
+    "Typed-edge creation, editing, removal, permission denial, and history through the shared Relationship Action",
+    "Manual and physics-assisted layouts, pinning, saved arrangements, reset, and proof that layout never mutates semantic relationships",
+    "Keyboard, assistive-technology, dense-neighborhood, and drill-in workflows in the real interface",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Graph View
+
+## Why this exists
+
+A list can show that records are related without making the surrounding structure legible. Graph View lets people explore an access-scoped semantic neighborhood: canonical records are nodes, and each visible line is a real typed Relationship rather than decoration.
+
+It is for questions such as “what supports this claim?” or “which work is blocked by this decision?” It is not a drawing board, a statistical chart, or an authored diagram.
+
+## Example workflow
+
+A project lead opens a saved graph query centered on a decision Page and expands one relationship type at a time. They pin the Pages relevant to a review, use a force-assisted layout to separate a crowded neighborhood, and save that arrangement for later. With the `blocks` type selected in the edge tool, they draw from one authorized Page to another; Content creates the corresponding canonical Relationship and shows it in Connections and other authorized projections. Resetting the layout changes only positions, never the relationship.
+
+## Product contract
+
+- Graph renders a saved, typed, access-scoped relationship query. Nodes retain their canonical Page, Block, Source, or query-result identity; Graph owns only its View configuration and arrangement.
+- Each semantic edge displays a Relationship type and is a projection of the canonical edge. Editing, removing, or creating an edge uses the shared typed Relationship Action and records normal history.
+- The edge tool requires a Relationship type before it can create an edge. A line never becomes a semantic assertion merely because it was drawn.
+- People may filter, group, and style by relationship type; expand authorized neighbors; open canonical records; pin or unpin nodes; save a useful arrangement; and reset it.
+- Manual, hierarchical, radial, and physics-assisted layouts may change positions only. Layout algorithms never infer, create, rewrite, or delete Relationships.
+- Graph applies access before query evaluation, traversal, counts, labels, previews, export, or agent use. An inaccessible endpoint is not exposed through a visible placeholder, degree, or hidden-edge count.
+- An empty query is an honest empty Graph. A failed, stale, or unavailable query reports that state distinctly and does not masquerade as no relationships.
+
+## Boundaries and non-goals
+
+- `content.relationship.edge` owns canonical edge identity, cardinality, authority, mutation, and history; Graph is an authorized editor and projection.
+- `content.knowledge.graph` owns relationship-query semantics and traversal; Graph owns visual exploration and layout.
+- `content.view.canvas` owns intentional spatial composition and view-local freeform connectors. Canvas lines require explicit promotion before they become Relationships.
+- `content.view.chart` owns analytical visualizations over measures and grouped data. Authored Mermaid diagrams belong to code-authoring and Mermaid rendering, not Graph.
+- Graph does not create a parallel graph datastore, access model, permission bypass, task dependency engine, or diagram language.
+
+## Acceptance stories
+
+### Explore only what the viewer may know
+
+Given a saved graph query that includes both accessible and inaccessible relationships, when a viewer opens and expands Graph, then the graph, counts, labels, previews, and exports contain only authorized nodes and edges, while a direct unauthorized request receives an honest denial.
+
+### Create a semantic edge deliberately
+
+Given an editor authorized to change two Pages and use the `supports` Relationship type, when they select `supports` and draw an edge, then one canonical typed Relationship is created and appears in Connections and other authorized projections. When no type is selected, drawing cannot commit an edge.
+
+### Separate arrangement from meaning
+
+Given a dense saved Graph, when a viewer pins nodes, runs a force-assisted layout, saves the arrangement, and later resets it, then node positions change as requested but the relationship query and canonical edge history remain unchanged.
+
+### Report unavailable work truthfully
+
+Given a graph query that cannot complete because its source is unavailable, when Graph opens, then it reports the unavailable state and retry path rather than rendering a plausible empty neighborhood.
+
+## Current evidence
+
+The repository defines the shared object, query, Relationship, and renderer boundaries that Graph will need. Existing code may offer useful visualization or relation substrate, but no current evidence proves the complete Graph query, edge-editing, access-closure, layout, or recovery contract. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Exercise saved graph queries with filtering, expansion, grouping, pagination or bounds, empty results, stale inputs, and unavailable sources.
+2. Create, edit, and remove typed edges through Graph alongside Connections and another projection; verify one identity, permission decision, and committed history.
+3. Verify manual, hierarchical, radial, and physics-assisted layouts across pin, save, reload, reset, and concurrent semantic edits; assert that no layout path changes an edge.
+4. Run keyboard and assistive-technology workflows for navigation, node inspection, edge-type selection, editing, errors, and dense-graph recovery.
+5. Re-run traversal, labels, counts, previews, export, and agent reads with changing endpoint access to prove access precedes every computation.
+
+## Open questions
+
+The contract leaves rendering-engine choice, layout implementation, graph-size limits, and exact controls open. Those choices must preserve bounded loading, explicit failure states, and the semantic/layout separation above.

package/corpus/templates/content/docs/product/capabilities/content.view.grouping-aggregation.md

@@ -0,0 +1,83 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.view.grouping-aggregation"
+name: "Grouping and aggregation"
+user_promise: "Views group across several dimensions and compute access-safe totals, subtotals, rollups, and measures."
+primary_user_job: "Understand meaningful totals and their contributing records without learning information I cannot access."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.view.query", "content.access.safe-aggregate"]
+related_features:
+  [
+    "content.feature.see-your-information-your-way",
+    "content.feature.plan-work-across-time",
+    "content.feature.understand-what-your-data-says",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Authorized View results can be grouped by typed dimensions and measured with access-safe totals, subtotals, rollups, and drill-in."
+proof_requirements:
+  [
+    "Typed multi-dimension grouping, ordering, empty groups, and measure semantics",
+    "Access-before-grouping, totals, rollups, drill-in, export, and agent-context tests",
+    "Real-interface refresh, unavailable-source, dense-result, and accessible-table workflows",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Grouping and aggregation
+
+## Why this exists
+
+People need a useful shape for many records, but a subtotal must never reveal a row,
+field, or inference that its viewer may not know.
+
+## Example workflow
+
+A lead groups authorized work by project and status, reads each subtotal, and opens a
+group to inspect its canonical records. A private task contributes nowhere: not to a
+count, a sum, an empty-group hint, or an export.
+
+## Product contract
+
+- Views group their canonical Query result by typed dimensions and compute declared measures.
+- Access applies before grouping, aggregation, rollup, count, labels, drill-in, export, or agent context.
+- Groups retain stable query semantics; sorting, collapse, and presentation do not mutate records.
+- Empty, stale, unavailable, and partially loaded inputs are explicitly represented.
+
+## Boundaries and non-goals
+
+Queries own result semantics and safe aggregates own disclosure rules. This is not a
+spreadsheet engine, a new analytics datastore, or permission-derived guessing.
+
+## Acceptance stories
+
+### Read an authorized subtotal
+
+Given a grouped View with private rows, when a viewer opens it, then every group and
+total is computed only from authorized rows and fields.
+
+### Drill into a measure
+
+Given a visible aggregate cell, when a viewer drills in, then Content opens the exact
+authorized contributing records rather than an inferred or copied collection.
+
+## Current evidence
+
+Existing filters and renderer utilities are donor substrate. The repository does not
+yet prove multi-dimensional measure semantics or disclosure closure, so this remains
+`approved_shape`.
+
+## Proof plan
+
+1. Test typed grouping, measures, ordering, nulls, empty groups, and rollups.
+2. Test access changes through results, counts, drill-in, exports, and agent context.
+3. Exercise reload, source failure, pagination, dense views, keyboard, and assistive technology.
+
+## Open questions
+
+The initial measure catalog and treatment of mixed-source precision need implementation design.