@agent-native/core 0.84.0 → 0.84.2

package/corpus/templates/content/app/hooks/use-notion.ts

@@ -1,4 +1,9 @@
-import { appApiPath } from "@agent-native/core/client";
+import {
+  appApiPath,
+  callAction,
+  useActionMutation,
+  useActionQuery,
+} from "@agent-native/core/client";
 import type {
   CreateNotionPageRequest,
   Document,
@@ -8,18 +13,20 @@ import type {
   NotionSearchResponse,
   ResolveDocumentSyncConflictRequest,
 } from "@shared/api";
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { useEffect, useRef } from "react";
 
-async function fetchJson<T>(url: string, init?: RequestInit): Promise<T> {
-  const res = await fetch(appApiPath(url), init);
+async function fetchNotionAuthUrl(): Promise<string> {
+  const res = await fetch(appApiPath("/api/notion/auth-url"));
   if (!res.ok) {
     const body = await res.json().catch(() => null);
     throw new Error(
       body?.error || body?.message || `${res.status} ${res.statusText}`,
     );
   }
-  return res.json();
+  const body = (await res.json()) as { url?: string };
+  if (!body.url) throw new Error("Notion OAuth URL is unavailable");
+  return body.url;
 }
 
 function invalidateDocumentQueries(
@@ -27,34 +34,65 @@ function invalidateDocumentQueries(
   documentId: string,
 ) {
   queryClient.invalidateQueries({ queryKey: ["action"] });
-  queryClient.invalidateQueries({ queryKey: ["document-sync", documentId] });
+  queryClient.invalidateQueries({
+    queryKey: documentSyncStatusQueryKey(documentId),
+  });
+  queryClient.invalidateQueries({
+    queryKey: documentSyncStatusQueryKey(documentId, { autoSync: true }),
+  });
+}
+
+export function documentSyncStatusQueryKey(
+  documentId: string,
+  options?: { autoSync?: boolean },
+) {
+  return [
+    "action",
+    "refresh-notion-sync-status",
+    { documentId, autoSync: !!options?.autoSync },
+  ] as const;
 }
 
 export function useNotionConnection() {
+  return useActionQuery<NotionConnectionStatus>(
+    "connect-notion-status",
+    undefined,
+    {
+      staleTime: 30_000,
+    },
+  );
+}
+
+export function useNotionAuthUrl(enabled: boolean) {
   return useQuery({
-    queryKey: ["notion-connection"],
-    queryFn: () => fetchJson<NotionConnectionStatus>("/api/notion/status"),
+    queryKey: ["notion-auth-url"],
+    queryFn: fetchNotionAuthUrl,
+    enabled,
     staleTime: 30_000,
   });
 }
 
+export async function openNotionOAuthUrl() {
+  return fetchNotionAuthUrl();
+}
+
 export function useDocumentSyncStatus(
   documentId: string | null,
   options?: { autoSync?: boolean },
 ) {
   const queryClient = useQueryClient();
   const lastObservedSyncedAtRef = useRef<string | null>(null);
-  const query = useQuery({
-    queryKey: ["document-sync", documentId],
-    queryFn: () =>
-      fetchJson<DocumentSyncStatus>(
-        `/api/documents/${documentId}/notion/refresh`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ autoSync: !!options?.autoSync }),
-        },
-      ),
+  const query = useQuery<DocumentSyncStatus>({
+    queryKey: documentId
+      ? documentSyncStatusQueryKey(documentId, options)
+      : ["action", "refresh-notion-sync-status", null],
+    queryFn: () => {
+      if (!documentId) throw new Error("documentId is required");
+      return callAction<DocumentSyncStatus>("refresh-notion-sync-status", {
+        documentId,
+        autoSync: !!options?.autoSync,
+      });
+    },
     enabled: !!documentId,
     // Poll Notion aggressively when auto-sync is on so remote changes appear
     // within ~2s. Server throttles match (see REFRESH_THROTTLE_AUTO_SYNC_MS in
@@ -97,118 +135,89 @@ export function useDocumentSyncStatus(
 
 export function useDisconnectNotion() {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: () =>
-      fetchJson<{ success: boolean }>("/api/notion/disconnect", {
-        method: "POST",
-      }),
-    onSuccess: () => {
-      queryClient.invalidateQueries({ queryKey: ["notion-connection"] });
-      queryClient.invalidateQueries({ queryKey: ["document-sync"] });
+  return useActionMutation<{ success: boolean; deleted: number }>(
+    "disconnect-notion",
+    {
+      onSuccess: () => {
+        queryClient.invalidateQueries({
+          queryKey: ["action", "connect-notion-status"],
+        });
+        queryClient.invalidateQueries({
+          queryKey: ["action", "refresh-notion-sync-status"],
+        });
+      },
     },
-  });
+  );
 }
 
 export function useLinkDocumentToNotion(documentId: string) {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (data: LinkNotionPageRequest) =>
-      fetchJson<DocumentSyncStatus>(
-        `/api/documents/${documentId}/notion/link`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(data),
-        },
-      ),
+  return useActionMutation<
+    DocumentSyncStatus,
+    LinkNotionPageRequest & { documentId: string }
+  >("link-notion-page", {
     onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
   });
 }
 
 export function useUnlinkDocumentFromNotion(documentId: string) {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: () =>
-      fetchJson<{ success: boolean }>(
-        `/api/documents/${documentId}/notion/unlink`,
-        {
-          method: "DELETE",
-        },
-      ),
-    onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
-  });
+  return useActionMutation<{ success: boolean }, { documentId: string }>(
+    "unlink-notion-page",
+    {
+      method: "DELETE",
+      onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
+    },
+  );
 }
 
 export function usePullDocumentFromNotion(documentId: string) {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: () =>
-      fetchJson<DocumentSyncStatus>(
-        `/api/documents/${documentId}/notion/pull`,
-        {
-          method: "POST",
-        },
-      ),
-    onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
-  });
+  return useActionMutation<DocumentSyncStatus, { documentId: string }>(
+    "pull-notion-page",
+    {
+      onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
+    },
+  );
 }
 
 export function usePushDocumentToNotion(documentId: string) {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: () =>
-      fetchJson<DocumentSyncStatus>(
-        `/api/documents/${documentId}/notion/push`,
-        {
-          method: "POST",
-        },
-      ),
-    onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
-  });
+  return useActionMutation<DocumentSyncStatus, { documentId: string }>(
+    "push-notion-page",
+    {
+      onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
+    },
+  );
 }
 
 export function useResolveDocumentSyncConflict(documentId: string) {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (data: ResolveDocumentSyncConflictRequest) =>
-      fetchJson<DocumentSyncStatus>(
-        `/api/documents/${documentId}/notion/resolve`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(data),
-        },
-      ),
+  return useActionMutation<
+    DocumentSyncStatus,
+    ResolveDocumentSyncConflictRequest & { documentId: string }
+  >("resolve-notion-sync-conflict", {
     onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
   });
 }
 
 export function useCreateAndLinkNotionPage(documentId: string) {
   const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (data?: CreateNotionPageRequest) =>
-      fetchJson<DocumentSyncStatus>(
-        `/api/documents/${documentId}/notion/create-and-link`,
-        {
-          method: "POST",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(data ?? {}),
-        },
-      ),
+  return useActionMutation<
+    DocumentSyncStatus,
+    CreateNotionPageRequest & { documentId: string }
+  >("create-and-link-notion-page", {
     onSuccess: () => invalidateDocumentQueries(queryClient, documentId),
   });
 }
 
 export function useSearchNotionPages(query: string, enabled: boolean) {
-  return useQuery({
-    queryKey: ["notion-search", query],
-    queryFn: () =>
-      fetchJson<NotionSearchResponse>("/api/notion/search", {
-        method: "POST",
-        headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ query }),
-      }),
-    enabled,
-    staleTime: 10_000,
-  });
+  return useActionQuery<NotionSearchResponse>(
+    "search-notion-pages",
+    { query },
+    {
+      enabled,
+      staleTime: 10_000,
+    },
+  );
 }

