@agent-native/core 0.130.2 → 0.131.2

package/corpus/templates/content/docs/product/capabilities/content.portability.pdf-export.md

@@ -0,0 +1,78 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.portability.pdf-export"
+name: "PDF export"
+user_promise: "Create a readable PDF of an authorized Content representation without confusing it with the editable or lossless export."
+primary_user_job: "Hand someone a stable, readable document that faithfully represents what I am authorized to share."
+kind: "workflow"
+state: "in_progress"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.renderer.typed", "content.access.visibility-closure"]
+related_features:
+  [
+    "content.feature.publish-with-confidence",
+    "content.feature.take-the-whole-vault-with-you",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "PDF export resolves the acting user's authorized representation through shared rendering, gives supported blocks a faithful layout or explicit fallback, and returns a durable file with clear scope and failure reporting."
+proof_requirements:
+  [
+    "Renderer fidelity tests for supported blocks, media, math, code, and explicit fallbacks",
+    "Access-closure, asset, pagination, metadata, and error reporting tests",
+    "Interface export workflow validated against the selected representation and downloaded PDF",
+  ]
+evidence:
+  [
+    "../../../shared/document-export.ts",
+    "../../../shared/document-export.spec.ts",
+  ]
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# PDF export
+
+## Why this exists
+
+PDF is a dependable reading artifact, not a promise that a flat page can carry every living behavior.
+
+## Example workflow
+
+An editor exports the approved article revision. Content renders the same authorized blocks, reports an unavailable protected asset, and produces a PDF whose scope identifies the selected representation.
+
+## Product contract
+
+- Export materializes the acting user's authorized closure at export time; it never borrows a collaborator's access.
+- It uses shared semantic rendering where possible and provides deliberate, readable fallbacks for unsupported interactive behavior.
+- The artifact records enough representation and generation context to explain what it contains. Asset failures are reported, not silently omitted.
+- A PDF is read-oriented output, separate from editable source and lossless archive formats.
+
+## Boundaries and non-goals
+
+Publication owns stable public URLs; vault export owns complete package closure. PDF export does not promise round-trip editing or live embeds.
+
+## Acceptance stories
+
+### Export only the viewer's closure
+
+Given a Page references an inaccessible private asset, when a permitted editor exports it, then the PDF does not expose the asset and reports the unavailable representation.
+
+### Render a deliberate fallback
+
+Given a supported Page contains an interactive Block without a print equivalent, when it exports, then the PDF includes a labeled safe fallback rather than pretending the interaction survived.
+
+## Current evidence
+
+Implementation evidence: `shared/document-export.ts` and `shared/document-export.spec.ts` cover current document export machinery. Donor evidence does not yet prove all block fidelity, access closure, or interface-level PDF behavior, so this record remains `in_progress`.
+
+## Proof plan
+
+1. Expand fixture coverage across supported blocks and intentional fallbacks.
+2. Test access changes, media resolution, metadata, pagination, and failures.
+3. Compare a real export against the selected authorized representation.
+
+## Open questions
+
+- Print styling and accessibility metadata policy need final acceptance criteria.

package/corpus/templates/content/docs/product/capabilities/content.portability.roundtrip.md

@@ -0,0 +1,154 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.portability.roundtrip"
+name: "Faithful round-tripping"
+user_promise: "Content preserves provider-owned meaning it cannot safely render or edit, so a supported change never silently destroys the rest of the work."
+primary_user_job: "Edit what Content understands while keeping connected and portable work recoverable and intelligible outside one application."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.portability.source-representation"]
+related_features:
+  [
+    "content.feature.trust-your-connected-sources",
+    "content.feature.cite-what-you-found",
+    "content.feature.take-the-whole-vault-with-you",
+    "content.feature.move-without-starting-over",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Authorized imports, edits, exports, and provider write-back preserve stable identity, known semantics, provenance, and unknown provider structures through explicit raw or typed fallback representations, while reporting unsupported or unresolved material instead of silently flattening it."
+proof_requirements:
+  [
+    "Golden import-edit-export and provider write-back fixtures covering known, unknown, mixed, and malformed representations",
+    "Stable identity, provenance, block/comment/reference/custom structure, and source mapping preservation or explicit unresolved reporting",
+    "Conflict, access, recovery, and lossless archive verification across at least two independently certified adapter formats",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Faithful round-tripping
+
+## Why this exists
+
+People bring work with structure Content may not yet understand: provider
+components, bindings, embeds, custom blocks, references, comments, and other
+format-specific detail. A friendly editable view is not permission to discard
+what it cannot represent. Lossy simplicity has excellent manners right up to
+the moment it loses a component.
+
+## Example workflow
+
+An editor opens a provider article containing ordinary text and an unsupported
+component. Content renders and edits the text through its native grammar while
+retaining the unsupported component as a preserved source-backed representation.
+After the editor changes the text and completes the Source's allowed write-back
+flow, the provider receives the changed text and the unknown component remains
+unchanged. A later export includes the information needed to preserve both the
+known Content semantics and unresolved provider material.
+
+## Product contract
+
+### Preserve what is known and what is not
+
+- A source representation maps known semantics into typed Content structures
+  only when that mapping is safe. It retains stable source identity,
+  provenance, ordering, and enough fidelity information to reconstruct the
+  provider-facing representation.
+- Unknown, unsupported, or not-yet-safe provider material survives as an
+  explicit raw or typed fallback with source identity and an inspectable status.
+  It is not flattened into ordinary text, silently dropped, or presented as a
+  fully editable native Block.
+- Known native-like semantics may render through ordinary Content Blocks while
+  retaining their source binding. Provider-specific reusable or custom
+  components remain source-backed until explicitly forked with provenance.
+- Expressions, references, custom blocks, comments, block identities, and
+  other typed Content structures need exact encodings or an explicit unresolved
+  representation; a best-effort export may not claim lossless completion.
+
+### Round trips retain authority and recoverability
+
+- Import, refresh, edit, export, and provider write-back retain the source
+  mapping, baseline, ownership, and policy needed to route later work safely.
+- A compatible Content edit changes only the mapped authorized portion. It
+  preserves unknown siblings and provider-owned fields outside that mapping.
+- Access applies before import preview, export, provider write-back, raw
+  fallback inspection, and recovery. Export includes only material the acting
+  user may access and reports unavailable or excluded dependencies.
+- A failed conversion, stale base, malformed input, or missing payload produces
+  an explicit failure or unresolved state. It never returns an empty or clean
+  representation that callers can mistake for a completed round trip.
+
+### Provider and portable forms remain distinct
+
+- The portable source representation owns provider-neutral interchange;
+  adapters and codecs own provider-specific mapping details. A provider codec
+  is not the universal Content authoring grammar.
+- A lossless archive may carry structured sidecars and stable asset handles in
+  addition to humane Markdown/MDX. Raw payloads and assets use appropriate file
+  or blob storage, not shared SQL fields.
+- Detaching or converting source-backed content into Content-managed work is an
+  explicit fork with provenance and policy consequences, never an accidental
+  outcome of opening or editing it.
+
+## Boundaries and non-goals
+
+- Sync policy decides whether and when outbound work may cross a Source
+  boundary; adapters certify a provider's codec and operations. This record
+  defines the fidelity obligation shared by those paths.
+- Faithful preservation does not promise a native editor for every provider
+  feature, universal raw-source editing, or byte-identical output where the
+  provider itself normalizes content.
+- Publication and other provider lifecycle changes are separate guarded actions.
+
+## Acceptance stories
+
+### Preserve an unknown sibling during a supported edit
+
+Given a provider representation with one editable text region and one unknown
+component, when an authorized editor changes the text and completes permitted
+write-back, then the provider receives the text change while the unknown
+component, ordering, and source identity remain intact.
+
+### Report an incomplete conversion honestly
+
+Given an import whose typed extension cannot be encoded by the target format,
+when a person exports it, then Content either emits the declared lossless
+sidecar/fallback or reports that representation as unresolved; it does not
+produce a clean-looking export that silently omits the extension.
+
+### Recover identity through a mixed-format round trip
+
+Given a Source with mapped Blocks, references, comments, and preserved raw
+provider material, when an authorized lossless archive is exported and restored,
+then stable identities, provenance, supported semantics, fallback material, and
+source mappings remain coherent or each unresolved dependency is reported.
+
+## Current evidence
+
+Content exports editable text formats and existing source machinery includes
+raw sidecars, hashes, and guarded provider paths. Those prove useful pieces,
+not a generic lossless contract across representations, access, recovery, and
+independently certified adapters. This Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Build golden fixtures for known, unknown, mixed, reordered, malformed, and
+   partially unavailable representations across at least two adapter formats.
+2. Run import, refresh, native edit, review/write-back, export, restore, and
+   re-import; compare stable identity, provenance, mapped semantics, fallback
+   payloads, source mappings, and explicit unresolved reports.
+3. Exercise stale bases, provider normalization, interrupted conversion,
+   conflicts, retries, access denial, redaction, and missing assets or handles.
+4. Verify fallback status and recovery paths in the real interface and shared
+   Actions, including accessible inspection of unsupported material.
+
+## Open questions
+
+- The canonical sidecar envelope and the exact portable encoding for every
+  typed Content structure remain implementation work.
+- Fidelity equivalence must define when provider normalization is acceptable
+  without weakening the obligation to preserve unknown meaning.

package/corpus/templates/content/docs/product/capabilities/content.portability.source-representation.md

@@ -0,0 +1,70 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.portability.source-representation"
+name: "Portable Source representation"
+user_promise: "Connected and local material has a portable Content representation without pretending Content owns every original."
+primary_user_job: "Move between local, hosted, and provider-backed work while retaining identity, provenance, fidelity limits, and a readable recovery path."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "configured"
+dependencies: ["content.source.adapters"]
+related_features: ["content.feature.bring-your-local-work"]
+roadmap_boundary: "feature"
+acceptance_summary: "A portable representation separates stable Content identity from source bindings, preserves source-owned unknown data and baselines, records fidelity and access limits, and can be materialized or repaired without default dual truth."
+proof_requirements:
+  [
+    "Representation schema and round-trip fixtures for native, provider, and local sources",
+    "Identity, provenance, unknown-data, baseline, conflict, access, and repair tests",
+    "Cross-client materialization and recovery workflow without raw local handles in shared state",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Portable Source representation
+
+## Why this exists
+
+Portability needs a map of what Content knows and what remains somewhere else, not an accidental second original.
+
+## Example workflow
+
+A local document is materialized for browser reading. Its Page identity, source binding, baseline, and unavailable local bytes remain distinguishable; an authorized bridge can later refresh or repair it.
+
+## Product contract
+
+- Stable Content identity is distinct from source connection, provider item identity, representation, baseline, and field ownership.
+- Source-owned unknown structures survive as faithful opaque data or explicit unsupported state; Content does not flatten them into editable guesses.
+- Materializations retain provenance, freshness, fidelity, and access boundaries. Local paths and handles do not enter shared state.
+- A source policy declares which direction may write and how conflict/recovery works; default SQL and filesystem dual truth is prohibited.
+
+## Boundaries and non-goals
+
+Adapters own provider behavior; round-trip owns conversion fidelity; local bridge owns device authority. This is not a universal file format or a claim of byte-perfect representation for every provider.
+
+## Acceptance stories
+
+### Preserve an unknown provider structure
+
+Given a source representation contains an unsupported provider component, when a mapped Content field changes, then the unknown component remains tied to its source identity and is not rewritten as ordinary Content data.
+
+### Keep local custody local
+
+Given a local file is materialized for another client, when that client inspects its Source metadata, then it can identify freshness and availability without receiving a raw path or filesystem handle.
+
+## Current evidence
+
+Donor evidence: `shared/content-source.ts`, `actions/_document-source.ts`, and source adapter actions model present source metadata. No complete portable representation, cross-client recovery, and fidelity proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Specify representation, baseline, opaque payload, fidelity, and access fields.
+2. Test source identities, unknown preservation, conflicts, repair, and redaction.
+3. Verify local and provider materialization across clients with no dual truth claim.
+
+## Open questions
+
+- The exact portable archive encoding for opaque provider payloads remains open.

package/corpus/templates/content/docs/product/capabilities/content.portability.vault-export.md

@@ -0,0 +1,80 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.portability.vault-export"
+name: "Portable vault export"
+user_promise: "Take the authorized Content vault away in open files plus a lossless archive instead of remaining dependent on one service."
+primary_user_job: "Export my authorized work with enough meaning, assets, provenance, and verification to use or recover it elsewhere."
+kind: "workflow"
+state: "approved_shape"
+publicness: "public"
+availability: "configured"
+dependencies:
+  [
+    "content.portability.roundtrip",
+    "content.job.durable",
+    "content.access.visibility-closure",
+  ]
+related_features:
+  [
+    "content.feature.take-the-whole-vault-with-you",
+    "content.feature.bring-your-local-work",
+    "content.feature.keep-your-private-vault-private",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "A resumable export materializes only the acting user's authorized closure into readable open files and a lossless Content archive, includes or reports assets and source handles, and supplies a verifiable conversion report."
+proof_requirements:
+  [
+    "Authorized-closure, dependency, asset, and inaccessible-reference tests",
+    "Open-package, lossless-archive, manifest, integrity, and conversion-report verification",
+    "Interrupted whole-vault export and resume workflow on a realistic corpus",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Portable vault export
+
+## Why this exists
+
+Portable work should leave with its meaning, not merely a pile of filenames.
+
+## Example workflow
+
+An administrator exports their authorized workspace. The package includes readable Markdown or MDX, tabular files, assets or stable handles, a manifest, and a Content archive; the report names inaccessible or unresolved dependencies.
+
+## Product contract
+
+- Export resolves the acting user's authorized closure at run time. It neither leaks inaccessible relations nor silently treats them as successfully included.
+- The open package uses readable files and a small manifest for stable identity and richer semantics; the lossless archive retains Content-specific history, annotations, discussion, rules, and provenance where authorized.
+- Assets are included when authorized and resolvable, otherwise represented by an honest report entry. Connected originals remain governed by Source policy.
+- Work is durable, resumable, verifiable, and separated from a disposable local cache.
+
+## Boundaries and non-goals
+
+PDF export is a reading artifact; round-trip owns format conversion; private vault owns encryption and keys. This does not promise every destination understands every Content feature.
+
+## Acceptance stories
+
+### Export only an authorized graph
+
+Given a Page references a record the exporter cannot access, when the vault exports, then the package does not include that record and the manifest reports the unresolved relationship without revealing hidden content.
+
+### Resume a large package
+
+Given export stops after writing a subset of assets, when the job resumes, then it verifies prior outputs and continues without duplicate objects or a false complete receipt.
+
+## Current evidence
+
+Donor evidence: `actions/export-document.ts`, `actions/export-content-source.ts`, and `shared/document-export.ts` cover bounded exports. No whole-vault authorized closure, lossless archive, or resume proof exists; this record remains `approved_shape`.
+
+## Proof plan
+
+1. Define package layout, manifest, archive semantics, and verification tool.
+2. Test closure, inaccessible dependencies, assets, source handles, and integrity.
+3. Run interrupted export/resume and validate the package outside Content.
+
+## Open questions
+
+- The first destination-compatible package and archive encryption handling remain open.

package/corpus/templates/content/docs/product/capabilities/content.presentation.mode.md

@@ -0,0 +1,76 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.presentation.mode"
+name: "Presentation mode"
+user_promise: "Pages and ordered records can present through shared Slides primitives without creating slide-only content."
+primary_user_job: "Present existing Content in a focused sequence without copying it into a separate slide document."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.layout.responsive", "content.renderer.typed"]
+related_features: ["content.feature.build-living-dashboards"]
+roadmap_boundary: "feature"
+acceptance_summary: "Presentation mode sequences canonical Pages or ordered records through shared slide primitives while preserving source identity, access, and ordinary editing."
+proof_requirements:
+  [
+    "Source selection, ordering, navigation, speaker-focus, and configuration persistence coverage",
+    "Canonical edit, access, sharing, export, reload, and recovery coverage",
+    "Real-interface keyboard, assistive-technology, responsive, and embedded presentation workflow",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Presentation mode
+
+## Why this exists
+
+Presenting should reveal a useful sequence, not ask people to maintain a shadow copy of
+their work in a slide-only silo.
+
+## Example workflow
+
+An editor presents an ordered set of Pages, advances with the keyboard, and corrects a
+fact through the ordinary Page editor. The next presentation uses that canonical change.
+
+## Product contract
+
+- Presentation mode is a View configuration over canonical Pages, Blocks, or ordered records.
+- Sequence, focus, and presenter controls are presentation state; source content retains identity and access.
+- Edits, sharing, export, and agent context use the same object and Action boundaries as ordinary Content.
+- Empty, unavailable, denied, and stale source states are visible rather than replaced by a blank deck.
+
+## Boundaries and non-goals
+
+Responsive layout supplies primitives. Presentation mode is not a slide-only document
+type, an animation authoring suite, or a bypass around source permissions.
+
+## Acceptance stories
+
+### Present canonical pages
+
+Given ordered authorized Pages, when a presenter enters presentation mode, then each
+slide reflects the canonical source and a viewer sees only Pages they may access.
+
+### Edit without forking
+
+Given a visible slide, when an editor changes its source Page, then the source history
+records one ordinary edit and the presentation refreshes without a duplicate slide copy.
+
+## Current evidence
+
+No complete Slides primitive or cross-surface proof is recorded. This Capability remains
+`approved_shape`.
+
+## Proof plan
+
+1. Test source selection, ordering, presenter navigation, persistence, and source mutation.
+2. Verify access, sharing, export, agent context, stale state, and recovery.
+3. Exercise keyboard, screen-reader, responsive, embedded, and reload workflows.
+
+## Open questions
+
+Speaker notes and transition scope need separate design without changing source truth.

package/corpus/templates/content/docs/product/capabilities/content.preset.catalog.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.preset.catalog"
+name: "Presets"
+user_promise: "Understand that older preassembled configurations now live as inspectable Templates rather than a competing product type."
+primary_user_job: "Follow historical Preset lineage to its Template successor."
+kind: "primitive"
+state: "superseded"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.template.graph"]
+related_features: []
+roadmap_boundary: "superseded"
+acceptance_summary: "Presets are superseded by Multi-object Templates: governed preassembled ordinary primitives continue through the Template graph and governance contracts with no alternate hidden engine."
+proof_requirements:
+  [
+    "All new reusable-system work belongs to content.template.graph and its governance/update capabilities.",
+    "A former preset must remain inspectable as ordinary Pages, Databases, Views, Properties, Rules, expressions, and bodies.",
+    "This record preserves lineage only and does not create a second catalog or migration requirement.",
+  ]
+evidence: []
+superseded_by: "content.template.graph"
+last_reviewed: "2026-07-29"
+---
+
+# Presets
+
+## Why this exists
+
+Historical Preset terminology can mislead people into looking for a separate engine that no longer exists. The lineage needs to remain legible while all real reuse work proceeds through Templates.
+
+## Example workflow
+
+A team follows a legacy Preset link to its Template graph lineage and adopts a Template version rather than creating a Preset instance.
+
+## Product contract
+
+- All new reusable-system work belongs to content.template.graph and its governance/update capabilities.
+- A former preset must remain inspectable as ordinary Pages, Databases, Views, Properties, Rules, expressions, and bodies.
+- This record preserves lineage only and does not create a second catalog or migration requirement.
+
+## Boundaries and non-goals
+
+- `content.template.graph`, Template governance, and Template updates own every successor workflow; this record preserves only the historical mapping.
+- Presets do not retain a separate catalog, instance type, mutation surface, or migration engine.
+
+## Acceptance stories
+
+### Preserve lineage only
+
+Given historical Preset provenance, when a person opens the legacy entry, then the record points to Template successor and exposes no Preset mutation action.
+
+### Use Template updates
+
+Given an old configuration changes, when its owner reviews it, then Template pinning, diff, selective apply, and detach govern it.
+
+## Current evidence
+
+`docs/product/architecture.md` and `content.template.graph.md` define the successor; no separate Presets implementation is intended.
+
+## Proof plan
+
+1. Resolve historic links to Template records.
+2. Confirm no separate Preset discovery/mutation engine.
+3. Exercise inspection/adoption/update through Template contracts.
+4. Preserve legacy provenance in export/history.
+
+## Open questions
+
+No product question remains.

package/corpus/templates/content/docs/product/capabilities/content.property.actor.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.property.actor"
+name: "Actor properties"
+user_promise: "Know who actually created or last changed a record, whether that actor was a person, agent, automation, or integration."
+primary_user_job: "Understand actual creators and editors across actor kinds."
+kind: "primitive"
+state: "approved_shape"
+publicness: "public"
+availability: "universal"
+dependencies: ["content.event.committed"]
+related_features:
+  [
+    "content.feature.durable-foundations",
+    "content.feature.data-that-keeps-itself-right",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "Created by and Last edited by are typed actor properties derived from committed mutations and retain actual actor and origin rather than a misleading shared account."
+proof_requirements:
+  [
+    "Actor values identify the actual human, agent, automation, or integration that committed the change.",
+    "Creation sets Created by once; later committed changes update Last edited by without overwriting provenance.",
+    "Denied, imported, or unavailable actor identity is represented honestly and does not collapse into a false personal attribution.",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Actor properties
+
+## Why this exists
+
+Collaboration loses accountability when automation and agents are flattened into a generic service identity. People need to distinguish who first created a record from who most recently changed it and how that change arrived.
+
+## Example workflow
+
+A coordinator creates a request, automation enriches it, and an agent edits status; Created by stays coordinator while Last edited by names the agent.
+
+## Product contract
+
+- Actor values identify the actual human, agent, automation, or integration that committed the change.
+- Creation sets Created by once; later committed changes update Last edited by without overwriting provenance.
+- Denied, imported, or unavailable actor identity is represented honestly and does not collapse into a false personal attribution.
+
+## Boundaries and non-goals
+
+- Committed events own mutation attribution and origin; Actor Properties project that record into stable created/last-edited fields.
+- Actor fields are not a permissions mechanism and do not fabricate a current-person identity when provenance is unresolved.
+
+## Acceptance stories
+
+### Keep creation provenance
+
+Given imported work is later edited, when a person commits the change, then Created by remains imported origin.
+
+### Admit unknown identity
+
+Given legacy resolution fails, when the actor Property renders, then the actor field says unresolved rather than current viewer.
+
+## Current evidence
+
+`actions/create-document.ts`, `update-document.ts`, and `edit-document.ts` are donors; `server/db/schema.ts` timestamps do not prove actor fields.
+
+## Proof plan
+
+1. Exercise person/agent/automation/integration/import/restore.
+2. Render access-aware actor and unresolved states.
+3. Export/import without identity leakage.
+4. Compare receipts and displayed actor.
+
+## Open questions
+
+Actor card versus text renderer remains open.