@agent-native/core 0.49.11 → 0.49.13

package/docs/content/local-file-mode.md

@@ -0,0 +1,378 @@
+---
+title: "Local File Mode"
+description: "Run agent-native apps with local Markdown, MDX, and other repo files as the source of truth instead of SQL-backed records."
+---
+
+# Local File Mode
+
+Local File Mode lets an agent-native app attach its normal UI and action surface
+directly to files in a repo or workspace. The app still feels like the hosted
+product, but its list views, editor, and agent tools read and write local files
+instead of SQL-backed app records.
+
+The first implementation is in the Content template: the left sidebar is
+populated from local `.md` and `.mdx` files, selecting a page opens the standard
+Content editor, and saving writes back to the selected file. The same files can
+also be edited by Codex, Claude Code, the Agent-Native sidebar agent, or a normal
+editor.
+
+Use Local File Mode when you want a repo-first workflow:
+
+- a docs repo with `docs/*.mdx`
+- a blog with `blog/*.mdx`
+- resources such as positioning, messaging, or team notes in `resources/*.md`
+- a personal Obsidian-style knowledge base with a richer MDX editor
+- app artifacts that should be easy for coding agents to inspect and patch
+
+Use database mode when you want the hosted collaborative app experience:
+multi-user sharing, SQL-backed permissions, comments, version history, and
+production hosting without local filesystem access.
+
+## The Mental Model
+
+There are two source-of-truth modes:
+
+| Mode            | Source of truth                            | Best for                                                                 |
+| --------------- | ------------------------------------------ | ------------------------------------------------------------------------ |
+| Database mode   | SQL rows through Drizzle                   | Hosted apps, collaboration, sharing, comments, version history           |
+| Local File Mode | Repo files declared by `agent-native.json` | Local/dev workflows, Git review, coding-agent edits, file-native content |
+
+The UI and agent actions should stay the same shape in both modes. A Content
+editor still edits documents; the difference is whether those documents resolve
+to SQL rows or local files.
+
+## Example Repo
+
+A Content workspace can be as small as this:
+
+```txt
+my-content-repo/
+  agent-native.json
+  docs/
+    getting-started.mdx
+    guides/
+      custom-components.mdx
+  blog/
+    launch-post.mdx
+  resources/
+    messaging/
+      positioning.md
+  components/
+    FrameworkTabs.tsx
+    Callout.tsx
+  extensions/
+    doc-status/
+      extension.json
+      index.html
+```
+
+In Local File Mode, the Content sidebar shows the `docs/`, `blog/`, and
+`resources/` trees as pages. Selecting `docs/getting-started.mdx` opens that
+file in the standard Content editor; editing in the UI writes back to
+`docs/getting-started.mdx`.
+
+`components/` is not a content root. It is a preview component library that MDX
+files can import or reference. The editor can render simple local MDX components
+without requiring you to clone or fork the entire Content app.
+
+`extensions/` is also not a content root. It is a local extension library:
+small sandboxed widgets that can render in app slots while their source stays in
+the repo.
+
+## Configuration
+
+Add `agent-native.json` to the repo or workspace root:
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "content": {
+      "mode": "local-files",
+      "roots": [
+        {
+          "name": "Docs",
+          "path": "docs",
+          "kind": "docs",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Blog",
+          "path": "blog",
+          "kind": "blog",
+          "extensions": [".md", ".mdx"]
+        },
+        {
+          "name": "Resources",
+          "path": "resources",
+          "kind": "resources",
+          "extensions": [".md", ".mdx"]
+        }
+      ],
+      "components": "components",
+      "extensions": "extensions",
+      "hide": ["**/_*.md", "**/_*.mdx"]
+    }
+  }
+}
+```
+
+You can also enable local files with `AGENT_NATIVE_MODE=local-files` or
+`AGENT_NATIVE_DATA_MODE=local-files`; the manifest is preferred because it
+documents the folder contract in the repo itself.
+
+## Content File Format
+
+Content reads Markdown and MDX. Frontmatter holds page metadata, and the body is
+the editable document:
+
+```mdx
+---
+title: "Getting Started"
+icon: "sparkles"
+isFavorite: true
+updatedAt: "2026-06-12T20:00:00.000Z"
+---
+
+# Getting Started
+
+Use <FrameworkTabs value="react" /> to show framework-specific code.
+```
+
+The title comes from `title` frontmatter when present, otherwise from the
+filename. The editor preserves MDX source that it cannot visually edit yet, so
+coding agents and normal text editors remain safe escape hatches.
+
+## Custom MDX Components
+
+Content can preview local components from the configured `components` folder.
+This is meant for docs-style MDX components such as tabs, callouts, package
+install snippets, or framework-specific code blocks.
+
+For example, add an interactive component next to your content:
+
+```tsx
+// components/ImpactCounter.tsx
+import { useState } from "react";
+
+export function ImpactCounter({
+  label = "points",
+  accent = "blue",
+  featured = false,
+}: {
+  label?: string;
+  accent?: "blue" | "green" | "purple";
+  featured?: boolean;
+}) {
+  const [count, setCount] = useState(3);
+  const accentClass =
+    accent === "green"
+      ? "border-green-300 bg-green-50"
+      : accent === "purple"
+        ? "border-purple-300 bg-purple-50"
+        : "border-blue-300 bg-blue-50";
+
+  return (
+    <div className={`rounded-md border p-4 ${accentClass}`}>
+      <div className="text-sm text-muted-foreground">Launch impact</div>
+      <div className="mt-1 text-3xl font-semibold">
+        {count} {label}
+      </div>
+      {featured ? <div className="mt-1 text-sm">Featured metric</div> : null}
+      <button
+        type="button"
+        className="mt-3 rounded border px-3 py-1 text-sm"
+        onClick={() => setCount((value) => value + 1)}
+      >
+        Add point
+      </button>
+    </div>
+  );
+}
+
+export const ImpactCounterInputs = {
+  label: {
+    type: "string",
+    label: "Metric label",
+    default: "points",
+  },
+  accent: {
+    type: "select",
+    label: "Accent",
+    options: ["blue", "green", "purple"],
+    default: "blue",
+  },
+  featured: {
+    type: "boolean",
+    label: "Featured",
+    default: false,
+  },
+};
+```
+
+Then use it from any local MDX file:
+
+```mdx
+---
+title: "Launch Notes"
+---
+
+# Launch Notes
+
+<ImpactCounter label="wins" />
+```
+
+The Content dev server discovers PascalCase named exports and PascalCase default
+exports from `.tsx`, `.jsx`, `.ts`, and `.js` files under `components/`. Those
+components render inside the editor and appear in the slash menu under
+**Local components**. Slash insertion creates a minimal tag such as
+`<ImpactCounter />`; add props in the MDX source when needed.
+
+If a component exports input metadata, selecting the component in the editor
+shows an edit button in the component's top-right corner. Supported input types
+are `string`, `textarea`, `number`, `boolean`, and `select`. The form writes
+changes back to the MDX tag, so local files remain the source of truth. The
+metadata can be exported as `ComponentNameInputs`, `ComponentNameConfig.inputs`,
+`Component.inputs`, or `agentNative.inputs`.
+
+Simple component tags with literal props can preview inline:
+
+```mdx
+<FrameworkTabs value="react" />
+
+<Callout type="warning">This setting affects production deploys.</Callout>
+```
+
+Complex JSX expressions are preserved in source. If the editor cannot safely
+preview a component prop yet, it shows a warning placeholder rather than
+silently dropping data.
+
+## Sharing Local Files
+
+Local files are not shared directly because other users cannot read a path on
+your machine. The Content toolbar's Share button creates or refreshes a
+database-backed copy of the selected file, navigates to that copy, and opens the
+normal share popover. The original local file remains under Local files; the
+database copy appears under Shared copies in Local File Mode and uses the
+standard document sharing model.
+
+## Local Extensions
+
+Local File Mode can also load repo-backed extensions from the configured
+`extensions` folder. Each extension is one directory with an `extension.json`
+manifest and an HTML entry file:
+
+```txt
+extensions/
+  doc-status/
+    extension.json
+    index.html
+```
+
+```json
+{
+  "id": "doc-status",
+  "name": "Doc Status",
+  "description": "Shows metadata for the selected Content file.",
+  "entry": "index.html",
+  "slots": ["content.sidebar.bottom"],
+  "permissions": {
+    "appActions": ["list-documents"],
+    "extensionData": true
+  }
+}
+```
+
+`index.html` is the same Alpine/Tailwind extension body format used by normal
+database-backed extensions. When the Content app sees a local extension that
+declares `content.sidebar.bottom`, it renders that extension at the bottom of
+the Content sidebar. The host passes `window.slotContext` with the selected
+document id, title, source metadata, and whether Content is in Local File Mode.
+
+Local extensions are previewed by the app but edited as files. The Extensions
+list shows them with a Local File badge, and the full-page viewer points back to
+the entry file. SQL-backed extension actions such as update, delete, share, and
+history do not apply; use your editor, Codex, Claude Code, or Git history for
+source changes.
+
+For v1, local extensions are intentionally conservative:
+
+- they can use `extensionData` for their own small runtime state
+- they can call only the `appAction`s listed in `extension.json`
+- raw SQL helpers and external `extensionFetch` are disabled
+- slot targets are declared in `extension.json`, not installed through SQL
+
+This gives local workspaces an Obsidian-like plugin surface without letting an
+arbitrary repo file inherit every capability of a database-backed extension.
+
+## How Apps Use It
+
+Local File Mode is implemented through the framework's local artifact helpers.
+An app declares roots for the artifact types it owns, then reads and writes
+through the same action surface its UI and agent already use.
+
+For Content, that means:
+
+- `list-documents` lists configured `.md` and `.mdx` files.
+- `get-document` reads a selected local file.
+- `update-document` writes the selected local file.
+- `create-document` creates a new local `.mdx` file in the selected folder.
+- `delete-document` deletes the local file.
+- search runs across the configured local files.
+
+Moving, renaming, and reordering local-file pages from the Content UI is not
+supported yet. Do those operations in the workspace or with a coding agent; the
+Content sidebar will reflect the resulting file tree.
+
+This keeps the agent contract simple: the agent can keep using Content actions,
+and those actions decide whether the target is SQL-backed or file-backed.
+
+Other apps can adopt the same pattern over time. A Slides app can map
+`slides/*.mdx` to decks, a Plans app can map `plans/*` to plan documents, and a
+Dashboards app can map `dashboards/*.mdx` to dashboards. Those app-specific
+folders are conventions layered on top of the same local artifact contract.
+
+## Local Files vs. Export/Import
+
+Content has two different file workflows:
+
+| Workflow                     | What happens                                                                                                         |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `/local-files` export/import | Database mode remains the source of truth. Files are an explicit sync surface you export, edit, preview, and import. |
+| Local File Mode              | Files are the source of truth. The Content sidebar and editor operate directly on local files.                       |
+
+Use export/import when you want occasional file review around a hosted workspace.
+Use Local File Mode when the repo itself is the workspace.
+
+## History And Collaboration
+
+Local File Mode leans on file-native history:
+
+- commit important changes to Git
+- use pull requests for review
+- let coding agents edit the same files directly
+- use normal file diffs to understand changes
+
+Database mode remains the better fit for hosted collaboration features such as
+sharing, comments, SQL-backed version history, and live multi-user editing.
+
+Provider sync can be layered on top of either mode. For example, a docs repo can
+add actions that pull content from a CMS into local MDX files or push selected
+local files back to that CMS.
+
+## Production Safety
+
+Local File Mode gives app actions direct write access to configured workspace
+files. That is appropriate for local development and trusted single-tenant file
+bridges, but it is not the default production security model.
+
+When `NODE_ENV=production`, the framework refuses `local-files` mode unless you
+set:
+
+```bash
+AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION=true
+```
+
+Only set that for a trusted single-tenant deployment where everyone who can use
+the app is allowed to read and write the configured files. For normal hosted,
+multi-user apps, use database mode and SQL-backed sharing.

package/docs/content/template-content.md

@@ -71,7 +71,10 @@ truth instead of SQL documents. Add `agent-native.json` to a repo, set
 left sidebar from those local `.md`/`.mdx` files and writes edits back to the
 selected file through the normal document actions. Use this for repo-first docs,
 blogs, resource libraries, or Obsidian-style personal content; switch back to
-database mode when you want hosted collaboration and SQL-backed sharing.
+database mode when you want hosted collaboration and SQL-backed sharing. See
+[Local File Mode](/docs/local-file-mode) for the standalone repo layout,
+configuration, custom MDX components, local `extensions/` widgets, and
+production safety guide.
 
 ## Why it's interesting
 
@@ -143,9 +146,18 @@ Sync state is tracked in the `document_sync_links` table (last synced time, conf
 
 ### Local file sync
 
-The protected `/local-files` route uses the browser File System Access API (or
-the same Chromium capability inside Agent Native Desktop) to read and write
-Markdown/MDX files from a user-chosen folder. It calls:
+The protected `/local-files` route uses the browser File System Access API, or a
+guarded native folder bridge inside Agent Native Desktop, to read and write
+Markdown/MDX files from a user-chosen folder. After the folder is linked and
+imported, the selected file is treated as the authority: opening the page reads
+the file, and normal editor saves write the file first. SQL is then updated as a
+cache/history layer for the existing document UI, search, and version panel, not
+as the source of truth. The top-right page menu exposes the local source path:
+relative path is always available, absolute path is available in true local-file
+mode and Agent Native Desktop, and Reveal in Finder is available through the
+desktop bridge or server-backed local-file mode.
+
+The bulk sync route calls:
 
 - `export-content-source` — reads the accessible document tree and returns a
   deterministic `content/` file bundle.
@@ -156,6 +168,43 @@ Markdown/MDX files from a user-chosen folder. It calls:
 The source format lives in `shared/content-source.ts`. Keep that file as the
 single contract for filenames, frontmatter, parsing, and serialization.
 
+Local file workspaces can also provide repo-local React components through the
+configured `components` folder. The Content dev server imports PascalCase
+exports from those files, renders matching MDX tags such as `<ImpactCounter />`
+inside the editor, and exposes them in the slash menu under Local components.
+This keeps custom MDX blocks local to the workspace without cloning the Content
+app. A minimal workspace component can be:
+
+```tsx
+// components/ImpactCounter.tsx
+import { useState } from "react";
+
+export function ImpactCounter({
+  label = "points",
+  start = 3,
+}: {
+  label?: string;
+  start?: number;
+}) {
+  const [count, setCount] = useState(start);
+  return (
+    <button type="button" onClick={() => setCount(count + 1)}>
+      Impact: {count} {label}
+    </button>
+  );
+}
+
+export const ImpactCounterInputs = {
+  label: { type: "string", label: "Label", default: "points" },
+  start: { type: "number", label: "Starting count", default: 3 },
+};
+```
+
+Use it in local MDX as `<ImpactCounter />`, or insert it from the editor slash
+menu under Local components. When input metadata is exported, selecting the
+component in the editor shows a corner edit button that rewrites the MDX props
+in the local file.
+
 ### Comments
 
 Threaded comments on documents with quoted-text anchors, replies, and resolve state. Backed by the `document_comments` table and `app/components/editor/CommentsSidebar.tsx`. Actions: `list-comments`, `add-comment`. Notion comments can sync both ways via `sync-notion-comments`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.49.11",
+  "version": "0.49.13",
   "type": "module",
   "engines": {
     "node": ">=22"