package/corpus/templates/content/package.json

@@ -9,6 +9,9 @@
     "build": "agent-native build",
     "start": "agent-native start",
     "test": "vitest --run",
+    "test:parity": "vitest --run parity",
+    "test:parity-capabilities": "vitest --run parity actions/content-database-lifecycle.db.test.ts actions/bind-content-database-source-field.db.test.ts actions/_local-file-documents.test.ts actions/builder-source-review-gates.db.test.ts",
+    "eval:parity": "agent-native eval parity",
     "format.fix": "oxfmt --write .",
     "typecheck": "agent-native typecheck",
     "action": "agent-native action",

package/corpus/templates/content/parity/README.md

@@ -0,0 +1,69 @@
+# Content Parity Harness
+
+This folder is the living audit for Content's agent/UI action parity. The
+matrix records which visible workflows are action-backed, which have explicit
+exceptions, and which gaps need follow-up.
+
+PR 2.2 adds two executable tiers:
+
+- Deterministic parity tests run in normal CI. They use fixture data and
+  existing action tests, make no model calls, and require no private provider
+  credentials.
+- Gated agent evals run through `agent-native eval parity`. They are opt-in via
+  `CONTENT_PARITY_EVALS=1`, capped to four initial scenarios, and should be
+  reserved for manual or nightly checks.
+
+## Deterministic Checks
+
+```bash
+cd templates/content
+./node_modules/.bin/vitest --run parity
+./node_modules/.bin/vitest --run actions/content-database-lifecycle.db.test.ts actions/bind-content-database-source-field.db.test.ts actions/_local-file-documents.test.ts actions/builder-source-review-gates.db.test.ts
+```
+
+The matrix rows use `coverageRefs` to point at deterministic files that prove a
+capability. The meta-tests fail with the row id when a priority capability loses
+coverage, so reviewers do not have to map a random test name back to the audit.
+
+## Gated Agent Evals
+
+```bash
+cd templates/content
+./node_modules/.bin/agent-native eval parity --json
+CONTENT_PARITY_EVALS=1 ANTHROPIC_API_KEY=... ./node_modules/.bin/agent-native eval parity
+```
+
+With `CONTENT_PARITY_EVALS` unset, parity evals return skipped rows and do not
+call the agent runner. The CLI still exits `0`, but both readable and JSON
+reports mark each row with `status: "skipped"` and a `skipReason` such as
+`Skipped because CONTENT_PARITY_EVALS is unset`.
+
+With the gate set, the eval files run the four PR 2.2 scenarios:
+
+- `database-source-scope`
+- `document-search-edit`
+- `local-file-source-truth`
+- `builder-source-review-readonly`
+
+The scenarios use fake or fixture data only. They must not require private
+Builder, Notion, customer, or workspace credentials. The Builder scenario is
+readonly/mocked by default and must not execute a live write.
+
+## CI Posture
+
+Normal PR CI runs deterministic parity checks through `pnpm test:content-parity`.
+Live or LLM-backed parity evals are reserved for the gated eval workflow, which
+can be triggered manually or by the nightly schedule. Missing provider secrets
+should show as skipped in that workflow summary, not as a scored pass.
+
+## Updating The Matrix
+
+Edit `matrix.ts`, then regenerate:
+
+```bash
+cd templates/content
+./node_modules/.bin/tsx parity/render-matrix.ts --write
+```
+
+`parity/__tests__/matrix-render-fresh.test.ts` keeps `matrix.md` synced with
+the typed source.

