@agent-native/core-corpus 0.201.0-nightly-20261005153421 → 0.201.0

package/corpus/templates/content/server/lib/suggested-edits.ts

@@ -28,8 +28,8 @@ import {
 import { hasSuggestionBodyTarget } from "../../actions/_suggestion-eligibility.js";
 import { commentIdForIdempotency } from "../../actions/add-comment.js";
 import {
-  SUPPORTED_SUGGESTION_BLOCKS,
   SUPPORTED_SUGGESTION_MARKS,
+  supportsSuggestionNode,
 } from "../../app/components/editor/suggestions/model.js";
 import { createContentEditorStructuralSchema } from "../../shared/content-editor-structural-schema.js";
 import { mergeDocumentBodyIntents } from "../../shared/document-intent-merge.js";
@@ -215,8 +215,6 @@ type SuggestionDocumentJson = {
   content?: SuggestionDocumentJson[];
 };
 
-const SUPPORTED_SUGGESTION_INLINE_NODES = new Set(["hardBreak"]);
-
 function unsupportedNotionSpanAttrs(
   attrs: Record<string, unknown> | undefined,
 ) {
@@ -280,11 +278,7 @@ function unsupportedSuggestionStructure(
     }
     return result;
   }
-  if (
-    node.type !== "doc" &&
-    !SUPPORTED_SUGGESTION_INLINE_NODES.has(node.type ?? "") &&
-    !SUPPORTED_SUGGESTION_BLOCKS.has(node.type ?? "")
-  ) {
+  if (!supportsSuggestionNode(node.type ?? "")) {
     result.push({ path, node });
     return result;
   }
@@ -325,6 +319,7 @@ function unsupportedStructureKey(markdown: string): string {
 function validateSuggestionStructure(
   beforeMarkdown: string,
   afterMarkdown: string,
+  refusal: string,
 ) {
   const after = parseSuggestionMarkdown(afterMarkdown);
   const surround = unsupportedStructureKey(
@@ -332,19 +327,14 @@ function validateSuggestionStructure(
   );
   if (
     unsupportedStructureKey(beforeMarkdown) !== surround ||
-    unsupportedStructureKey(afterMarkdown) !== surround
-  ) {
-    throw new Error(
-      "Content v1 suggestions cannot add or change unsupported structures",
-    );
-  }
-  if (
+    unsupportedStructureKey(afterMarkdown) !== surround ||
     JSON.stringify(unsupportedRawNotionSpanAttrs(beforeMarkdown)) !==
-    JSON.stringify(unsupportedRawNotionSpanAttrs(afterMarkdown))
+      JSON.stringify(unsupportedRawNotionSpanAttrs(afterMarkdown))
   ) {
-    throw new Error(
-      "Content v1 suggestions cannot add or change unsupported structures",
-    );
+    fail(refusal, {
+      statusCode: 422,
+      errorCode: "suggestion_structure_unsupported",
+    });
   }
   return after;
 }
@@ -579,11 +569,16 @@ export const contentDocumentSuggestionAdapter: SuggestionAdapter = {
       );
     }
     if (before.markdown.includes("<InlineDatabase")) {
-      throw new Error(
-        "Pages with inline databases cannot receive suggestions yet",
-      );
+      fail("Pages with inline databases cannot receive suggestions yet.", {
+        statusCode: 409,
+        errorCode: "suggestion_body_unavailable",
+      });
     }
-    validateSuggestionStructure(before.markdown, after.markdown);
+    validateSuggestionStructure(
+      before.markdown,
+      after.markdown,
+      "Suggestions cannot change tables, images, or other content or formatting they do not support yet. Suggest changes to the surrounding text instead.",
+    );
     return operations;
   },
   async coordinateDecision(context, run) {
@@ -675,11 +670,13 @@ export const contentDocumentSuggestionAdapter: SuggestionAdapter = {
     const nextDocument = validateSuggestionStructure(
       currentContent,
       nextContent,
+      "This suggestion changes a table, image, or other content or formatting that suggestions do not support yet, so it cannot be accepted.",
     );
     if (currentContent.includes("<InlineDatabase")) {
-      throw new Error(
-        "Pages containing inline databases cannot accept suggestions yet",
-      );
+      fail("Pages containing inline databases cannot accept suggestions yet.", {
+        statusCode: 409,
+        errorCode: "suggestion_body_unavailable",
+      });
     }
     const eligiblePrimaryIds = await assertSuggestionBodyTarget(
       tx,

package/corpus/templates/content/server/plugins/auth.ts

@@ -6,7 +6,8 @@ export default createAuthPlugin({
   workspaceAppPublicPaths: ["/"],
   marketing: {
     appName: "Content",
-    learnMoreUrl: "https://agent-native.com/apps/content",
+    learnMoreUrl:
+      "https://agent-native.com/apps/content?utm_source=app&utm_medium=product&utm_content=onboarding-learn-more",
     tagline:
       "Open-source Obsidian for MDX: your AI agent edits local docs, creates custom blocks, and organizes everything alongside you.",
     features: [

package/corpus/templates/content/server/plugins/otel.ts

@@ -0,0 +1,6 @@
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { startAgentNativeOtel } from "@agent-native/otel";
+
+export default defineNitroPlugin(() => {
+  startAgentNativeOtel();
+});

package/corpus/templates/content/shared/api.ts

@@ -1077,8 +1077,25 @@ export interface ContentDatabaseNavigationPageResponse {
     hasMore: boolean;
     nextCursor: string | null;
   };
+  /**
+   * First pages of the requested expanded folders, by parent document ID. A
+   * folder with no children the caller can see is left out.
+   */
+  branches?: Record<string, ContentDatabaseNavigationPage>;
+  /**
+   * Present when the read asked for expanded folders: true when the cap on
+   * branches per read left out folders it could have opened, which then read
+   * their own pages.
+   */
+  branchesTruncated?: boolean;
 }
 
+/** One Files navigation page on its own, without expanded folders. */
+export type ContentDatabaseNavigationPage = Omit<
+  ContentDatabaseNavigationPageResponse,
+  "branches" | "branchesTruncated"
+>;
+
 export interface BuilderActionTiming {
   name: string;
   durationMs: number;

package/corpus/templates/content/shared/suggestion-diff.ts

@@ -2,7 +2,9 @@ import { canonicalizeNfm } from "./nfm.js";
 import {
   suggestionFormattingChanges,
   suggestionMarkedSourceRanges,
+  suggestionSourceAlignment,
   SuggestionFormattingMappingError,
+  type SuggestionSourceAlignment,
 } from "./suggestion-formatting.js";
 import { resolveMarkdownSuggestionRange } from "./suggestion-rebase.js";
 
@@ -838,8 +840,13 @@ export function markdownSuggestionOperationsForEditorRevision(input: {
       },
     ];
   }
-  const editorBefore = canonicalizeNfm(input.before);
+  const alignment = suggestionSourceAlignment(input.before);
+  const editorBefore = alignment
+    ? alignment.canonical
+    : canonicalizeNfm(input.before);
   const replacements = input.replacements.map(({ from, to }) => {
+    const aligned = alignment && alignedRange(alignment, from, to, "stored");
+    if (aligned) return aligned;
     const changedText = input.before.slice(from, to);
     const range = resolveMarkdownSuggestionRange(editorBefore, {
       before: { markdown: input.before, changedText },
@@ -854,47 +861,142 @@ export function markdownSuggestionOperationsForEditorRevision(input: {
     if (!range) throw new SuggestionFormattingMappingError();
     return range;
   });
+  const operations = markdownSuggestionOperationsForReplacements({
+    before: editorBefore,
+    after: input.after,
+    replacements,
+  });
   return isolateSiblingAnchorContexts(
-    markdownSuggestionOperationsForReplacements({
-      before: editorBefore,
-      after: input.after,
-      replacements,
-    }).map((operation, ordinal) => {
-      const range = resolveMarkdownSuggestionRange(input.before, operation);
-      if (!range) throw new SuggestionFormattingMappingError();
-      return operationForChange(
+    (alignment &&
+      alignedStoredOperations(
         input.before,
+        input.after,
+        operations,
+        alignment,
+      )) ??
+      operations.map((operation, ordinal) => {
+        const range = resolveMarkdownSuggestionRange(input.before, operation);
+        if (!range) throw new SuggestionFormattingMappingError();
+        return operationForChange(
+          input.before,
+          range.from,
+          range.to,
+          operation.after.changedText,
+          ordinal,
+        );
+      }),
+  );
+}
+
+function alignedRange(
+  alignment: SuggestionSourceAlignment,
+  from: number,
+  to: number,
+  side: "canonical" | "stored",
+) {
+  const alignedFrom = alignment.map(from, side);
+  const alignedTo = alignment.map(to, side);
+  return alignedFrom === null || alignedTo === null
+    ? null
+    : { from: alignedFrom, to: alignedTo };
+}
+
+function alignedStoredOperations(
+  before: string,
+  after: string,
+  operations: MarkdownSuggestionOperation[],
+  alignment: SuggestionSourceAlignment,
+): MarkdownSuggestionOperation[] | null {
+  const stored: MarkdownSuggestionOperation[] = [];
+  for (const operation of operations) {
+    const range = alignedRange(
+      alignment,
+      operation.anchor.from,
+      operation.anchor.to,
+      "canonical",
+    );
+    if (!range) return null;
+    stored.push(
+      operationForChange(
+        before,
         range.from,
         range.to,
         operation.after.changedText,
-        ordinal,
-      );
-    }),
-  );
+        stored.length,
+      ),
+    );
+  }
+  let reconstructed = before;
+  for (const operation of [...stored].reverse())
+    reconstructed =
+      reconstructed.slice(0, operation.anchor.from) +
+      operation.after.changedText +
+      reconstructed.slice(operation.anchor.to);
+  // An edit spanning a gap writes the editor's syntax for it, which a stored
+  // pipe table cannot hold; only a reparse shows the page still matches.
+  return reconstructed === after ||
+    canonicalizeNfm(reconstructed) === canonicalizeNfm(after)
+    ? stored
+    : null;
+}
+
+// Replays the operations onto the base's canonical form; the result must be
+// the draft byte for byte, so every anchor lands where the editor shows it.
+function alignedDraftAnchors(
+  operations: readonly MarkdownSuggestionOperation[],
+  draft: string,
+): MarkdownSuggestionOperation["anchor"][] | null {
+  const alignment = suggestionSourceAlignment(operations[0]!.before.markdown);
+  if (!alignment) return null;
+  const ranges: Array<{ from: number; to: number }> = [];
+  let reconstructed = "";
+  let cursor = 0;
+  for (const operation of operations) {
+    const range = alignedRange(
+      alignment,
+      operation.anchor.from,
+      operation.anchor.to,
+      "stored",
+    );
+    if (!range || range.from < cursor) return null;
+    reconstructed += alignment.canonical.slice(cursor, range.from);
+    ranges.push({
+      from: reconstructed.length,
+      to: reconstructed.length + operation.after.changedText.length,
+    });
+    reconstructed += operation.after.changedText;
+    cursor = range.to;
+  }
+  if (reconstructed + alignment.canonical.slice(cursor) !== draft) return null;
+  return ranges.map(({ from, to }) => ({
+    from,
+    to,
+    prefix: draft.slice(Math.max(0, from - 32), from),
+    suffix: draft.slice(to, to + 32),
+  }));
 }
 
 export function draftSuggestionAnchors(
   operations: readonly MarkdownSuggestionOperation[],
   draft: string,
 ): MarkdownSuggestionOperation["anchor"][] {
-  const canonical = operations.every(
-    (operation) =>
-      canonicalizeNfm(operation.after.markdown) === operation.after.markdown,
-  );
-  let proposedRaw = operations[0]?.before.markdown ?? draft;
+  if (operations.length === 0) return [];
+  const aligned = alignedDraftAnchors(operations, draft);
+  if (aligned) return aligned;
+  let proposedRaw = operations[0]!.before.markdown;
   for (const operation of [...operations].reverse()) {
     proposedRaw =
       proposedRaw.slice(0, operation.anchor.from) +
       operation.after.changedText +
       proposedRaw.slice(operation.anchor.to);
   }
-  const parts = canonical ? null : diffParts(proposedRaw, draft);
-  if (!canonical && !parts) throw new SuggestionFormattingMappingError();
+  const parts = diffParts(proposedRaw, draft);
+  if (!parts) throw new SuggestionFormattingMappingError();
   const boundaryMap = new Array<number>(proposedRaw.length + 1);
   let rawOffset = 0;
   let draftOffset = 0;
   boundaryMap[0] = 0;
-  for (const part of parts ?? []) {
+  for (const part of parts) {
     if (part.type === "insert") {
       draftOffset += part.text.length;
       boundaryMap[rawOffset] = draftOffset;
@@ -906,27 +1008,11 @@ export function draftSuggestionAnchors(
       boundaryMap[rawOffset] = draftOffset;
     }
   }
-  if (
-    !canonical &&
-    (rawOffset !== proposedRaw.length || draftOffset !== draft.length)
-  )
+  if (rawOffset !== proposedRaw.length || draftOffset !== draft.length)
     throw new SuggestionFormattingMappingError();
 
   let delta = 0;
   return operations.map((operation) => {
-    if (canonical) {
-      const from = operation.anchor.from + delta;
-      const to = from + operation.after.changedText.length;
-      delta +=
-        operation.after.changedText.length -
-        operation.before.changedText.length;
-      return {
-        from,
-        to,
-        prefix: draft.slice(Math.max(0, from - 32), from),
-        suffix: draft.slice(to, to + 32),
-      };
-    }
     const rawFrom = operation.anchor.from + delta;
     const rawTo = rawFrom + operation.after.changedText.length;
     const from = boundaryMap[rawFrom];

package/corpus/templates/content/shared/suggestion-formatting.ts

@@ -1,4 +1,5 @@
 import {
+  canonicalizeNfm,
   docToNfm,
   nfmToDoc,
   serializeInlineTextNodeWithOffsets,
@@ -55,7 +56,11 @@ function longestBacktickRun(text: string): number {
   return Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
 }
 
-function formattingRuns(source: string): { runs: TextRun[] } | null {
+function formattingRuns(source: string): {
+  runs: TextRun[];
+  restored: string;
+  canonicalSpans: SourceSpan[];
+} | null {
   const doc = nfmToDoc(source);
   let markerPrefix = "suggestiontextboundary";
   while (source.includes(markerPrefix)) markerPrefix += "z";
@@ -133,12 +138,103 @@ function formattingRuns(source: string): { runs: TextRun[] } | null {
     },
   );
   if (unmappable || runs.some((run) => run.sourceFrom < 0)) return null;
+  const canonicalSpans = runs.map(({ sourceFrom, sourceTo, textOffsets }) => ({
+    from: sourceFrom,
+    to: sourceTo,
+    textOffsets,
+  }));
   if (
     restored !== source &&
     !mapStoredSourceRuns(source, restored, runs, markers, withPlaceholders)
   )
     return null;
-  return { runs };
+  return { runs, restored, canonicalSpans };
+}
+
+type SourceSpan = TextRange & { textOffsets: number[] };
+type SourceSide = "canonical" | "stored";
+
+export type SuggestionSourceAlignment = {
+  canonical: string;
+  map(offset: number, from: SourceSide): number | null;
+};
+
+let lastAlignment: {
+  source: string;
+  alignment: SuggestionSourceAlignment | null;
+} | null = null;
+
+// A draft session maps every keystroke against the same stored base.
+export function suggestionSourceAlignment(
+  source: string,
+): SuggestionSourceAlignment | null {
+  if (lastAlignment?.source !== source)
+    lastAlignment = { source, alignment: sourceAlignment(source) };
+  return lastAlignment.alignment;
+}
+
+// Pairs each text run's canonical and stored bytes. An offset maps inside a
+// run, at a run or gap edge, or inside a gap whose bytes match on both sides;
+// anywhere else the two serializations disagree and the offset has no image.
+function sourceAlignment(source: string): SuggestionSourceAlignment | null {
+  const canonical = canonicalizeNfm(source);
+  const inside = (offset: number, text: string) =>
+    Number.isInteger(offset) && offset >= 0 && offset <= text.length;
+  if (canonical === source)
+    return {
+      canonical,
+      map: (offset) => (inside(offset, source) ? offset : null),
+    };
+  const mapped = formattingRuns(source);
+  if (!mapped || mapped.restored !== canonical) return null;
+  const texts = { canonical, stored: source };
+  const spans: Array<Record<SourceSide, SourceSpan>> = mapped.runs.map(
+    (run, index) => ({
+      canonical: mapped.canonicalSpans[index]!,
+      stored: {
+        from: run.sourceFrom,
+        to: run.sourceTo,
+        textOffsets: run.textOffsets,
+      },
+    }),
+  );
+  return {
+    canonical,
+    map(offset, from) {
+      if (!inside(offset, texts[from])) return null;
+      const to: SourceSide = from === "canonical" ? "stored" : "canonical";
+      type Edge = Record<SourceSide, number>;
+      const gap = (start: Edge, end: Edge) => {
+        if (offset === start[from]) return start[to];
+        if (offset === end[from]) return end[to];
+        return texts[from].slice(start[from], end[from]) ===
+          texts[to].slice(start[to], end[to])
+          ? start[to] + offset - start[from]
+          : null;
+      };
+      let previous: Edge = { canonical: 0, stored: 0 };
+      for (const span of spans) {
+        const own = span[from];
+        const other = span[to];
+        if (offset < own.from)
+          return gap(previous, {
+            canonical: span.canonical.from,
+            stored: span.stored.from,
+          });
+        if (offset <= own.to) {
+          if (offset === own.from) return other.from;
+          if (offset === own.to) return other.to;
+          const index = own.textOffsets.indexOf(offset - own.from);
+          return index < 0 ? null : other.from + other.textOffsets[index]!;
+        }
+        previous = { canonical: span.canonical.to, stored: span.stored.to };
+      }
+      return gap(previous, {
+        canonical: canonical.length,
+        stored: source.length,
+      });
+    },
+  };
 }
 
 function normalizedSourceGap(source: string, from: number, to: number): string {
@@ -155,6 +251,28 @@ function normalizedSourceGap(source: string, from: number, to: number): string {
     .slice(prefix.length);
 }
 
+const TABLE_TAG = /<\/?(?:table|tr|td|th)\b[^>]*>/;
+
+// Canonical NFM writes a stored pipe table as an HTML table. Both reduce to
+// "|" between cells and a newline between rows, with or without the stored
+// rows' optional outer pipes; the final reparse proves the cells.
+function tableBoundaries(
+  gap: string,
+  startsLine: boolean,
+  endsLine: boolean,
+): string {
+  return `${startsLine ? "\n" : ""}${gap}${endsLine ? "\n" : ""}`
+    .replace(/^[ \t|:-]*$/gm, (line) =>
+      line.includes("|") && line.includes("-") ? "" : line,
+    )
+    .replace(/[ \t]*\|?[ \t]*\n[ \t]*\|?/g, "\n")
+    .replace(/<tr\b[^>]*>\s*<t[dh]\b[^>]*>/g, "\n")
+    .replace(/<t[dh]\b[^>]*>/g, "|")
+    .replace(/<\/?(?:table|tr|td|th)\b[^>]*>/g, "\n")
+    .replace(/\s*\|\s*/g, "|")
+    .replace(/\s*\n\s*/g, "\n");
+}
+
 function mapStoredSourceRuns(
   source: string,
   canonical: string,
@@ -188,7 +306,20 @@ function mapStoredSourceRuns(
       stored = stored.replace(/\n+$/, "");
       expected = expected.replace(/\n+$/, "");
     }
-    return stored === expected;
+    if (stored === expected) return true;
+    const lineEdges = (text: string, start: number, end: number) =>
+      [
+        start === 0 || /[\r\n]/.test(text[start - 1]!),
+        end === text.length || /[\r\n]/.test(text[end]!),
+      ] as const;
+    return (
+      TABLE_TAG.test(canonical.slice(canonicalFrom, canonicalTo)) &&
+      tableBoundaries(stored, ...lineEdges(source, from, to)) ===
+        tableBoundaries(
+          expected,
+          ...lineEdges(canonical, canonicalFrom, canonicalTo),
+        )
+    );
   };
   let cursor = 0;
   let canonicalCursor = 0;

package/corpus/templates/crm/.agents/skills/security/SKILL.md

@@ -290,9 +290,16 @@ export default defineEventHandler(async (event) => {
 
 ## Data Scoping
 
-In production, the framework automatically restricts all agent SQL queries to the current user's data using temporary views. This is enforced at the SQL level — the agent cannot bypass it.
+In production, the framework automatically restricts all agent SQL queries to the current user's data using temporary views, and checks every statement before it runs so it can only reach those views.
 
-The `db-query` / `db-exec` tools (and the extension SQL bridge, which shares the same path) reject schema-qualified table references like `public.<table>` — a qualified name resolves to the base table and would skip the temp view. Use bare table names; scoping is applied automatically.
+The `db-query` / `db-exec` / `db-patch` tools (and the extension SQL bridge, which shares the same path) read each statement the way Postgres does and refuse anything that could reach data around the temp views:
+
+- schema- or database-qualified names like `public.<table>`, which resolve to the base table;
+- names that resolve to anything other than the current user's temp views, such as materialized views or tables the scoping does not cover;
+- app-defined SQL or PL/pgSQL functions and operators, whose bodies read tables without the views;
+- built-ins that run SQL text, change session settings, or reach outside the database (`query_to_xml`, `set_config`, `dblink`, most `pg_*` functions).
+
+`db-query` runs in a read-only transaction, and an `INSERT` must list its columns when the table has access-control columns. Use bare table names and plain expressions; scoping is applied automatically. When the agent needs data the views do not expose, add an app action with its own access checks.
 
 ### Per-User Scoping (`owner_email`)
 

package/corpus/templates/crm/.agents/skills/storing-data/SKILL.md

@@ -75,10 +75,11 @@ state their PostgreSQL types directly.
 
 Member offboarding and email changes refuse to run while any column named
 `email`, `*_email`, `*scope_id`, `created_by`, `updated_by`, `invited_by`,
-`owner`, `principal_id`, `session_id`, or `user_id` has no policy. `owner_email`
-and `createSharesTable()` tables are handled for you. Declare every other one,
-including columns that are not member identities, from the app's database
-plugin graph (Clips does it in `server/db/index.ts`):
+`owner`, `principal_id`, `session_id`, or `user_id` has no policy.
+`createSharesTable()` tables are handled for you, and undeclared `owner_email`
+columns transfer to the successor, which is right only for owned content.
+Declare every other one, including columns that are not member identities, from
+the app's database plugin graph (Clips does it in `server/db/index.ts`):
 
 ```ts
 import { registerIdentityColumns } from "@agent-native/core/org";
@@ -88,13 +89,17 @@ registerIdentityColumns([
   { table: "space_members", column: "email", emailChange: "rekey", offboard: "delete", orgScope: { column: "space_id", references: { table: "spaces", column: "id", orgColumn: "org_id" } }, reason: "Space membership grants access." },
   // Someone else's address: never rewritten.
   { table: "meeting_participants", column: "email", emailChange: "retain", offboard: "retain", reason: "Attendee address from the calendar provider." },
+  // A credential in an owner_email table: never handed to the successor.
+  { table: "api_keys", column: "owner_email", emailChange: "rekey", offboard: "revoke", reason: "Bearer keys act as their owner." },
 ]);
 ```
 
-Choose `delete` for grants, credentials, and pending tokens; `retain` for
+Choose `delete` for grants, credentials, and pending tokens, or `revoke` (sets
+`revoked_at`) when a reader treats a missing row as "not revoked"; `retain` for
 attribution, history, and third-party addresses; `transfer` only for owned
-data. A table without `org_id` needs `orgScope` or an organization-scoped
-removal leaves its rows alone.
+data. Declare `owner_email` tables that hold credentials or grants, or
+offboarding hands them to the successor. A table without `org_id` needs
+`orgScope` or an organization-scoped removal leaves its rows alone.
 
 | Template     | Tables                                        |
 | ------------ | --------------------------------------------- |

package/corpus/templates/crm/package.json

@@ -17,6 +17,7 @@
   },
   "dependencies": {
     "@agent-native/core": "workspace:*",
+    "@agent-native/otel": "workspace:*",
     "@agent-native/toolkit": "workspace:*",
     "@electric-sql/pglite": "^0.5.8",
     "@fontsource-variable/inter": "^5.3.0",

package/corpus/templates/crm/server/plugins/otel.ts

@@ -0,0 +1,6 @@
+import { defineNitroPlugin } from "@agent-native/core/server";
+import { startAgentNativeOtel } from "@agent-native/otel";
+
+export default defineNitroPlugin(() => {
+  startAgentNativeOtel();
+});

package/corpus/templates/design/.agents/skills/security/SKILL.md

@@ -290,9 +290,16 @@ export default defineEventHandler(async (event) => {
 
 ## Data Scoping
 
-In production, the framework automatically restricts all agent SQL queries to the current user's data using temporary views. This is enforced at the SQL level — the agent cannot bypass it.
+In production, the framework automatically restricts all agent SQL queries to the current user's data using temporary views, and checks every statement before it runs so it can only reach those views.
 
-The `db-query` / `db-exec` tools (and the extension SQL bridge, which shares the same path) reject schema-qualified table references like `public.<table>` — a qualified name resolves to the base table and would skip the temp view. Use bare table names; scoping is applied automatically.
+The `db-query` / `db-exec` / `db-patch` tools (and the extension SQL bridge, which shares the same path) read each statement the way Postgres does and refuse anything that could reach data around the temp views:
+
+- schema- or database-qualified names like `public.<table>`, which resolve to the base table;
+- names that resolve to anything other than the current user's temp views, such as materialized views or tables the scoping does not cover;
+- app-defined SQL or PL/pgSQL functions and operators, whose bodies read tables without the views;
+- built-ins that run SQL text, change session settings, or reach outside the database (`query_to_xml`, `set_config`, `dblink`, most `pg_*` functions).
+
+`db-query` runs in a read-only transaction, and an `INSERT` must list its columns when the table has access-control columns. Use bare table names and plain expressions; scoping is applied automatically. When the agent needs data the views do not expose, add an app action with its own access checks.
 
 ### Per-User Scoping (`owner_email`)