@agent-native/core 0.130.2 → 0.131.3

package/corpus/templates/content/docs/product/capabilities/content.source.file-folder.md

@@ -0,0 +1,71 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.source.file-folder"
+name: "Files and folders as Sources"
+user_promise: "Open a selected file tree as a Source without forcing heterogeneous files into one Database schema."
+primary_user_job: "Browse and work with a local folder through Content while retaining file identity, hierarchy, device limits, and source ownership."
+kind: "primitive"
+state: "exploring"
+publicness: "public"
+availability: "configured"
+dependencies:
+  ["content.source.adapters", "content.portability.source-representation"]
+related_features: ["content.feature.bring-your-local-work"]
+roadmap_boundary: "feature"
+acceptance_summary: "A folder Source models a selected root and heterogeneous file representations with stable source identity and hierarchy, materializes only supported authorized content, and delegates physical authority, sync, and write-back to the Source adapter and local bridge."
+proof_requirements:
+  [
+    "Folder identity, hierarchy, heterogeneous representation, and source-metadata tests",
+    "Access, local-path redaction, add/change/delete/rename/conflict/degraded-client tests",
+    "Selected-folder workflow covering browse, open, external change, unavailable device, and disconnect",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Files and folders as Sources
+
+## Why this exists
+
+A folder is a living landscape of unlike things; it should not have to masquerade as one spreadsheet.
+
+## Example workflow
+
+A developer selects a documentation folder. Content shows a source-root hierarchy, opens supported files as Pages, keeps unknown files identifiable, and shows last synchronized material when a browser lacks the local bridge.
+
+## Product contract
+
+- A folder Source retains selected-root, relative hierarchy, file identity, representation kind, baseline, and provenance without exporting raw paths or handles to shared clients.
+- Files may map to different Content representations or remain opaque/unavailable; no common Database schema is assumed.
+- Physical reads, watches, writes, rename/delete behavior, conflict, and bridge availability follow adapter and local-bridge policy.
+- Removing a connection stops future source access without silently deleting external originals.
+
+## Boundaries and non-goals
+
+Local bridge owns device authority; portable representation owns materialization; Files UI is a projection. This is not a universal filesystem browser or arbitrary directory access grant.
+
+## Acceptance stories
+
+### Browse heterogeneous material
+
+Given a selected folder with Markdown, PDF, and unsupported binary files, when it materializes, then Content preserves hierarchy and source identity while exposing only the representations each file supports.
+
+### Degrade without exposing paths
+
+Given a browser without bridge authority, when it opens a materialized folder item, then it can read the last authorized representation but cannot reveal the local path or invoke physical file operations.
+
+## Current evidence
+
+Donor evidence: `actions/connect-local-folder-source.ts`, `actions/sync-local-folder-source.ts`, `actions/local-folder-source.db.test.ts`, and sidebar source handling establish local-folder substrate. The common heterogeneous folder contract and complete authority/recovery proof remain exploratory.
+
+## Proof plan
+
+1. Define folder/file representation and hierarchy contract independent of one Database schema.
+2. Test file lifecycle, path redaction, bridge absence, conflicts, and disconnect.
+3. Verify selection, browse, sync, external change, and repair through the interface.
+
+## Open questions
+
+- Supported file-family order and directory-scale behavior remain open.

package/corpus/templates/content/docs/product/capabilities/content.source.local-bridge.md

@@ -0,0 +1,156 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.source.local-bridge"
+name: "Local Source bridge"
+user_promise: "A trusted device can synchronize explicitly selected local Sources while browsers remain useful without inheriting filesystem authority."
+primary_user_job: "Work with a local folder across devices without exposing its path, handles, or direct filesystem power to every browser."
+kind: "surface"
+state: "approved_shape"
+publicness: "public"
+availability: "desktop"
+dependencies: ["content.source.adapters", "content.source.sync-policy"]
+related_features:
+  [
+    "content.feature.bring-your-local-work",
+    "content.feature.take-the-whole-vault-with-you",
+    "content.feature.keep-your-private-vault-private",
+  ]
+roadmap_boundary: "feature"
+acceptance_summary: "A device-authorized bridge holds selected-root authority locally, synchronizes access-scoped materializations through the Source contract, validates every physical operation and base revision, queues permitted write-back truthfully, and lets unsupported clients use the last authorized representation without receiving filesystem authority."
+proof_requirements:
+  [
+    "Device pairing, root grants, capability revocation, path containment, payload bounds, and origin/client authorization tests",
+    "End-to-end bridge synchronization, base-version conflict, queue, retry, receipt, disconnect, and degraded-client workflows",
+    "Security and privacy review proving raw paths/handles stay local and no webpage or browser client gains general filesystem or command authority",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Local Source bridge
+
+## Why this exists
+
+A local folder should participate in the same Content workspace without making
+the folder a shared database or granting every browser the ability to inspect a
+device. Some clients can hold a user-granted folder capability; many cannot.
+The bridge keeps that difference honest while preserving ordinary Content work.
+
+## Example workflow
+
+A person grants a trusted desktop app access to one documentation folder. The
+bridge materializes authorized files into Content and watches the granted root.
+Later, a browser without local-file capability reads the last synchronized
+representation, adds a permitted source-owned edit, and sees **waiting for
+local access** rather than **synced**. When the trusted device returns, the
+bridge checks the base revision, writes or raises a conflict, and emits a
+receipt. The browser never receives the folder path or direct file handle.
+
+## Product contract
+
+### One narrow device-authorized protocol
+
+- The Local Source Bridge is one Source-adapter protocol. A trusted desktop app
+  implements it first; a lightweight helper or optional browser transport may
+  later use the same contract rather than create separate sync engines.
+- A person explicitly selects roots and grants read and write capability
+  separately. Hosted Content stores opaque connection IDs, Source metadata,
+  baselines, and access-scoped materializations, never raw paths or operating
+  system handles.
+- Every physical operation validates the paired client/origin, connection,
+  granted root, operation capability, normalized relative path, payload bound,
+  and base version. Traversal, root escape through symlinks, arbitrary shell
+  execution, and a general webpage-to-native command channel are prohibited.
+- The bridge reads, watches, and writes only declared Source representations;
+  it uses the same policy, conflict, Event, and receipt contract as other
+  adapters.
+
+### Degrade without pretending authority exists
+
+- A browser or device that lacks persistent folder access can read the last
+  access-authorized SQL materialization and continue SQL-owned work such as
+  Views, Queries, memberships, collaboration, and Content-owned properties.
+- It does not inherit desktop filesystem authority. Direct local-only actions,
+  such as immediate physical writes or opening bytes never materialized, are
+  unavailable on that client and identify the applicable trusted route.
+- When policy permits, source-owned outbound edits can queue with their base
+  version until an authorized bridge returns. Queued, stale, unavailable,
+  conflict, failed, and provider-confirmed states remain distinct.
+- The normal interface stays quiet until a requested operation genuinely needs
+  unavailable local bytes or authority. Loss of a bridge narrows the Source on
+  that client; it does not hide the Source or make unrelated Content read-only.
+
+### Keep custody and recovery explicit
+
+- Reconnection refreshes freshness before applying queued work. Incompatible
+  upstream edits enter review rather than overwriting local files.
+- Each bridge operation produces ordinary actor/origin-aware Events and sync
+  receipts. Retries use stable identity and must not duplicate physical effects.
+- Disconnecting or revoking a bridge grant stops future device access and never
+  deletes external originals. Treatment of any Content materialization is an
+  explicit separate decision under Source policy and portability rules.
+
+## Boundaries and non-goals
+
+- Files and folders as Sources owns how a selected tree materializes as Content
+  records. This bridge owns device authority and transport, not a second Files
+  product.
+- Sync policy owns View only, Keep in sync, and Review before write-back;
+  adapters own capability declarations. The bridge implements those contracts
+  for local authority.
+- This Capability does not require every browser to install an extension, make
+  a browser's folder picker equivalent to desktop authority, or expose a
+  loopback service to arbitrary webpages.
+
+## Acceptance stories
+
+### Synchronize without disclosing a local path
+
+Given a person grants one root to a paired bridge, when the bridge synchronizes
+an authorized file into Content, then shared records contain only opaque Source
+connection and representation metadata, while the raw path and handle remain
+on the device.
+
+### Queue honestly on an unsupported client
+
+Given a browser without local bridge capability and a Source policy that permits
+write-back, when an editor changes a source-owned field, then Content records a
+base-versioned queued change and shows a waiting state; it does not claim the
+file changed or grant the browser direct access to the folder.
+
+### Block root escape and preserve the original on disconnect
+
+Given a paired bridge receives a write request whose path escapes the granted
+root, when it validates the request, then it rejects the operation with no file
+mutation and an honest failure. Given the owner later disconnects the Source,
+then the bridge stops access without deleting the original local file.
+
+## Current evidence
+
+Local File Mode, connected-folder Sources, conflict records, and trusted local
+bridge pieces provide substantial foundation. They do not yet prove dependable
+background synchronization, uniform device pairing/revocation, browser queue
+behavior, or the complete protocol security and recovery contract. This
+Capability remains `approved_shape`.
+
+## Proof plan
+
+1. Test root selection, pairing, origin/client allowlists, separate read/write
+   grants, revocation, normalized paths, symlink escapes, oversized payloads,
+   and rejected operations without filesystem side effects.
+2. Exercise initial materialization, watch refresh, authorized write-back,
+   queues, reconnect freshness checks, conflicts, retries, receipts, pauses,
+   and disconnect across a desktop bridge and an unsupported browser client.
+3. Verify access-scoped materialization and changing Content permissions never
+   convert one person's device grant into another person's filesystem access.
+4. Complete the real interface workflow for selection, degraded states,
+   contextual unavailable operations, recovery, and accessible status text.
+
+## Open questions
+
+- The exact pairing ceremony, background-service packaging, and optional
+  browser transport remain open provided they preserve the one narrow protocol.
+- Cache retention, offline capacity, and the detailed user choice for retaining
+  materialized Content on disconnect need portability design.

package/corpus/templates/content/docs/product/capabilities/content.source.local-project.md

@@ -0,0 +1,70 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.source.local-project"
+name: "Local project mode"
+user_promise: "The former local-project proposal remains lineage for file-truth work, not an active dual-truth product contract."
+primary_user_job: "Understand that selected local Sources use the common Source model and portable representation rather than a separate local-project system."
+kind: "primitive"
+state: "superseded"
+publicness: "public"
+availability: "configured"
+dependencies:
+  ["content.source.adapters", "content.portability.source-representation"]
+related_features: []
+roadmap_boundary: "superseded"
+acceptance_summary: "This lineage record directs new local-file work to Source adapters, portable representations, folder Sources, and the local bridge; it preserves the no-default-SQL/git-dual-truth constraint and does not define a separate active mode."
+proof_requirements:
+  [
+    "Catalog validation of the supersession target",
+    "Review of new local-source work for one Source contract and explicit truth/write policy",
+    "Regression review that rejects default SQL and filesystem or git dual truth",
+  ]
+evidence: []
+superseded_by: "content.source.adapters"
+last_reviewed: "2026-07-29"
+---
+
+# Local project mode
+
+## Why this exists
+
+The early local-project label is useful history, but a separate mode would make files and hosted Content argue over who is real.
+
+## Example workflow
+
+A contributor planning local repository support follows the active Source adapter, file/folder, representation, and bridge records rather than adding a special project datastore.
+
+## Product contract
+
+- This is lineage only; active local work uses the common Source model.
+- A selected source declares its truth, representation, and write policy. SQL materialization and filesystem or git originals are not default competing truths.
+- Migration between local and hosted forms must be explicit and preserve provenance, conflict, and recovery semantics.
+
+## Boundaries and non-goals
+
+This does not specify a new local mode, branch workflow, repository UI, or source synchronization engine.
+
+## Acceptance stories
+
+### Route new local work to active contracts
+
+Given a request to add a local file workflow, when it is planned, then it names Source adapter and representation boundaries rather than creating a `local-project` mutation path.
+
+### Refuse accidental dual truth
+
+Given a proposed feature stores editable copies in SQL and a repository by default, when reviewed, then it is rejected until one authoritative write and recovery policy is explicit.
+
+## Current evidence
+
+Repository product records identify `content.source.adapters` as the active target. This superseded record makes no implementation or verification claim.
+
+## Proof plan
+
+1. Keep the supersession edge valid.
+2. Review local-source changes for explicit source truth and migration policy.
+3. Require adapter/representation proof for any future local workflow.
+
+## Open questions
+
+- None; active design questions belong to the successor records.

package/corpus/templates/content/docs/product/capabilities/content.source.page-link.md

@@ -0,0 +1,70 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.source.page-link"
+name: "Page-linked Sources"
+user_promise: "A Page can bind to one external item while keeping Content identity and the provider's ownership clear."
+primary_user_job: "Open a connected item as a Page and know which values come from its Source, which Content owns, and where an edit will go."
+kind: "primitive"
+state: "exploring"
+publicness: "public"
+availability: "configured"
+dependencies: ["content.source.adapters", "content.object.page"]
+related_features: ["content.feature.connect-your-sources"]
+roadmap_boundary: "feature"
+acceptance_summary: "A Page may carry one explicit external-item binding with stable source and provider identity, representation and baseline metadata, ownership-aware fields and actions, provenance, and source-policy routing without creating a parallel page-source architecture."
+proof_requirements:
+  [
+    "Binding identity, uniqueness, provenance, access, and Page lifecycle tests",
+    "Field ownership, write routing, baseline/conflict, detach, and source-unavailable tests",
+    "Page workflow opening a connected item, inspecting provenance, editing a mapped value, and resolving a conflict",
+  ]
+evidence: []
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Page-linked Sources
+
+## Why this exists
+
+A connected item deserves a familiar Page without asking it to surrender where it came from.
+
+## Example workflow
+
+A person opens a provider article as a Page, sees source provenance and mapped fields, edits one writable field, and receives a source receipt or a conflict rather than an ambiguous local save.
+
+## Product contract
+
+- A Page has one explicit external item binding when this capability applies; the binding carries Source, provider identity, representation, baseline, and provenance.
+- Content identity, comments, memberships, views, and Content-owned fields remain Content-owned. Source-owned values route only through declared adapter policy.
+- The page shows freshness, availability, ownership, conflict, and write outcome honestly. Detach is explicit and preserves provenance/history.
+- The binding is a normalized use of the Source adapter model, not a separate data architecture.
+
+## Boundaries and non-goals
+
+Multi-source composition belongs to Queries; folder hierarchy belongs to folder Sources. This does not assert that all Pages have or need an external binding.
+
+## Acceptance stories
+
+### Route a mapped edit
+
+Given a Page linked to one writable external item, when an editor changes a source-owned mapped field, then the adapter receives that one authorized change and the receipt names the provider outcome.
+
+### Keep Content work after source loss
+
+Given the linked Source becomes unavailable, when a reader opens the Page, then Content shows the last authorized representation and source status while preserving Content-owned comments and memberships.
+
+## Current evidence
+
+Donor evidence: `actions/_document-source.ts`, `shared/content-source.ts`, and source-backed database actions model parts of binding/provenance. No normalized Page binding, ownership UI, or full conflict proof exists; this record remains `exploring`.
+
+## Proof plan
+
+1. Define binding cardinality, provenance, ownership, detach, and state model.
+2. Test access, route selection, base revisions, conflicts, unavailable source, and detachment.
+3. Verify linked Page workflow through the editor and source receipts.
+
+## Open questions
+
+- Whether a Page may bind multiple representations of one provider item needs a later Shape.

package/corpus/templates/content/docs/product/capabilities/content.source.row-union.md

@@ -0,0 +1,69 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.source.row-union"
+name: "Materialized multi-source Databases"
+user_promise: "The former multi-source row-union model remains migration evidence, while active composition moves toward source Queries."
+primary_user_job: "Understand the proven source-scoped row behavior without mistaking it for the active composition contract."
+kind: "primitive"
+state: "superseded"
+publicness: "public"
+availability: "configured"
+dependencies: ["content.source.adapters", "content.object.database"]
+related_features: []
+roadmap_boundary: "superseded"
+acceptance_summary: "This lineage record preserves donor evidence for source-scoped rows, per-source field bindings, source selection, and guarded writes while directing new multi-source composition to saved source Queries and their access-safe semantics."
+proof_requirements:
+  [
+    "Catalog validation of the supersession target",
+    "Regression tests retaining source-scoped identity and guarded writes while legacy behavior remains",
+    "Design review that routes new multi-source composition to content.view.source-query",
+  ]
+evidence: []
+superseded_by: "content.view.source-query"
+last_reviewed: "2026-07-29"
+---
+
+# Materialized multi-source Databases
+
+## Why this exists
+
+The row-union experiment taught useful boundaries, but its configuration surface is not the chosen future composition model.
+
+## Example workflow
+
+A maintainer fixing a legacy multi-source row preserves its source-scoped identity and write route, while a new combined view is designed as a saved source Query.
+
+## Product contract
+
+- This record is donor and migration lineage, not new feature direction.
+- Legacy rows preserve source-scoped identity, selected source for new rows, visible Source provenance, per-source field bindings, and guarded source writes.
+- New composition evaluates through `content.view.source-query`, where access and ownership are explicit rather than materialized into a confusing universal row surface.
+
+## Boundaries and non-goals
+
+This does not revive multi-source Database configuration, prove Query behavior, or authorize a bulk migration without its own recovery plan.
+
+## Acceptance stories
+
+### Preserve a legacy row route
+
+Given a legacy row from a writable Source, when it is edited through its mapped binding, then only that Source receives the guarded change and the row retains source identity.
+
+### Design new composition as a Query
+
+Given a request to combine two Sources, when a new experience is planned, then it uses the saved source Query contract instead of adding another row-union configuration path.
+
+## Current evidence
+
+Donor evidence: `actions/_content-database-source-adapters.ts`, `actions/content-database-source-actions.test.ts`, and Builder source tests cover source-backed row behavior. This record is superseded and makes no active whole-contract claim.
+
+## Proof plan
+
+1. Keep source-scoped legacy tests while the model remains supported.
+2. Validate the supersession link and review new composition work for Query ownership.
+3. Plan any migration with identity, access, conflict, and rollback evidence.
+
+## Open questions
+
+- Legacy removal timing is intentionally not decided here.

package/corpus/templates/content/docs/product/capabilities/content.source.spaces-files.md

@@ -0,0 +1,75 @@
+---
+record_type: "capability"
+spec_version: 2
+id: "content.source.spaces-files"
+name: "Content spaces and Files"
+user_promise: "Personal and organization-backed Content spaces and Files views keep work navigable without becoming a second permission system."
+primary_user_job: "Find, enter, and organize authorized work in the right space while knowing that sidebar arrangement does not rewrite shared ownership."
+kind: "primitive"
+state: "verified"
+publicness: "public"
+availability: "configured"
+dependencies: []
+related_features: ["content.feature.find-your-place-again"]
+roadmap_boundary: "feature"
+acceptance_summary: "Content provides database-backed personal and organization spaces, Files and Workspace/sidebar projections, explicit scope-aware selection, and source-as-adapter handling while access remains enforced by the shared resource model."
+proof_requirements:
+  [
+    "Schema and action tests for scope-aware spaces, Files membership, and source handling",
+    "Sidebar selection, ordering, drag/drop, and access-boundary regression tests",
+    "Interface workflow entering a space, organizing Files, reopening a source-backed item, and handling unavailable scope",
+  ]
+evidence:
+  [
+    "../../../server/db/schema.ts",
+    "../../../app/components/sidebar/DocumentSidebar.tsx",
+    "../../../app/components/sidebar/DocumentSidebar.layout.test.ts",
+  ]
+superseded_by: null
+last_reviewed: "2026-07-29"
+---
+
+# Content spaces and Files
+
+## Why this exists
+
+People need a place to arrive and a way to arrange it, without mistaking a sidebar for the constitution.
+
+## Example workflow
+
+A teammate enters an organization space, opens its Files view, reorders a personal sidebar preference, and opens a source-backed item without changing the source's ownership or another person's arrangement.
+
+## Product contract
+
+- Personal and organization-backed spaces organize Content navigation and memberships; shared access remains the resource/access model's responsibility.
+- Files, Workspaces, and sidebar sections are projections over Content objects and source-backed items, not a rival Source architecture.
+- Scope selection and saved personal navigation state are explicit. Personal ordering does not silently mutate shared Database membership or reparent a Page.
+- Source-backed entries retain source-adapter boundaries and unavailable states rather than pretending all files are native Content.
+
+## Boundaries and non-goals
+
+Global Home and session restore own cross-space arrival; source adapters own provider behavior. Spaces do not grant access merely because an item appears in a sidebar.
+
+## Acceptance stories
+
+### Keep a personal reorder personal
+
+Given two people share a Files view, when one reorders their custom sidebar arrangement, then their preference persists without changing the other person's order or shared membership positions.
+
+### Respect space access
+
+Given a stale link to an organization-backed item, when a person without current access opens it, then the interface gives an honest access state and does not expose the item's title or source data.
+
+## Current evidence
+
+Implementation evidence: `server/db/schema.ts`, `app/components/sidebar/DocumentSidebar.tsx`, and `app/components/sidebar/DocumentSidebar.layout.test.ts` cover database-backed sidebar/Files behavior and source handling. The cited tests support the present atomic contract; Feature-level arrival proof remains separate.
+
+## Proof plan
+
+1. Maintain schema/action coverage for personal and organization scope boundaries.
+2. Run sidebar ordering and source-backed-item regression suites.
+3. Periodically verify the real interface workflow across scope changes and denied links.
+
+## Open questions
+
+- Broader Home and cross-space resumption improvements belong to their dedicated capabilities.