@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.reader.documents.md

@@ -0,0 +1,69 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.reader.documents"
+name: "Document Reader"
+user_promise: "The earlier separate PDF/EPUB reader proposal remains readable lineage rather than an active second product contract."
+primary_user_job: "Understand where native document-reading work belongs without building a separate reader identity or data system."
+kind: "surface"
+state: "superseded"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.reader.surface"]
+related_features: []
+roadmap_boundary: "superseded"
+acceptance_summary: "This lineage record directs new reading and annotation work to the unified Reader surface, keeps PDF export distinct, and prevents a separate document-reader app or source model from becoming an active requirement."
+proof_requirements:
+  [
+    "Catalog validation that supersession target remains present",
+    "Review of new reader work confirming it targets content.reader.surface",
+    "Regression review ensuring PDF export is not represented as native annotation support",
+  ]
+evidence: []
+superseded_by: "content.reader.surface"
+last_reviewed: "2026-07-29"
+---
+
+# Document Reader
+
+## Why this exists
+
+The original narrow reader idea captured a real need but split the product where one Reader surface now carries the contract.
+
+## Example workflow
+
+A contributor looking for PDF annotation requirements follows this record to `content.reader.surface` and `content.research.annotation`, rather than creating a new PDF/EPUB app and data model.
+
+## Product contract
+
+- This record is lineage only. New reading work targets the unified Reader surface over Content objects and source representations.
+- PDF export remains a read-oriented output path, not a substitute for reading state, selectors, or annotations.
+- Any later separate app shell may reuse the Reader contract without creating separate Content identity or custody.
+
+## Boundaries and non-goals
+
+This record does not specify new implementation, verify a reader, or preserve a separate document-only roadmap.
+
+## Acceptance stories
+
+### Route a new request correctly
+
+Given a proposal for EPUB highlighting, when it is classified, then it is evaluated against Reader surface and Annotation contracts rather than this superseded record.
+
+### Keep export distinct
+
+Given a PDF export improvement, when it is documented, then it does not claim native reading progress or annotation support.
+
+## Current evidence
+
+Repository product records identify `content.reader.surface` as the active unified target. This superseded record has no implementation proof and intentionally makes no delivery claim.
+
+## Proof plan
+
+1. Keep the supersession link valid in the product-doc guard.
+2. Review future reader records for unified identity and annotation ownership.
+3. Reject any new separate reader contract unless a later Shape explicitly changes this boundary.
+
+## Open questions
+
+- None; implementation questions belong to `content.reader.surface`.

