@agent-native/core 0.121.1 → 0.122.0

package/corpus/templates/content/.agents/skills/content/references/local-file-mode.md

@@ -0,0 +1,135 @@
+# Local File Mode Reference
+
+Content has one database-backed document model with optional folder sources.
+This file covers the folder-source workflow, the manifest/CLI bridge, and
+local MDX components in full; the `content` skill's "Local Folder Sources"
+section is the short version.
+
+## Local folder sources
+
+The `/local-files` view links one or more browser or Agent Native Desktop
+folders to SQL-backed documents. The UI uses folder rows: **Pull** calls
+`sync-local-folder-source`, **Check** runs the same action with
+`dryRun: true`, and **Push** uses the source-scoped `export-content-source`.
+Imported files become ordinary SQL documents in the target space's canonical
+Files database. Preserve frontmatter `id` across renames; missing files and
+concurrent changes become reviewable incoming change sets instead of
+silently deleting or overwriting a page. SQL stores only opaque connection
+identity, relative paths, and hashes. Disconnecting a folder keeps both the
+Content pages and disk files.
+
+## Manifest/CLI bridge
+
+`agent-native content local-files <target>` remains as a compatibility
+spelling, but it launches normal database-backed Content. `agent-native.json`
+declares `source.type: "local-folder"` and an opaque `connectionId`; it does
+not select a separate application mode. The trusted local server bridge
+materializes that source through `sync-manifest-local-folder-source`.
+
+Launch Content directly against a local folder or file with:
+
+```bash
+agent-native content local-files docs --profile docs/no-bookkeeping
+agent-native content local-files docs/guide.mdx --profile docs/no-bookkeeping
+```
+
+Minimal `agent-native.json`:
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "profile": "docs/no-bookkeeping",
+      "roots": [
+        {
+          "name": "Docs",
+          "path": "docs",
+          "profile": "docs/no-bookkeeping",
+          "extensions": [".md", ".mdx"]
+        },
+        { "name": "Blog", "path": "blog", "extensions": [".md", ".mdx"] },
+        {
+          "name": "Resources",
+          "path": "resources",
+          "extensions": [".md", ".mdx"]
+        }
+      ],
+      "components": "components"
+    }
+  }
+}
+```
+
+In Local File Mode, use the normal document actions (`list-documents`,
+`get-document`, `create-document`, `update-document`, `delete-document`)
+instead of raw filesystem writes when operating through the app. To share a
+local file, call `share-local-file-document --id <local-file-document-id>`
+first; it creates or refreshes a database-backed copy and returns the
+shareable document id. Provider sync such as Builder.io pull/push should
+remain a Content-specific explicit sync action.
+
+## Local MDX components
+
+Local file workspaces can expose React components from the configured
+`components` folder. Export PascalCase components such as `ImpactCounter`
+from `.tsx` files, then use `<ImpactCounter />` in MDX or pick it from the
+editor slash menu under Local components. Simple string props are previewed.
+Components can export editable input metadata such as `ImpactCounterInputs`
+with `string`, `textarea`, `number`, `boolean`, and `select` fields;
+selecting the component in the editor shows a corner edit button that
+rewrites the MDX props. JSX expression props are preserved in source but
+shown as an unsupported preview.
+
+## Reusable MDX references
+
+Local-file MDX can embed another local document with
+`<ContentReference sourcePath="./shared/example.mdx" />`. The editor resolves
+`sourcePath` relative to the current file, previews the referenced MDX
+read-only in place, and preserves the original tag in source. Use this for
+reusable docs fragments instead of copy/pasting shared content.
+
+## Builder Symbols
+
+Builder MDX pulls preserve Symbol blocks as `<BuilderSymbol ... />`. When
+Builder returns enriched symbol content, the pull also writes a referenced
+`.builder.mdx` file under `content/builder/symbols/` and sets the Symbol
+block's `source` attribute. Edit reusable symbol content in that emitted
+source file; do not retarget `entry`, `model`, or `source` in the parent MDX
+unless a dedicated Builder retargeting workflow is added.
+
+## Builder source components
+
+Builder CMS database body hydration renders unsupported provider-native body
+blocks as `<SourceComponent ... />` markers. These markers include
+`mappingStatus` and `sourceEditState`: `mapped` / `safe-to-edit` content has
+an explicit Markdown/NFM mapper, `preserved` / `needs-review` content keeps a
+known Builder/source component intact for review, and `unknown` /
+`preserved-only` content is an unmapped provider block that must round-trip
+as-is. Treat source-component markers as read-only preservation anchors, not
+editable local blocks. Agents may edit surrounding prose, but must not
+delete, duplicate, move, or rewrite `rawRef`, `rawHash`, mapping metadata, or
+marker ids unless a dedicated provider conversion workflow exists. Guarded
+Builder write-back refuses missing, tampered, or structurally moved markers
+so source-native components are not lost. Readable bodies hydrated before
+source-component mapping may need a fresh Builder body hydration pass before
+guarded push, because newly preserved markers are intentionally treated as
+structure changes.
+
+## Picked folders and components
+
+Browser-picked folders can be the source of truth for `.md`/`.mdx` files, but
+the browser does not expose an absolute path that Vite can compile. Component
+previews from a picked `components/` folder require Agent Native Desktop or a
+local Content dev server. Desktop-selected folders register their workspace
+path with the local dev server so Vite can import and hot reload
+`components/*.tsx`.
+
+## Agent component edits
+
+Use `list-local-component-files` to find the registered workspace id, then
+`write-local-component-file` to add or edit `.tsx`, `.jsx`, `.ts`, or `.js`
+files under that workspace's `components/` folder. The Vite component
+registry reloads after file additions/removals; edits to already-loaded files
+hot reload through Vite.

package/corpus/templates/content/.agents/skills/document-editing/SKILL.md

@@ -205,3 +205,15 @@ descriptions narrow the guidance further when working with structured values.
 | "Show me the document tree"  | `list-documents`                                                                    |
 
 Always run `refresh-list` after any create, update, or delete operation.
+
+## Reference Files
+
+- **`references/document-behavior.md`** — self-documenting descriptions,
+  `pull-document`'s collab-flush handshake vs `get-document`, versions, image
+  blocks, and the sharing/visibility model (`/page/<id>` vs `/p/<id>`,
+  discoverability, the read-only public chat). Read it before touching
+  descriptions, external ingest, or a document's visibility.
+- **`references/databases.md`** — full behavioral reference for Content
+  databases: property types, Blocks fields, and every view type (table,
+  list, gallery, board, calendar, timeline, form). Read it before building or
+  modifying database views, properties, or forms.

package/corpus/templates/content/.agents/skills/document-editing/references/databases.md

@@ -0,0 +1,238 @@
+# Content Databases — Behavioral Reference
+
+Notion-style databases layered on top of the normal document model. The SQL
+column shapes are injected separately by the framework schema block — this
+file covers behavior the schema can't convey: what each property type means,
+how views work, and which actions own which mutation.
+
+## Databases are document-backed page-level objects
+
+A normal document has no properties by default. A row in a database is also a
+document, linked through `content_database_items`; when that row document
+opens, it shows the database's properties. The database page itself renders as
+a table and owns the schema in `document_property_definitions.database_id`.
+Database row documents and their descendants stay contained by the database
+and are omitted from the ordinary sidebar page tree; users open them from the
+database view or an explicit link. When a row document is open, the editor
+shows a small parent-database breadcrumb above the title so the user can
+return to the containing database without relying on the sidebar. The
+`view-screen` document tree follows the same rule: database row pages are
+omitted from the ordinary tree and counted separately as contained database
+items.
+
+When a database row is open in the side preview, navigation state includes
+`databasePreviewDocumentId`, and `view-screen` returns that row as
+`databasePreview` with its content and properties. Database navigation state
+also includes the active view type, search query, sort count, the saved
+database view list, active sort/filter definitions, filter match mode, saved
+column calculations, table cell wrapping state, table row density, collapsed
+group IDs, calendar or timeline date property IDs/names, the visible date
+range for calendar/timeline views, empty-group visibility state, visible
+source summary when attached, and database row preview state. Source-aware
+metadata lives alongside the database model in `content_database_sources`,
+`content_database_source_fields`, `content_database_source_rows`, and
+`content_database_source_change_sets`; those tables store binding status,
+field mappings, source-qualified row identity/provenance, freshness
+timestamps, and proposed local-only diff records without changing the normal
+table view.
+
+Navigation state includes a capped `databaseVisibleItems` summary with row
+item IDs, document IDs, titles, positions, and visible property value
+summaries for the visible rows, plus row count and total row count, so agents
+can tell whether the user is looking at the full database or a constrained
+slice and can refer to the same rows and cells the user can currently scan;
+for calendar and timeline views this summary is limited to rows in the
+current visible date window plus rows shown in the "No date" section. When
+footer calculations are active, navigation state also includes
+`databaseCalculationResults` with the visible result text for each calculated
+column. When table rows are selected, navigation state also includes
+`databaseSelectedItemCount` and `databaseSelectedItems`, and
+`view-screen.databaseCurrentView` mirrors that selected row summary.
+`view-screen` exposes the same slice as `databaseCurrentView` alongside the
+full database payload. Its row property summaries should mirror the active
+database view's property order, hidden-property list, and empty-property
+visibility rules. It also marks database page entries in
+`documentTree.items[].database`, matching the sidebar's database icon
+fallback so agents can distinguish database pages from ordinary pages.
+
+Database views render the row page's custom icon anywhere a row title
+appears, falling back to the default page icon when the row has no icon. The
+database side preview exposes the same icon picker affordance as a normal
+page, so users can set or remove a row page icon without leaving the
+database. The preview is an overlay-free, non-modal side peek so the database
+context stays visible while the row page is open. Background database
+interactions should not dismiss it; use the explicit close control to close
+the preview. Keep it narrow enough on desktop that the underlying database
+still reads as the active context. In table views, clicking a row title opens
+that side preview; inline title editing lives behind the hover pencil
+affordance.
+
+## Property types
+
+Document properties are SQL-backed, Notion-style structured metadata rather
+than YAML embedded in the markdown body. Database property definitions
+support `text`, `number`, `select`, `multi_select`, `status`, `date`,
+`person`, `place`, `files_media` (`Files & media`), `checkbox`, `url`,
+`email`, `phone`, `blocks` (Capacities-style rich-text body field), plus
+computed `formula`, `id`, `created_time`, `created_by`, and
+`last_edited_time`, `last_edited_by`, plus property visibility
+(`always_show`, `hide_when_empty`, `always_hide`). The value table stores
+per-row-document JSON values.
+
+### Blocks fields
+
+A `blocks` field is independent rich-text content per row — NOT YAML and NOT
+a pointer to the body. Every database is seeded with one primary "Content"
+Blocks field whose content is backed by `documents.content` (so it reuses the
+collaborative TipTap/Yjs body editor and existing data migrates for free).
+Each additional Blocks field stores its own content in
+`document_block_field_contents`, keyed by `(document_id, property_id)`, so no
+two Blocks fields ever share content — adding a second Blocks field creates a
+new, empty, independent field. On the page: one Blocks field renders
+chromeless (no header, just the body); two or more each show their name as a
+header and are collapsible and reorderable (the surviving lone field keeps
+its stored name). In table views a Blocks column shows a word count (e.g.
+"412 words"), not the body. A Blocks field can only be deleted from the
+database view's column menu (not from the page body); deleting the last
+Blocks field warns that it removes the body for every object of the type.
+
+Formula properties store their expression in property options and support
+`{Property name}` substitution plus simple numeric math such as `{MSV} * 2`.
+
+## Views
+
+Database views support multiple named table, list, gallery, board, calendar,
+timeline, and form views saved in `content_databases.view_config_json`. Each
+view has its own stacked sorts, type-aware filters with an all/any match
+mode, per-view hidden property IDs, column widths, and (for table, list,
+gallery, and board views) grouping property or (for calendar/timeline views)
+date property: text-like fields can use contains/exact/empty filters, numbers
+support comparisons, dates support before/after, and checkboxes support
+checked/unchecked. Users can reorder stacked sort and filter conditions from
+the database toolbar menus, and sort priority follows the same top-to-bottom
+order shown in the menu.
+
+New rows created from a filtered UI view inherit simple editable equality and
+checkbox filters as initial property values, resolving option labels back to
+stable option IDs for select, status, and multi-select filters, so a row
+created under "Status is Published" remains visible instead of immediately
+disappearing. Agents can mirror that behavior by passing
+`--propertyValues '{"propertyId":"value"}'` to `add-database-item`. Filter
+controls are type-aware: option properties choose from their configured
+options, option value editors can search existing options or create a new
+option from the typed query, and property settings can rename option labels
+or change option colors while preserving stable option IDs. Option-backed
+filter value pickers are searchable, can create a new option from the typed
+query, and can be cleared without removing the whole filter row. Date
+properties use date inputs, and number properties use numeric inputs.
+
+Column header menus can add or clear column sorts, add or replace type-aware
+quick filters (including checked/unchecked for checkbox fields), clear
+filters for that column, hide property columns in the current view without
+changing other views, and resize column widths. Column headers show compact
+sort/filter indicators when that column has active view constraints. Table
+rows can be selected with row checkboxes, and the table shows a compact
+selected-row bar with clear, duplicate, confirmed delete, and bulk property
+set actions for editable non-computed fields. Empty table cells stay
+visually blank while remaining clickable for editing, and checkbox table
+cells render as compact checkbox glyphs instead of "Checked"/"Unchecked"
+text; clicking a checkbox cell toggles it directly via
+`set-document-property`, matching Notion's quieter table surface. Table
+views can toggle wrapped cells and row density per view for longer
+text-heavy tables or more compact scanning.
+
+Table, list, and gallery views can group rows by status, select,
+multi-select, or checkbox properties; creating a page inside a group seeds
+the grouped property so the new page stays in that group. Grouped table,
+list, and gallery sections can be collapsed individually or all at once per
+view, and views can hide empty groups to reduce option-backed clutter. Active
+search, sort, and filter constraints show as removable chips below the
+toolbar with a clear-all control, and every database view shows a
+Notion-style page count footer that switches to "count of total" when search
+or filters reduce the result set. Table views can also save per-column
+footer calculations such as count values, count empty, percent empty, sum,
+average, count all rows, count unique values, percent filled, checkbox
+checked/unchecked summaries, percent checked/unchecked, min/max/median/range
+numbers, and earliest/latest/date-range dates in the active view config.
+Empty constrained views show a clear search/filter recovery action in the
+view body. The database Properties menu can search fields and show or hide
+all fields for the current view, and it includes a New property control for
+adding fields without returning to the table header. The New property picker
+supports searching property types by label or machine name.
+
+In unconstrained table views, row drag handles can reorder database item
+pages through `move-database-item`; clear search, sort, and filters before
+manual reordering. Creating a database row returns the created item IDs and
+opens the new row page in the side preview. Duplicating a database row
+returns the duplicate item IDs and opens the copied row in the side preview
+so users can continue editing the new page immediately, including from
+table, list, and gallery row action menus. Board, calendar, and timeline
+cards expose the same row action menu without showing table-only manual
+reorder actions. Deleting the currently previewed row from any row action
+menu or from the side preview header advances to the next row, falls back to
+the previous row, or closes the preview when no rows remain.
+
+List views render the same row pages as a compact page list with visible
+property metadata. Gallery views render row pages as cards with a preview
+area and visible property metadata.
+
+Calendar views render row pages on a month grid using a `date`,
+`created_time`, or `last_edited_time` property; when the selected date
+property is editable, creating a page from a day sets that page's date
+property to the day. Calendar and timeline views keep rows without the
+selected date value reachable in a compact "No date" section instead of
+treating them as missing search results. If a calendar or timeline view has
+not saved a date property yet, the UI and `view-screen` both use the same
+first available date-like property fallback. Timeline views render the same
+date-backed row pages in a horizontally scrollable six-week range, using a
+per-view start date property and optional end date property so cards can
+span multiple days.
+
+Form views render database properties as ordered questions. Each form view
+owns its enabled-question order and required flags, so two forms on the same
+database can collect different information. Use `submit-content-database-form`
+for agent, Slack, MCP, and UI submissions instead of composing
+`add-database-item` plus several property writes. The action accepts
+property definition IDs or exact property names, accepts select/status
+option IDs or labels, rejects unknown options, writes primary and additional
+Blocks fields to their correct stores in one transaction, verifies the saved
+row, and returns `createdItemId`, `createdDocumentId`, `urlPath`, and
+`deepLink`.
+
+The active view menu can rename, duplicate, delete, or switch an existing
+view's layout between table, list, gallery, calendar, timeline, board, and
+form while preserving its sorts, filters, hidden properties, and
+layout-specific settings.
+
+Board views group pages by status, select, multi-select, or checkbox
+properties, and board columns can be collapsed per view using the same
+`collapsedGroupIds` state as grouped table/list/gallery sections, including
+collapse-all and expand-all group commands. Board views also honor the
+per-view empty-group visibility setting. Changing the group-by property
+clears stale collapsed group IDs for that view. Board card metadata follows
+the same active-view hidden-property and empty-property visibility rules as
+table/list/gallery metadata. Dragging a board card between columns updates
+that row page's grouping property through `set-document-property`. When a
+board is grouped by status, select, or multi-select, users can add a new
+board group from the board itself; this appends a new option to the grouped
+property definition.
+
+## Actions
+
+Use `create-content-database`, `create-inline-content-database`,
+`get-content-database`, `list-trashed-content-databases`,
+`restore-content-database`, `add-database-item`, `duplicate-database-item`,
+`duplicate-database-items`, `delete-database-items`, `move-database-item`,
+`update-content-database-view`, `list-document-properties`,
+`configure-document-property`, `set-document-property`,
+`duplicate-document-property`, and `delete-document-property`; do not edit
+property rows or view config via raw SQL when an action can do it.
+
+When targeting more than one database row, call `duplicate-database-items` or
+`delete-database-items` once with a native JSON array of `itemIds` or
+`documentIds`. Do not loop `duplicate-database-item` or `delete-document` for
+multi-row duplicate/delete requests.
+
+Database views follow Notion-style tab labels. When creating or duplicating
+views in `viewConfig`, use unique default names (`Table 2`, `SEO copy 2`,
+etc.) instead of appending several tabs with the same label.

package/corpus/templates/content/.agents/skills/document-editing/references/document-behavior.md

@@ -0,0 +1,91 @@
+# Document Behavior Reference
+
+Non-obvious semantics for reading, describing, versioning, illustrating, and
+sharing documents. Read this before doing focused work in one of these areas.
+
+## Self-documenting descriptions
+
+Descriptions are stable semantic guidance, not generated summaries of current
+content. Preserve this distinction when reading or writing them:
+
+- A page description explains why the page exists and what belongs there.
+- A database description explains the collection's purpose and inclusion
+  boundary. Inline and full-page views of one database share the same
+  description.
+- A property description explains what the field means and what value
+  belongs there.
+- A select, status, or multi-select option description explains when to
+  choose that option.
+
+Descriptions are owned; context is inherited. Never copy an ancestor's prose
+into a child description. Focused reads expose a root-to-parent `contextPath`
+so the agent can use ancestor guidance without creating stale duplicates.
+Read the returned descriptions before placing content or setting property
+values. Update a description only when the object's meaning changes, not
+whenever its current content changes.
+
+## `pull-document` vs `get-document`
+
+**`pull-document` is the collab-aware "ingest the final" read** — prefer it
+over `get-document` for external ingest (another app, an external coding
+agent over MCP/A2A, an A2A peer). `get-document` returns whatever is in the
+`documents.content` SQL column, which can lag behind a live editing session:
+the open editor holds the authoritative Y.Doc in memory and only debounces it
+back to SQL. `pull-document` closes that gap with a flush handshake — if a
+live Yjs collab session exists for the document it writes a one-shot
+`flush-request-<id>` application-state key (scoped to the browser session,
+just like `navigate`); the open editor sees that key, serializes its current
+document to markdown through its own existing serializer, calls
+`update-document`, and writes an explicit request-id-matched success/error
+acknowledgement. `pull-document` waits for that acknowledgement and fails
+closed if the open editor cannot save; when no active human editor is
+present, the SQL column is authoritative and the handshake is skipped. It is
+GET + read-only + public-agent exposed (`requiresAuth: true`), returns
+`{ id, title, content, format, deepLink }`, and surfaces an "Open document"
+deep link for external agents. Use `--format text` for a plain-text strip of
+the markdown.
+
+## Versions
+
+`list-document-versions` / `restore-document-version` operate on saved
+document versions. There is no diff view — restoring replaces the current
+content with the selected version's content wholesale.
+
+## Image blocks
+
+Documents support image blocks as markdown images: `![alt text](https://...)`.
+The UI uploads local image files through the framework
+`/_agent-native/file-upload` endpoint, with Builder.io as the recommended
+storage path. If image upload fails because storage is not configured, tell
+the user to connect Builder.io in Settings -> File uploads. Agents can add
+images that already have a hosted URL by using `edit-document` or
+`update-document` to insert markdown image syntax. Do not embed base64 image
+data in document content.
+
+## Sharing and visibility
+
+Documents are **private by default** — only the creator can see them. To
+grant access to others, change the visibility or add explicit share grants
+using the framework-wide `share-resource` / `unshare-resource` /
+`list-resource-shares` / `set-resource-visibility` actions (`resourceType`
+`document`). See the `sharing` skill for the general access model.
+
+Read (`get-document`, `list-documents`, `search-documents`) admits rows the
+current user owns, has been shared on, or that match the resource's
+visibility. Write (`update-document`, `edit-document`) requires `editor` role
+or above; `delete-document` requires `admin` (owners always satisfy).
+
+For Notion-style "workspace access but don't list it everywhere," set
+`visibility` to `org` and then run `set-document-discoverability --id <id>
+--hideFromSearch true`. Organization members can still open the document
+with the link, but it is omitted from their Organization sidebar and
+document search unless they own it or have an explicit share grant. Use
+`--includeChildren true` (default) when hiding a page with sub-pages so
+descendants do not leak into the org list.
+
+Public documents are reachable at `/p/<id>` once visibility is `public`.
+Anyone with the link can read the page. The public page mounts a read-only
+agent chat with the document injected as context; public viewers must not
+create, edit, comment on, delete, or share documents through that chat.
+Private app documents (any visibility other than a deliberately public link)
+are reached at `/page/<id>`.

package/corpus/templates/content/.agents/skills/upgrade-agent-native/SKILL.md

@@ -56,7 +56,29 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    - Runs `skills update scaffold --project`
    - Runs `typecheck` when the project has that script
 
-3. **If upgrade or typecheck fails**
+3. **Pull upstream template changes (optional, separate from the bump)**
+
+   `agent-native upgrade` moves package versions. It never touches files that
+   were copied out of a template at scaffold time, so template fixes and
+   improvements do not arrive with a bump.
+
+   ```bash
+   agent-native template status        # recorded ref vs latest, drift counts
+   agent-native template diff          # what upstream changed, read-only
+   agent-native template sync          # 3-way merge it into the app
+   ```
+
+   `sync` defaults to the ref matching the installed `@agent-native/core`, so
+   run it after `upgrade`. It merges per file against a pristine baseline
+   stored in `refs/agent-native/template-baseline/<app-path>`; files upstream
+   did not touch are left alone, and real collisions get conflict markers.
+   After resolving markers, run `agent-native template accept` — the baseline
+   deliberately does not advance past an unresolved merge.
+
+   Apps scaffolded before provenance existed have no baseline. Create one
+   with `agent-native template baseline` before the first sync.
+
+4. **If upgrade or typecheck fails**
 
    - Read the concrete error
    - Fix **app** source, actions, config, or env — not framework packages
@@ -68,7 +90,7 @@ install → refresh scaffold skills → verify, then fix **app** code only.
    copied component; do not use that path to reproduce framework runtime
    behavior or hide version skew.
 
-4. **Dry-run / partial runs**
+5. **Dry-run / partial runs**
 
    ```bash
    agent-native upgrade --dry-run