package/corpus/templates/content/parity/eval-scenarios.ts

@@ -0,0 +1,118 @@
+export interface ParityEvalScenario {
+  id: string;
+  title: string;
+  capabilityIds: string[];
+  gateEnv: string;
+  defaultState: "skipped";
+  requiresPrivateCredentials: false;
+  prompt: string;
+  successSignals: string[];
+  expectedTools?: string[];
+}
+
+export const parityEvalScenarios: ParityEvalScenario[] = [
+  {
+    id: "database-bulk-row-reliability",
+    title: "Bulk database row reliability",
+    capabilityIds: ["database.rows"],
+    gateEnv: "CONTENT_PARITY_EVALS",
+    defaultState: "skipped",
+    requiresPrivateCredentials: false,
+    prompt:
+      "Using fixture Content database rows only, duplicate multiple selected rows and delete multiple selected rows through the action surface. Report the ordered duplicated item/document IDs, deleted IDs, and the verified remaining row count. Do not loop single-row duplicate or document delete actions for the multi-row operations.",
+    successSignals: [
+      "Uses duplicate-database-items once for the multi-row duplicate.",
+      "Uses delete-database-items once for the multi-row delete.",
+      "Reports ordered duplicated item and document IDs.",
+      "Reports deleted IDs and verified remaining row count.",
+      "Does not use private provider credentials.",
+    ],
+    expectedTools: ["duplicate-database-items", "delete-database-items"],
+  },
+  {
+    id: "database-source-scope",
+    title: "Source-backed database scope",
+    capabilityIds: [
+      "database.lifecycle-and-trash",
+      "source-sync.database-source-bindings",
+    ],
+    gateEnv: "CONTENT_PARITY_EVALS",
+    defaultState: "skipped",
+    requiresPrivateCredentials: false,
+    prompt:
+      "Using only fake or fixture source data, inspect or create a source-backed Content database, attach a safe source, map at least one unmapped field, change a view/filter/grouping, and report visible source scope plus whether any live external write occurred.",
+    successSignals: [
+      "Uses action-backed database/source operations instead of raw SQL.",
+      "Reports source scope and provenance explicitly.",
+      "Does not require private Builder credentials.",
+      "States that no live external write occurred unless a gated write action was explicitly run.",
+    ],
+    expectedTools: [
+      "create-content-database",
+      "attach-content-database-source",
+      "bind-content-database-source-field",
+      "get-content-database-source",
+    ],
+  },
+  {
+    id: "document-search-edit",
+    title: "Document search and edit through actions",
+    capabilityIds: [
+      "sidebar.document-tree-crud",
+      "editor.document-body-and-title",
+    ],
+    gateEnv: "CONTENT_PARITY_EVALS",
+    defaultState: "skipped",
+    requiresPrivateCredentials: false,
+    prompt:
+      "Using fixture Content documents only, search for a document by a unique title or body phrase, inspect it, make one small title or body edit through an action-backed document operation, and report the changed title/body plus the action path used.",
+    successSignals: [
+      "Uses search/open/edit document actions instead of direct SQL.",
+      "Reports which fixture document was changed.",
+      "Shows the edited title or body text.",
+      "Does not require private provider credentials.",
+    ],
+    expectedTools: ["search-documents", "get-document", "edit-document"],
+  },
+  {
+    id: "local-file-source-truth",
+    title: "Local file source-truth edit",
+    capabilityIds: [
+      "local-files.import-export-mounted-folder",
+      "sharing.document-discoverability-and-export",
+    ],
+    gateEnv: "CONTENT_PARITY_EVALS",
+    defaultState: "skipped",
+    requiresPrivateCredentials: false,
+    prompt:
+      "Using only a temporary local-file Content fixture, find a local MDX document, edit a small phrase through the Content action surface, pull or export the document, and report that the mounted local file remains the source of truth. Do not invoke OS reveal.",
+    successSignals: [
+      "Uses local-file-aware document actions rather than raw filesystem writes.",
+      "Reports the local file source-truth relationship.",
+      "Does not call OS reveal as an agent tool.",
+      "Does not require private provider credentials.",
+    ],
+    expectedTools: ["search-documents", "edit-document", "pull-document"],
+  },
+  {
+    id: "builder-source-review-readonly",
+    title: "Builder source review without live write",
+    capabilityIds: ["source-sync.builder-cms-review-and-write-gates"],
+    gateEnv: "CONTENT_PARITY_EVALS",
+    defaultState: "skipped",
+    requiresPrivateCredentials: false,
+    prompt:
+      "Using mocked Builder CMS fixture data only, prepare or review a Builder source change set, summarize the staged changes and write gates, and explicitly state that no live Builder write was executed.",
+    successSignals: [
+      "Uses Builder source review or validation actions.",
+      "Reports staged changes or gate state.",
+      "States that no live Builder write occurred.",
+      "Does not require private Builder credentials.",
+    ],
+    expectedTools: [
+      "prepare-builder-source-review",
+      "review-content-database-source-change-set",
+      "validate-builder-source-execution",
+    ],
+  },
+];