package/corpus/templates/content/docs/product/capabilities/content.reader.surface.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.reader.surface"
+name: "Reader surface"
+user_promise: "Read and annotate text, documents, web material, and media through one specialized Content surface."
+primary_user_job: "Read comfortably, find my place, and mark exact material without creating a separate copy of the source."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.author.media",
+    "content.research.annotation",
+    "content.source.adapters",
+  ]
+related_features: ["content.feature.read-and-annotate-anything"]
+roadmap_boundary: "feature"
+acceptance_summary: "A specialized, embeddable Reader renders stable Content and source representations with accessible personal reading preferences, durable progress, multimodal selectors, synchronized media/transcript modes, and Actions for annotation and assistive features."
+proof_requirements:
+  [
+    "Representation, selector, progress, preference, accessibility, and offline/cache policy tests across text and media",
+    "Annotation, version-change, source-availability, playback/transcript, and assistive-action tests",
+    "End-to-end read, annotate, resume, re-anchor, and embedded-reader workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Reader surface
+
+## Why this exists
+
+Reading has its own rhythm: the work should be quiet, personal, and still connected to the object it interprets.
+
+## Example workflow
+
+A researcher opens a PDF representation, adjusts width and type, highlights a page range, adds an Annotation, resumes later at progress, and can follow a transcript while audio plays.
+
+## Product contract
+
+- Reader is an embeddable Content surface, not necessarily a separate application or dataset.
+- It renders text, PDFs, EPUBs, web material, audio, video, and transcripts through stable representation handles and source-aware fallbacks.
+- Per-viewer typography, theme, pagination/flow, progress, accessibility, cache/offline policy, text-to-speech, and dictation are personal surface state; they do not change shared source truth.
+- Annotations use durable selectors and version/revision context. Media playback and transcript positions remain synchronized where representations support them.
+
+## Boundaries and non-goals
+
+Annotations own contribution identity; adapters own representations and source availability; public reading owns public pages. Reader does not promise every format is editable or locally available.
+
+## Acceptance stories
+
+### Resume without changing the source
+
+Given two readers of the same source, when one changes typography and progress, then their preferences persist for that viewer without mutating the shared Page or other reader's layout.
+
+### Mark exact media material
+
+Given a source video with a transcript, when a researcher annotates a transcript range, then the Annotation retains the source representation and time/range selector and can reopen the corresponding media location.
+
+## Current evidence
+
+Donor evidence: editor media and source representations provide foundations for rendering. No dedicated multimodal Reader, personal progress model, or end-to-end annotation proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define reader representation, personal state, selector, accessibility, and cache contracts.
+2. Test text, paged, transcript, audio/video, unavailable source, revision, and assistive paths.
+3. Verify reading, annotation, resume, and embed workflows in a real interface.
+
+## Open questions
+
+- The first format sequence and offline storage limits remain open.

package/corpus/templates/content/docs/product/capabilities/content.relationship.edge.md

@@ -0,0 +1,183 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.relationship.edge"
+name: "Typed Relationships"
+user_promise: "One typed edge substrate powers relation Properties, inline typed Page references, backlinks, Info, graph queries, and Graph editing"
+primary_user_job: "Connect two Pages once, give that connection a useful meaning, and manage it consistently from any Content surface."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies:
+  [
+    "content.object.page",
+    "content.object.reference",
+    "content.property.typed",
+    "content.access.page-database",
+    "content.event.committed",
+  ]
+related_features:
+  [
+    "content.feature.living-references",
+    "content.feature.run-projects-your-way",
+    "content.feature.plan-work-across-time",
+    "content.feature.sketch-connections-keep-whats-true",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "People can create, inspect, edit, bulk-remove, restore, and query one canonical Relationship through every authorized surface without duplicated truth, silent partial mutation, access leaks, or lost concurrent history."
+proof_requirements:
+  [
+    "Canonical identity and projection parity across Relation Properties, Connections, inline references, Graph, Canvas promotion, agents, Rules, imports, and Sources",
+    "Directional cardinality, uniqueness, local-to-governed lifecycle, deletion, bulk mutation, and causal concurrency behavior",
+    "Access-first traversal and aggregation plus identical permission decisions through UI and Actions",
+    "Real-interface keyboard, accessibility, recovery, and Undo workflows",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Typed Relationships
+
+## Why this exists
+
+People encounter connections in many places: a Relation column, an `@` mention, a backlink, a project dependency, a Graph edge, or a line drawn on a Canvas. If each surface stores its own version of the connection, the workspace develops several incompatible kinds of truth.
+
+Content instead stores one canonical typed Relationship between stable Page identities. Relation Properties, Info, Queries, Graph, Canvas, agents, Rules, imports, and source adapters are projections and editing routes over that same edge.
+
+## Example workflow
+
+A team has a Tasks Database and a Projects Database. Adding a `Project` Relation Property to Tasks creates a local Relationship type and its first visible projection. A task editor connects a task to a project from the cell. The project immediately shows the inverse connection in **Info → Connections**, and an optional inverse Relation Property can expose the same edge as an editable `Tasks` column.
+
+Later, the team selects several tasks and assigns the same project in one bulk edit. Removing the `Project` column does not erase those relationships. If the team truly wants to remove both the column and its knowledge, the removal dialog offers **Remove Property and its N relationships**, reports the exact authorized impact, commits one Revision, and supports Undo.
+
+## Product contract
+
+### One relationship, many projections
+
+- Every semantic Relationship is one durable edge between stable Page IDs.
+- Both directions are always access-scoped and queryable. Content has no semantically one-way relationship whose inverse disappears from the system; people decide only where each direction is displayed and editable.
+- A directional Relationship type has a forward label and an optional inverse label. A symmetric type such as `Related to` has one canonical unordered edge, not two mirrored writable values.
+- A Relationship type and a visible Relation Property have separate stable identities. The type owns meaning, labels, per-direction cardinality, target constraints, provenance policy, and governing scope. The Property is one Database's editable projection of that type in one direction.
+- Databases own Relation Properties, not Relationships. Pages may be related without belonging to a Database, and removing a Property does not make the underlying edge anonymous or inaccessible.
+- Every editing surface invokes the same typed Relationship Action. No UI, agent, Rule, import, provider, Graph, or Canvas receives a private mutation engine.
+
+### Where people manage relationships
+
+- Adding an ordinary Relation column creates a local Relationship type and its first Property projection. It feels like adding any other column; no catalog ceremony is required.
+- **Info → Connections** is the universal relationship surface. It shows every accessible incoming and outgoing connection, including types not exposed as columns.
+- A Relation picker may use a Database or Query to narrow candidates, but the stored endpoint is the selected Page's stable ID. The edge remains if that Page later leaves the picker Query.
+- Ordinary Page mentions and transclusions create system-managed structural edges with their own mutation rules. An advanced inline action may create a semantic typed reference. Removing one anchored mention does not delete an independently asserted semantic Relationship.
+- In freeform Canvas mode, a drawn connector is view-local brainstorming state until someone explicitly promotes it to a Relationship type. In semantic Graph mode, the active edge tool requires a Relationship type before drawing commits an edge.
+- Existing relationships may be projected as Graph or Canvas lines. Deleting the visual occurrence or removing an object from one View never deletes the canonical Relationship.
+
+### Local and governed definitions
+
+- A local Relationship type belongs to the Content space where it was created and remains resolvable in Connections after its last visible Property is removed.
+- **Save as Custom Property** promotes the definition into the governed Custom Properties catalog at an allowed Personal, Workspace, or Organization scope.
+- Another Database may adopt the governed Property, creating another projection of the same Relationship type rather than copying its semantic identity.
+- Each projection may choose a local display alias, formatting, renderer, and visibility without changing the shared definition.
+- **Detach to local Property** preserves the projected data while creating an independent local definition.
+- Shared definitions are version-pinned. Label, cardinality, constraint, or inverse changes are proposed as readable updates that consuming Database owners adopt explicitly; catalog edits never silently rewrite every relationship system.
+- Provider-backed Relation fields use the same projection model while retaining source identity and synchronization authority.
+
+## Cardinality and identity
+
+- Cardinality is defined independently in each direction. A Task may have one Parent task while a parent has many children; a symmetric `Related to` type may be many-to-many.
+- Requiredness is separate Database/Property validation. `At most one` does not mean `must have one`.
+- Selecting a new target in a single-value Relation Property replaces the observed existing edge as one atomic change.
+- Moving a one-to-one target that is already related elsewhere requires an explicit replacement confirmation and permission to remove the old edge as well as create the new one.
+- Tightening a type from many to one never deletes existing edges. Existing violations become **Needs attention**; new mutations cannot worsen them, and authorized owners can resolve a filtered set.
+- A directional type permits at most one live edge for the same type, source, and target. Adding it again is idempotent. Symmetric types treat `(A, B)` and `(B, A)` as the same pair.
+- Different Relationship types remain independent, and reversed directional edges may coexist. Cycle rules are explicit validation on types or workflows, not deduplication and not a universal ban.
+- Self-relationships are disabled by default and can be enabled as an advanced Relationship-type option.
+- Repeated anchored citations or mentions retain their own occurrences and history while Connections may summarize them as one Page-to-Page relationship.
+- A connection that needs several independent instances with dates, roles, or state becomes an intermediate Page with Properties rather than several indistinguishable parallel edges.
+
+## Permissions and authority
+
+- Editing a forward Relation Property requires **Can edit entries** in the Database owning that projection, access to the target Page, permission to use the Relationship type, and satisfaction of its constraints.
+- An explicitly editable inverse Relation Property grants the matching inverse-side editing route. An inverse shown only in Connections remains read-only from that side.
+- On an ordinary Page, **Can edit** permits outgoing directional Relationship changes through Connections. Incoming directional edges remain read-only unless the actor also has an authorized source-side or editable-inverse route.
+- A symmetric Relationship may be changed through an authorized edit route on either endpoint.
+- Seeing an endpoint or an incoming edge never grants authority to sever it. Owning a Relationship type does not grant access to every private edge that uses it.
+- Same-Organization cross-Workspace edges may be allowed by policy. Cross-Organization canonical edges are prohibited by default until federation can preserve both organizations' access, deletion, and governance guarantees.
+- Source-managed edges additionally obey the Source's **View only**, **Keep in sync**, or **Review before write-back** policy and provider capabilities. A local relationship pointing to a source-backed Page does not automatically become provider-owned.
+- Counts, rollups, graph degree, Queries, expressions, agents, inverse projections, exports, and graph traversal are computed only over edges and endpoints the viewer may access. Physical inverse indexes may improve performance but never become a second truth.
+
+## Bulk operations, deletion, and concurrency
+
+- Multi-cell selection, row bulk edit, paste/fill, and filtered selection may add Relationships. Delete/Backspace, **Clear relationships**, target removal, and filtered bulk editing remove the exact selected edges.
+- Bulk mutation preflights the complete selection. Ambiguous input or mixed permissions never produces a silent partial commit. Content identifies conflicts or locked items and lets the person narrow explicitly; an agent may narrow only when that remains faithful to the request and must report skipped scope.
+- A filtered bulk removal resolves exact edge IDs and activation states when the selection is made. New concurrent matches are not swept in later.
+- Removing a Relation Property preserves its Relationships by default. The destructive dialog offers **Remove Property** or **Remove Property and its N relationships**, with an access-scoped impact count, one attributable Revision, and Undo. **Manage relationships** opens a filterable collection before removal.
+- Removing an edge removes the activation state the operation observed. A genuinely concurrent authorized addition that the remover did not observe survives. A later removal made after observing that addition wins.
+- Re-adding a removed Relationship continues one stable lineage with another activation period. Concurrent duplicate additions converge on that same live lineage.
+- Successful single-value replacements serialize through committed-event order so only one target remains live; history and Undo preserve the displaced choices.
+- Trashing a Page suspends its active Relationships and restoring it restores them. Permanent deletion retains only inaccessible audit/history evidence.
+- Relationship definitions archive rather than cascading deletion across their edges.
+
+## Failure behavior
+
+- Constraint, permission, access, source-authority, and cardinality failures are typed failures, never successful empty results.
+- A bulk operation with ambiguous values, mixed authority, or an invalid cardinality change does not half-commit.
+- When a one-to-one move cannot remove the old edge, Content leaves both prior states unchanged and explains the required authority.
+- Broken, trashed, inaccessible, and permanently deleted endpoints remain distinguishable according to the viewer's authority without leaking private identity.
+- Ordinary concurrent convergence does not interrupt people with a conflict dialog. Intervention appears only when no valid authorized state can be committed.
+
+## Boundaries and non-goals
+
+- Relationships do not create a parallel graph datastore, permission model, Action surface, or task-dependency engine.
+- Relation Properties are projections, not the owners of the underlying knowledge.
+- Graph owns semantic graph layout and editing; Canvas owns intentional spatial arrangement and draft connectors; Queries own access-scoped traversal and result contracts.
+- Schedule constraints may interpret dependency Relationships, but this Capability does not calculate critical paths or repair dates.
+- Merely drawing a freeform Canvas line does not assert semantic truth.
+- A relationship never grants access to either endpoint.
+- Provider synchronization is proven separately for each adapter and cannot stand in for the generic Relationship contract.
+
+## Acceptance stories
+
+### Create once and edit from either direction
+
+Given two authorized Pages and a directional Relationship type with forward and inverse projections, when an editor creates the edge from the forward Relation Property and later removes it through the editable inverse projection, then Info, both Properties, Queries, Graph, and the shared Action surface show one canonical edge and one coherent history.
+
+### Preserve knowledge when a column disappears
+
+Given a Relation Property containing several Relationships, when a Database editor removes only the Property, then the Relationships remain visible in authorized Connections and Queries. When the editor instead chooses **Remove Property and its N relationships**, the exact authorized edges are removed in one reversible Revision and newer concurrent edges are preserved.
+
+### Enforce directional cardinality atomically
+
+Given a one-parent Relationship and a bulk paste containing several proposed parents for one Task, when the edit is submitted, then no subset commits and Content identifies the conflicting input. Given one valid replacement, the observed prior parent is replaced atomically and the inverse projection updates.
+
+### Keep authority attached to the route
+
+Given a person who may view both endpoints but may edit only the target Page, when they inspect an incoming directional edge in Connections, then they can see it but cannot remove it unless an editable inverse Property or other authorized route exists. Graph, Canvas, agents, and Rules return the same decision.
+
+### Converge without inventing history
+
+Given one client removes the edge it observed while another concurrently re-adds it, when both commits settle, then the unseen addition remains live, no duplicate appears, and Versions shows the actual removal and re-add. A subsequent informed removal makes the edge inactive.
+
+### Protect private neighborhoods
+
+Given an authorized Page related to an endpoint the viewer cannot access, when the viewer opens Connections, runs a Query, inspects Graph, calculates counts or rollups, or exports the Page, then the private endpoint and its existence do not leak. A known direct reference returns an honest access denial.
+
+## Current evidence
+
+Current code can model and display some relation values, which is useful donor substrate. Relation is not yet a generally user-creatable Property, and the current Notion path treats relations as unsupported. No evidence currently proves the shared type identity, universal Connections editor, bulk/deletion semantics, cardinality, access closure, source policy, or causal concurrency contract. This Capability therefore remains `approved_shape`.
+
+## Proof plan
+
+Proof requires deterministic Action and persistence tests plus real-interface workflows:
+
+1. Create local, governed, symmetric, directional, self-enabled, and source-backed Relationship types; rename and version them without changing stable identity.
+2. Create, edit, and remove the same edge through forward and inverse Properties, Connections, inline typed references, Graph, Canvas promotion, agents, Rules, and imports; verify identical permission and Event behavior.
+3. Exercise one-to-one, one-to-many, many-to-many, replacement, tightening, cycle validation, duplicate addition, and invalid-target cases.
+4. Exercise bulk add/remove, mixed permissions, filtered selection, property-only removal, destructive property-plus-edge removal, Undo, and new concurrent matches.
+5. Race add/add, add/remove, replacement/replacement, deletion/restoration, and definition updates; verify one valid live state and complete causal history.
+6. Re-run cells, Connections, backlinks, Queries, traversal, Graph, counts, rollups, aggregates, exports, public output, and agent reads under changing access; verify access is applied before computation.
+7. Verify keyboard and assistive-technology paths for relation pickers, Connections, impact dialogs, bulk selection, and repair states.
+
+## Open questions
+
+The core product behavior above is settled. Implementation may still choose storage layout, index strategy, causal metadata representation, and exact control placement provided those choices satisfy this contract. Federation must be separately designed before enabling canonical cross-Organization Relationships.

package/corpus/templates/content/docs/product/capabilities/content.renderer.artifact-block.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.renderer.artifact-block"
+name: "Artifact Blocks"
+user_promise: "Make a one-off interactive or visual artifact on one page, then promote it only if reuse becomes real."
+primary_user_job: "Build a safe page-local artifact before deliberate promotion."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.custom-block"]
+related_features: ["content.feature.build-new-surfaces"]
+roadmap_boundary: "feature"
+acceptance_summary: "An Artifact Block is page-owned HTML/CSS/JS in the shared Custom Block sandbox format, with optional typed props, stable asset handles, export fallback, and explicit Save as Custom Block promotion."
+proof_requirements:
+  [
+    "Artifact Blocks have no catalog identity until a user explicitly saves one as a Custom Block.",
+    "The sandbox receives only bound typed props and has no ambient Content data, actions, cookies, filesystem, parent DOM, secrets, or network.",
+    "Export uses a declared static fallback; promotion preserves provenance rather than silently changing reuse scope.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Artifact Blocks
+
+## Why this exists
+
+Many useful artifacts begin as one-page experiments, before anyone can justify governing them for reuse. That early experiment still needs a sandbox strong enough that a decorative widget cannot acquire host authority.
+
+## Example workflow
+
+Tess builds a scoring widget on a planning Page, verifies static export, then chooses Save as Custom Block; the original remains local.
+
+## Product contract
+
+- Artifact Blocks have no catalog identity until a user explicitly saves one as a Custom Block.
+- The sandbox receives only bound typed props and has no ambient Content data, actions, cookies, filesystem, parent DOM, secrets, or network.
+- Export uses a declared static fallback; promotion preserves provenance rather than silently changing reuse scope.
+
+## Boundaries and non-goals
+
+- `content.renderer.custom-block` owns reusable catalog definitions; Artifact Blocks own a page/block-local instance and explicit promotion.
+- Artifacts are not Extensions, do not receive ambient host grants, and do not enter a catalog merely because they ran.
+
+## Acceptance stories
+
+### Keep it page-owned
+
+Given the artifact is copied, when the original changes, then the copy is not silently shared.
+
+### Deny ambient authority
+
+Given artifact code requests cookies, Content actions, parent DOM, or network, then the sandbox rejects it.
+
+## Current evidence
+
+`app/blocks/contentBlockRegistry.tsx` and Extension sandbox code donate substrate; no Artifact Block lifecycle is implemented.
+
+## Proof plan
+
+1. Create empty and typed-prop artifacts with no catalog record.
+2. Deny SQL/actions/cookies/secrets/DOM/filesystem/network.
+3. Verify copy and static export never execute for readers.
+4. Promote and inspect distinct catalog provenance.
+
+## Open questions
+
+No question remains: network is out of the first contract.

package/corpus/templates/content/docs/product/capabilities/content.renderer.custom-block.md

@@ -0,0 +1,81 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.renderer.custom-block"
+name: "Custom Blocks"
+user_promise: "Name, govern, and reuse a safe renderer without making it a hidden application."
+primary_user_job: "Adopt a governed renderer with explicit inputs and origin."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.typed", "content.source.adapters"]
+related_features: ["content.feature.build-new-surfaces"]
+roadmap_boundary: "feature"
+acceptance_summary: "Custom Blocks have one catalog identity with personal or organization ownership and Content-managed, repository-backed, or provider-backed origin; typed props are optional, discovery is shared, runtime authority is origin-aware, one-off Artifacts promote explicitly, and export is deterministic."
+proof_requirements:
+  [
+    "Ownership scope governs reuse and approval; origin says where source truth lives, and the axes remain independent.",
+    "Slash discovery exposes governed metadata, optional typed inputs, provenance, availability, and a useful preview or fallback.",
+    "Content-managed bundles receive explicit props only in a strict sandbox; source-backed code needs a trusted adapter renderer or visible fallback, and Artifact promotion creates a new catalog identity.",
+    "Extensions retain their visible grants and identity; deterministic export never grants execution authority.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Custom Blocks
+
+## Why this exists
+
+Reusable components must be discoverable and governable without becoming opaque bundles of code with accidental powers. The source of a component and the people allowed to reuse it are separate questions that must remain visible.
+
+## Example workflow
+
+An operations lead approves a repository-backed status card, inserts it from slash search, binds typed props, and gets adapter fallback instead of repository execution.
+
+## Product contract
+
+- Ownership scope governs reuse and approval; origin says where source truth lives, and the axes remain independent.
+- Every entry has stable identity plus name, description, aliases, category, compatibility, icon, ownership, origin, and optional preview metadata. Slash insertion searches that contract; `@` remains for references and expressions.
+- Props are optional. A block may be a fixed renderer with no inputs or expose typed inputs that the editor validates and binds explicitly.
+- Content-managed bundles receive explicit props only in a strict sandbox; source-backed code needs a trusted adapter renderer or visible fallback.
+- **Save as Custom Block** promotes a page-owned Artifact into a new catalog entry while preserving provenance. Copying an Artifact alone never enrolls it in the catalog.
+- An Extension is a more capable application with grants and is never silently presented as a Custom Block.
+- Public or static output uses a deterministic declared fallback and never executes merely because the Custom Block is visible.
+
+## Boundaries and non-goals
+
+- Source adapters own repository/provider synchronization; the Custom Block catalog owns reusable renderer identity, governance, origin metadata, and typed props.
+- Artifact Blocks own one-off page-local HTML/CSS/JS and promotion. Built-in Blocks may implement the same discovery contract but do not masquerade as editable Custom Blocks.
+- Custom Blocks are renderers, not Extensions: they do not acquire arbitrary Actions, ambient Content data, filesystem, parent DOM, secrets, cookies, or network authority.
+
+## Acceptance stories
+
+### Keep axes independent
+
+Given a personal repository-backed block is shared, when scope changes, then repository origin remains unchanged.
+
+### Do not disguise Extensions
+
+Given an Extension has grants, when embedded, then it remains a visible Extension embed.
+
+### Promote one Artifact deliberately
+
+Given a page-owned Artifact has no catalog record, when its owner chooses Save as Custom Block, then Content creates one governed catalog identity with provenance and leaves ordinary copied Artifacts local.
+
+## Current evidence
+
+`app/components/editor/extensions/LocalMdxComponentNode.tsx`, `actions/list-local-component-files.ts`, `actions/write-local-component-file.ts`, and `app/blocks/contentBlockRegistry.tsx` are donors, not a hosted catalog.
+
+## Proof plan
+
+1. Test managed, repository, and provider origins with no props, typed props, local aliases, and origin-preserving scope changes.
+2. Test slash discovery and insertion across compatibility, permissions, preview, validation, unavailable origin, Versions, and provenance.
+3. Deny ambient data, Actions, cookies, secrets, DOM, filesystem, and network; verify trusted adapter fallback without executing repository code in the sandbox.
+4. Promote a one-off Artifact, copy it without promotion, export every origin deterministically, and distinguish built-ins and Extensions.
+
+## Open questions
+
+Catalog version/update policy and the first trusted-adapter eligibility rules still need a dedicated Shape. Network grants remain Extension territory rather than a Custom Block option.

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

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.renderer.graph"
+name: "Collection graph renderers (superseded)"
+user_promise: "Historical umbrella for graph and chart rendering, now split into distinct semantic Graph and analytical Chart capabilities"
+primary_user_job: "Follow the lineage from the former combined renderer concept to the precise modern capability that owns the work."
+kind: "surface"
+state: "superseded"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.typed", "content.view.grouping-aggregation"]
+related_features: []
+roadmap_boundary: "superseded"
+acceptance_summary: "No implementation should target this ambiguous umbrella; analytical rendering belongs to Chart View, semantic relationship exploration belongs to Graph View, and reusable compatibility/export mechanics belong to Typed Renderers."
+proof_requirements:
+  [
+    "Every former analytical responsibility resolves to content.view.chart or content.renderer.typed",
+    "Every former semantic-relationship responsibility resolves to content.view.graph",
+    "No Feature or implementation treats this record as an active contract",
+  ]
+evidence: []
+superseded_by: "content.view.chart"
+last_reviewed: "2026-07-29"
+---
+
+# Collection graph renderers (superseded)
+
+## Why this exists
+
+The early catalog used `Graph` to mean both an analytical chart over grouped records and a semantic network of Pages and Relationships. Those are different user jobs, interaction models, dependencies, and proof gates. Keeping the umbrella active would make an implementer guess which meaning was intended.
+
+## Example workflow
+
+A developer asked to add a bar chart follows `content.view.chart`. A developer asked to let someone explore and edit `supports` relationships follows `content.view.graph`. Both reuse `content.renderer.typed` for compatibility, accessibility, and export behavior.
+
+## Product contract
+
+- `content.view.chart` owns analytical visualizations over typed Query results, grouping, measures, drill-down, saved Views, embedded Blocks, dashboards, and static output.
+- `content.view.graph` owns query-selected canonical nodes, typed Relationship edges, semantic exploration, and authorized edge editing.
+- `content.view.canvas` owns intentional spatial arrangement, view-local connectors, and explicit connector promotion.
+- `content.renderer.typed` owns the shared renderer registry, typed compatibility, inheritance, accessible degradation, and export fallback.
+- Authored Mermaid diagrams remain Code blocks with a Mermaid renderer; they are neither analytical Charts nor semantic Graphs.
+
+## Boundaries and non-goals
+
+- Do not add new dependencies, Features, or implementation evidence to this record.
+- Do not use `Graph` as a synonym for `Chart` in new product contracts.
+- Do not delete this record; it preserves stable-ID lineage for older references.
+
+## Acceptance stories
+
+### Route analytical work correctly
+
+Given a change that renders grouped measures as bars, lines, or another statistical graphic, when product context is resolved, then the active contract is Chart View plus Typed Renderers and this record is not treated as implementable.
+
+### Route semantic work correctly
+
+Given a change that traverses or edits typed Page Relationships, when product context is resolved, then the active contract is Graph View plus the graph-query and Relationship capabilities.
+
+## Current evidence
+
+The modern catalog already contains separate Chart, Graph, Canvas, and Typed Renderer records. This lineage correction changes no runtime behavior and makes no implementation claim.
+
+## Proof plan
+
+Validate that no Feature requires this ID, repository guidance resolves both historical meanings to active records, generated projections label it superseded, and the dependency graph retains valid one-target lineage through `content.view.chart` while naming `content.view.graph` in this body.
+
+## Open questions
+
+The schema currently permits one `superseded_by` target. This record points to Chart because its original dependencies were analytical; the body preserves the separate Graph lineage. Supporting several replacement IDs may be considered later if the broader catalog needs it.