package/corpus/templates/content/parity/exceptions.allowlist.ts

@@ -0,0 +1,17 @@
+export interface ParityActionAllowlistEntry {
+  action: string;
+  reason: string;
+}
+
+export const parityActionAllowlist: ParityActionAllowlistEntry[] = [
+  {
+    action: "refresh-list",
+    reason:
+      "Agent/UI bridge helper that only nudges application-state refresh; not a user-visible Content operation.",
+  },
+  {
+    action: "run",
+    reason:
+      "Template bootstrap/support action rather than a Content user workflow.",
+  },
+];

package/corpus/templates/content/parity/matrix.md

@@ -0,0 +1,28 @@
+# Content Agent/UI Action Parity Matrix
+
+This generated matrix tracks whether high-value Content UI operations use the same action surface agents can call, or have an explicit exception. Edit `matrix.ts`, then regenerate this file.
+
+| ID                                             | Surface     | User-visible action                                                                            | Status                | Actions                                                                                                                                                                                                                                                                                                                   | UI entrypoints                                                                                                                                                                            | Durable effect                                                                                                                                  | Exception / gap                                                                                                                                                                                                                            | Reliability risk | Spine priority | Test coverage | Coverage refs                                                                                                                                                   | Eval scenarios                   | Follow-up                      |
+| ---------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | -------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------ |
+| comments.threads                               | comments    | List, add, reply, resolve, reopen, and delete comment threads                                  | action-backed         | `add-comment`, `delete-comment`, `list-comments`, `update-comment`                                                                                                                                                                                                                                                        | `app/components/editor/CommentsSidebar.tsx`, `app/hooks/use-comments.ts`                                                                                                                  | Comment threads, replies, anchors, mentions, resolution state, and deletion are stored through comment actions.                                 | -                                                                                                                                                                                                                                          | -                | P0             | seeded        | -                                                                                                                                                               | -                                | -                              |
+| database.lifecycle-and-trash                   | database    | Create, soft-delete, restore, list, and inspect content databases                              | action-backed         | `create-content-database`, `create-inline-content-database`, `delete-content-database`, `get-content-database`, `list-content-databases`, `list-trashed-content-databases`, `restore-content-database`                                                                                                                    | `app/components/editor/SlashCommandMenu.tsx`, `app/hooks/use-content-database.ts`, `app/hooks/use-documents.ts`                                                                           | Database pages and database records are created, read, soft-deleted, restored, and listed.                                                      | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`                                                                                                                 | `database-source-scope`          | -                              |
+| database.properties-and-view-config            | database    | Configure properties, values, ordering, and saved views                                        | action-backed         | `configure-document-property`, `delete-document-property`, `duplicate-document-property`, `list-document-properties`, `reorder-document-property`, `set-document-property`, `update-content-database-view`                                                                                                                | `app/components/editor/DocumentProperties.tsx`, `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-document-properties.ts`   | Property schemas, property values, property order, filters, sorts, grouping, hidden columns, view type, and view settings are stored.           | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/bind-content-database-source-field.db.test.ts`, `actions/content-database-source-actions.test.ts`, `actions/resync-content-database-source.db.test.ts` | `database-source-scope`          | -                              |
+| database.rows                                  | database    | Add, duplicate, move, open, and delete database rows                                           | action-backed         | `add-database-item`, `delete-database-items`, `delete-document`, `duplicate-database-items`, `duplicate-database-item`, `move-database-item`, `set-document-property`                                                                                                                                                     | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`                                                                                           | Database row backing documents and row ordering are created, duplicated, moved, edited, and deleted.                                            | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/database-row-batch-actions.db.test.ts`, `parity/__tests__/database-row-batch-reliability.test.ts`                                                      | `database-bulk-row-reliability`  | -                              |
+| editor.agent-assist-prompts                    | editor      | Ask AI from slash generation or comment context                                                | client-assist         | -                                                                                                                                                                                                                                                                                                                         | `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/CommentsSidebar.tsx`                                                                                                 | No direct durable mutation; the prompt asks the agent to use document actions when it decides to write.                                         | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                               | -                                | -                              |
+| editor.client-formatting-and-insertions        | editor      | Rich text formatting, selection state, slash block insertion, and copy actions                 | client-only-ephemeral | -                                                                                                                                                                                                                                                                                                                         | `app/components/editor/BubbleToolbar.tsx`, `app/components/editor/SlashCommandMenu.tsx`, `app/components/editor/DocumentToolbar.tsx`                                                      | -                                                                                                                                               | -                                                                                                                                                                                                                                          | -                | P1             | none          | -                                                                                                                                                               | -                                | -                              |
+| editor.document-body-and-title                 | editor      | Edit document title, body, icon, image alt text, and precise text                              | action-backed         | `edit-document`, `pull-document`, `set-image-alt-text`, `transcribe-media`, `update-document`                                                                                                                                                                                                                             | `app/components/editor/DocumentEditor.tsx`, `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/extensions/ImageBlock.tsx`, `app/components/editor/SlashCommandMenu.tsx` | Document content, title, icon, image metadata, and text replacements are saved to the same document source.                                     | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`, `actions/_local-file-documents.test.ts`                                                                        | `document-search-edit`           | -                              |
+| local-files.components-workspace               | local-files | Register, list, and write local MDX component workspaces                                       | host-only             | `list-local-component-files`, `register-local-component-workspace`, `write-local-component-file`                                                                                                                                                                                                                          | `app/routes/_app.local-files.tsx`, `actions/register-local-component-workspace.ts`, `actions/list-local-component-files.ts`, `actions/write-local-component-file.ts`                      | Trusted local component workspace registration and component file reads/writes support local MDX previews.                                      | Workspace registration depends on a trusted Desktop folder path and is intentionally hidden with agentTool: false.                                                                                                                         | -                | P1             | seeded        | -                                                                                                                                                               | -                                | Local folder exception/docs PR |
+| local-files.host-folder-handles                | local-files | Choose, persist, remove, and write trusted local folder handles                                | host-only             | -                                                                                                                                                                                                                                                                                                                         | `app/routes/_app.local-files.tsx`                                                                                                                                                         | Host directory handles and browser/Desktop write permissions are managed outside SQL action state.                                              | Mounted local folders require browser/Desktop host handles that agents cannot safely or portably hold as normal tools.                                                                                                                     | -                | P0             | none          | -                                                                                                                                                               | -                                | Local folder exception/docs PR |
+| local-files.import-export-mounted-folder       | local-files | Import, check, export, and push local folder source files                                      | action-backed         | `export-content-source`, `import-content-source`                                                                                                                                                                                                                                                                          | `app/routes/_app.local-files.tsx`, `actions/import-content-source.ts`, `actions/export-content-source.ts`                                                                                 | Local Markdown/MDX source files are imported into Content documents, and editable Content documents are exported back to source-friendly files. | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/_local-file-documents.test.ts`                                                                                                                         | `local-file-source-truth`        | -                              |
+| notion.route-backed-document-sync              | source-sync | Notion document sync status, link, unlink, pull, push, resolve, create, search, and disconnect | action-backed         | `connect-notion-status`, `create-and-link-notion-page`, `disconnect-notion`, `link-notion-page`, `list-notion-links`, `pull-notion-page`, `push-notion-page`, `refresh-notion-sync-status`, `resolve-notion-sync-conflict`, `search-notion-pages`, `sync-notion-comments`, `unlink-notion-page`                           | `app/hooks/use-notion.ts`, `app/components/editor/DocumentToolbar.tsx`, `app/components/editor/NotionSyncBar.tsx`, `app/components/editor/DocumentEditor.tsx`                             | Notion connection state, page search, link metadata, and local/remote document body sync state are read or mutated through Content actions.     | Notion OAuth auth-url and callback routes remain route-shaped because they initiate and receive browser redirects rather than normal app data mutations.                                                                                   | -                | P0             | covered       | `parity/__tests__/matrix-route-gap-classify.test.ts`                                                                                                            | -                                | -                              |
+| sharing.document-discoverability-and-export    | sharing     | Share, hide from search, export, and reveal documents                                          | action-backed         | `export-document`, `reveal-local-source-file`, `set-document-discoverability`, `share-local-file-document`                                                                                                                                                                                                                | `app/components/editor/DocumentToolbar.tsx`, `app/hooks/use-documents.ts`                                                                                                                 | Search discoverability, shareable copies, exports, and OS reveal requests are managed through Content actions.                                  | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/_local-file-documents.test.ts`                                                                                                                         | `local-file-source-truth`        | -                              |
+| sharing.os-reveal-local-source                 | sharing     | Reveal a local source file in the system file manager                                          | host-only             | `reveal-local-source-file`                                                                                                                                                                                                                                                                                                | `app/components/editor/DocumentToolbar.tsx`, `actions/reveal-local-source-file.ts`                                                                                                        | -                                                                                                                                               | OS reveal depends on trusted local host capabilities and should not spend agent tool surface or imply portable hosted behavior.                                                                                                            | -                | P2             | seeded        | -                                                                                                                                                               | -                                | Local folder exception/docs PR |
+| sidebar.chrome-state                           | sidebar     | Collapse sections and resize the sidebar                                                       | client-only-ephemeral | -                                                                                                                                                                                                                                                                                                                         | `app/components/sidebar/DocumentSidebar.tsx`, `app/components/layout/Layout.tsx`                                                                                                          | -                                                                                                                                               | -                                                                                                                                                                                                                                          | -                | P2             | none          | -                                                                                                                                                               | -                                | -                              |
+| sidebar.document-tree-crud                     | sidebar     | Create, delete, move, favorite, list, search, and open pages                                   | action-backed         | `create-document`, `delete-document`, `get-document`, `list-documents`, `move-document`, `search-documents`, `update-document`                                                                                                                                                                                            | `app/components/sidebar/DocumentSidebar.tsx`, `app/components/sidebar/DocumentTreeItem.tsx`, `app/hooks/use-documents.ts`                                                                 | Document tree rows and document metadata are created, updated, deleted, moved, searched, or read.                                               | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/content-database-lifecycle.db.test.ts`, `actions/_local-file-documents.test.ts`                                                                        | `document-search-edit`           | -                              |
+| sidebar.navigation-and-screen-context          | sidebar     | Navigate between documents and expose current screen context                                   | action-equivalent     | `navigate`, `view-screen`                                                                                                                                                                                                                                                                                                 | `app/components/sidebar/DocumentSidebar.tsx`, `actions/navigate.ts`, `actions/view-screen.ts`                                                                                             | Application navigation state is updated or read so the agent can reason about the user's current page/view.                                     | Human navigation is router-local, while agent navigation/screen inspection uses application-state actions to produce the same workspace orientation effect.                                                                                | -                | P1             | seeded        | -                                                                                                                                                               | -                                | -                              |
+| source-sync.builder-body-hydration-worker      | source-sync | Process queued Builder CMS body hydration work                                                 | action-backed         | `process-builder-body-hydration`                                                                                                                                                                                                                                                                                          | `app/components/editor/DocumentEditor.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`                                                        | Queued Builder body hydration entries are processed into readable Content document/database body state.                                         | This action is intentionally hidden from the model with agentTool: false because it is an internal bounded queue worker; agents should use source refresh, review, and execution actions rather than manually driving hydration internals. | -                | P0             | covered       | `actions/_database-source-utils.test.ts`                                                                                                                        | -                                | -                              |
+| source-sync.builder-cms-review-and-write-gates | source-sync | Review, stage, validate, and execute Builder CMS source writes                                 | action-backed         | `execute-builder-source-batch`, `execute-builder-source-execution`, `prepare-builder-source-execution`, `prepare-builder-source-review`, `review-content-database-source-change-set`, `set-content-database-source-write-mode`, `stage-builder-revision`, `validate-builder-source-execution`                             | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/components/editor/database-sources/BuilderSourceReviewDialog.tsx`                   | Builder source write mode, staged reviews, validation records, and bounded execution records are created through guarded actions.               | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/builder-source-review-gates.db.test.ts`, `actions/execute-builder-source-execution.test.ts`                                                            | `builder-source-review-readonly` | -                              |
+| source-sync.builder-documents                  | source-sync | List, pull, check, and push Builder docs/blog MDX documents                                    | action-backed         | `check-builder-doc`, `list-builder-docs`, `pull-builder-doc`, `push-builder-doc`                                                                                                                                                                                                                                          | `actions/list-builder-docs.ts`, `actions/pull-builder-doc.ts`, `actions/check-builder-doc.ts`, `actions/push-builder-doc.ts`                                                              | Builder docs/blog entries can be read into Content, checked locally, and pushed through guarded Builder document actions.                       | -                                                                                                                                                                                                                                          | -                | P1             | seeded        | -                                                                                                                                                               | -                                | -                              |
+| source-sync.database-source-bindings           | source-sync | Attach, inspect, refresh, disconnect, join, and bind database sources                          | action-backed         | `add-content-database-source-field-property`, `attach-content-database-source`, `bind-content-database-source-field`, `change-content-database-source-role`, `disconnect-content-database-source`, `get-content-database-source`, `list-builder-cms-models`, `refresh-content-database-source`, `suggest-source-join-key` | `app/components/editor/DocumentDatabase.tsx`, `app/components/editor/DocumentProperties.tsx`, `app/components/editor/database/DatabaseView.tsx`, `app/hooks/use-content-database.ts`      | Mounted database source metadata, fields, source role, join keys, and source-field/property bindings are stored and refreshed.                  | -                                                                                                                                                                                                                                          | -                | P0             | covered       | `actions/bind-content-database-source-field.db.test.ts`, `actions/content-database-source-actions.test.ts`, `actions/resync-content-database-source.db.test.ts` | `database-source-scope`          | -                              |
+| source-sync.provider-api-and-staged-datasets   | source-sync | Inspect provider APIs and stage/query/delete large provider datasets                           | action-backed         | `delete-staged-dataset`, `list-staged-datasets`, `provider-api-catalog`, `provider-api-docs`, `provider-api-request`, `query-staged-dataset`                                                                                                                                                                              | `actions/provider-api-catalog.ts`, `actions/provider-api-docs.ts`, `actions/provider-api-request.ts`, `actions/query-staged-dataset.ts`                                                   | Provider API metadata and staged dataset scratch storage support scoped agent/source analysis.                                                  | -                                                                                                                                                                                                                                          | -                | P1             | seeded        | -                                                                                                                                                               | -                                | -                              |
+| versions.history-and-restore                   | versions    | Open version history and restore a previous document version                                   | action-backed         | `list-document-versions`, `restore-document-version`                                                                                                                                                                                                                                                                      | `app/components/editor/VersionHistoryPanel.tsx`, `app/hooks/use-document-versions.ts`                                                                                                     | Document versions are listed and selected versions can restore the document while snapshotting current state.                                   | -                                                                                                                                                                                                                                          | -                | P0             | seeded        | -                                                                                                                                                               | -                                | -                              |