From 4fb014398bbac9cd99004f916e9b9354524697f3 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Fri, 7 Aug 2026 14:25:37 -0700
Subject: [PATCH 01/22] feat: add Signature, Image, and Video docs components

Adds three new MDX block components for packages/core/docs/content
reference pages: Signature (a collapsible function/hook/action
signature with parameter and return-type breakdown), and Image/Video
(full width or aligned left/right with paired markdown text, alt
text, and a caption). Video additionally supports reduced-motion-aware
autoplay and looping. Documented all three on /docs/docs-components
with live examples.
---
 .../core/docs/content/docs-components.mdx     | 215 ++++++++++++++++
 .../app/components/blocks/image.config.ts     |  56 +++++
 packages/docs/app/components/blocks/image.tsx |  37 +++
 .../app/components/blocks/media-layout.tsx    |  74 ++++++
 .../app/components/blocks/media-shared.ts     |  30 +++
 .../app/components/blocks/signature.config.ts |  77 ++++++
 .../docs/app/components/blocks/signature.tsx  | 141 +++++++++++
 .../app/components/blocks/video.config.ts     |  71 ++++++
 packages/docs/app/components/blocks/video.tsx |  77 ++++++
 packages/docs/app/components/docBlocks.tsx    |   6 +
 packages/docs/app/global.css                  | 229 ++++++++++++++++++
 packages/docs/lib/doc-block-segments.ts       |   9 +
 12 files changed, 1022 insertions(+)
 create mode 100644 packages/docs/app/components/blocks/image.config.ts
 create mode 100644 packages/docs/app/components/blocks/image.tsx
 create mode 100644 packages/docs/app/components/blocks/media-layout.tsx
 create mode 100644 packages/docs/app/components/blocks/media-shared.ts
 create mode 100644 packages/docs/app/components/blocks/signature.config.ts
 create mode 100644 packages/docs/app/components/blocks/signature.tsx
 create mode 100644 packages/docs/app/components/blocks/video.config.ts
 create mode 100644 packages/docs/app/components/blocks/video.tsx

diff --git a/packages/core/docs/content/docs-components.mdx b/packages/core/docs/content/docs-components.mdx
index b967b220cc..5792cea51a 100644
--- a/packages/core/docs/content/docs-components.mdx
+++ b/packages/core/docs/content/docs-components.mdx
@@ -223,6 +223,218 @@ Add more `###` sections to get 3 or 4 columns (max 4). The red/green label accen
 
 ---
 
+## Image
+
+<Image
+  src="/screenshots/dispatch.png"
+  alt="Dispatch app screenshot showing the run history sidebar"
+  align="left"
+  width={320}
+  caption="Dispatch's run history sidebar."
+>
+
+Aligning an image left or right turns it into a two-column row. The image sits on that side, and this markdown is the paired text on the other side. Leave `align` unset, or set it to `"full"`, for a normal full-width image with no paired text.
+
+</Image>
+
+```mdx
+<Image
+  src="/screenshots/dispatch.png"
+  alt="Dispatch app screenshot showing the run history sidebar"
+  align="left"
+  width={320}
+  caption="Dispatch's run history sidebar."
+>
+
+Aligning an image left or right turns it into a two-column row. The image sits on that side, and this markdown is the paired text on the other side. Leave `align` unset, or set it to `"full"`, for a normal full-width image with no paired text.
+
+</Image>
+```
+
+`alt` is required. `align` is `"full"` (the default), `"left"`, or `"right"`. `width` is an optional pixel hint for the image column when aligned, and has no effect on `"full"`. `caption` renders in small muted text under the image. Anything between the open and close tags is markdown, and becomes the paired text next to the image when aligned, or plain content below it when full width. Omit the children entirely for a self-closing `<Image ... />` with no paired text.
+
+For a plain full-width image with no paired text, omit `align` (or set it to `"full"`) and skip the children entirely:
+
+<Image
+  src="/screenshots/mail.png"
+  alt="Mail app screenshot showing the inbox and reading pane"
+  caption="The default inbox view."
+/>
+
+```mdx
+<Image
+  src="/screenshots/mail.png"
+  alt="Mail app screenshot showing the inbox and reading pane"
+  caption="The default inbox view."
+/>
+```
+
+---
+
+## Video
+
+<Video
+  src="/videos/product-tour.mp4"
+  alt="A short screen recording of creating a new action from the CLI"
+  align="right"
+  width={320}
+  caption="Creating an action from the CLI."
+>
+
+Same shape as `Image`, aligned the other way this time. The video sits on the right, and this text sits on the left. `src` must be a direct video file, mp4 or webm. Third-party embed links like YouTube or Loom aren't supported, since that would need an `<iframe>`, which the docs system doesn't allow for security reasons.
+
+</Video>
+
+```mdx
+<Video
+  src="/videos/product-tour.mp4"
+  alt="A short screen recording of creating a new action from the CLI"
+  align="right"
+  width={320}
+  caption="Creating an action from the CLI."
+>
+
+Same shape as `Image`, aligned the other way this time. The video sits on the right, and this text sits on the left. `src` must be a direct video file, mp4 or webm. Third-party embed links like YouTube or Loom aren't supported, since that would need an `<iframe>`, which the docs system doesn't allow for security reasons.
+
+</Video>
+```
+
+Identical attributes to `Image` (`src`, `alt`, `align`, `width`, `caption`, and paired markdown children), except `src` must point to a direct video file rather than an embed link. `alt` becomes the video's `aria-label`, since `<video>` has no native `alt` attribute.
+
+Pass `autoplay` to play the video automatically once it's visible. It always forces `muted` alongside it, since browsers block autoplay with sound regardless of the attribute. It also never autoplays for a viewer with `prefers-reduced-motion: reduce` set. That viewer instead gets a normal paused player, and pressing play themselves gives them full, unmuted playback rather than a silently-muted one.
+
+Pass `loop` to restart the video from the beginning once it ends. It's independent of `autoplay`, so a looping video that isn't set to autoplay just loops once the viewer presses play themselves.
+
+The same full-width form applies here too, omit `align` and the children for a plain full-width video:
+
+<Video
+  src="/videos/product-tour.mp4"
+  alt="A full walkthrough recording of building an action end to end"
+  caption="Building an action end to end."
+/>
+
+```mdx
+<Video
+  src="/videos/product-tour.mp4"
+  alt="A full walkthrough recording of building an action end to end"
+  caption="Building an action end to end."
+/>
+```
+
+---
+
+## Signature
+
+<Signature
+  id="docs-components-signature"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "The question, its options, and how it should behave.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "The complete question. Clear, specific, ends with a question mark.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'Very short chip/heading, about 12 characters, e.g. `"Date range"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description: "2-4 distinct options.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description: 'Adds a free-text "Other" option.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Multi-select instead of single-select.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'The picked value, `value[]` when `allowMultiple`, the typed "Other" text, or `null` if skipped.',
+  }}
+/>
+
+```mdx
+<Signature
+  id="docs-components-signature"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "The question, its options, and how it should behave.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "The complete question. Clear, specific, ends with a question mark.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'Very short chip/heading, about 12 characters, e.g. `"Date range"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description: "2-4 distinct options.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description: 'Adds a free-text "Other" option.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Multi-select instead of single-select.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'The picked value, `value[]` when `allowMultiple`, the typed "Other" text, or `null` if skipped.',
+  }}
+/>
+```
+
+`Signature` is self-closing. `name` plus `params` build the code-style call line shown at the top (an optional param renders as `name?: type`). Each param is `{ name, type, optional?, default?, description }`, matching a plain field. An object-shaped param (like `input` above) can add a nested `fields` array of the same shape to break down its properties, so one block replaces both a hand-written signature line and a separate options table. `returns` is optional and takes the same `{ type, description? }` shape. Descriptions render through the normal markdown pipeline, so backticks and bold work.
+
+Use this over a hand-written `ts` fence plus a prose bullet list whenever a reference page documents a specific function, hook, or action's call shape, per the `writing-reference-docs` skill.
+
+---
+
 ## kbd — keyboard shortcut
 
 Press [[⌘K]] to open the command palette. Save with [[Ctrl+S]] before running the dev server. Navigate fields with [[Tab]] and [[Shift+Tab]].
@@ -487,5 +699,8 @@ Like `TabsBlock`, `Columns` is self-closing with a single JSON `columns` attribu
 | Same task in multiple tools or frameworks | `Tabs`                               |
 | Side-by-side code (labeled columns)       | `Columns`                            |
 | Project directory structure               | `FileTree`                           |
+| A function/hook/action's call shape       | `Signature`                          |
+| An image, full width or with paired text  | `Image`                              |
+| A video, full width or with paired text   | `Video`                              |
 | Inline keyboard shortcut                  | `[[Key]]`                            |
 | Architecture or flow diagram              | Mermaid fence                        |
diff --git a/packages/docs/app/components/blocks/image.config.ts b/packages/docs/app/components/blocks/image.config.ts
new file mode 100644
index 0000000000..e71d494ac1
--- /dev/null
+++ b/packages/docs/app/components/blocks/image.config.ts
@@ -0,0 +1,56 @@
+import type { BlockMdxConfig } from "@agent-native/core/blocks";
+import { z } from "zod";
+
+import {
+  mediaAlignSchema,
+  mediaCaptionSchema,
+  mediaSrcSchema,
+  mediaTextSchema,
+  mediaWidthSchema,
+  type MediaAlign,
+} from "./media-shared";
+
+export interface ImageData {
+  src: string;
+  alt: string;
+  align?: MediaAlign;
+  width?: number;
+  caption?: string;
+  /** Markdown paired text shown beside the image when aligned left/right. */
+  text?: string;
+}
+
+export const imageSchema = z.object({
+  src: mediaSrcSchema,
+  alt: z.string().trim().min(1).max(400),
+  align: mediaAlignSchema,
+  width: mediaWidthSchema,
+  caption: mediaCaptionSchema,
+  text: mediaTextSchema,
+}) as unknown as z.ZodType<ImageData>;
+
+/**
+ * MDX config: `<Image src alt align width caption>text</Image>`. `text` is
+ * MDX children (like `Callout`'s body), so it round-trips as real markdown
+ * rather than a flat attribute. Self-closing (`<Image ... />`) is valid too —
+ * `text` decodes to `undefined` when there are no children.
+ */
+export const imageMdx: BlockMdxConfig<ImageData> = {
+  tag: "Image",
+  childrenField: "text",
+  toAttrs: (data) => ({
+    src: data.src,
+    alt: data.alt,
+    align: data.align,
+    width: data.width,
+    caption: data.caption,
+  }),
+  fromAttrs: (attrs, children) => ({
+    src: attrs.string("src") ?? "",
+    alt: attrs.string("alt") ?? "",
+    align: attrs.string("align") as MediaAlign | undefined,
+    width: attrs.number("width"),
+    caption: attrs.string("caption"),
+    text: children.trim() ? children : undefined,
+  }),
+};
diff --git a/packages/docs/app/components/blocks/image.tsx b/packages/docs/app/components/blocks/image.tsx
new file mode 100644
index 0000000000..5e1f4bb483
--- /dev/null
+++ b/packages/docs/app/components/blocks/image.tsx
@@ -0,0 +1,37 @@
+import { defineBlock } from "@agent-native/core/blocks";
+import type { BlockReadProps } from "@agent-native/core/blocks";
+
+import { imageSchema, imageMdx, type ImageData } from "./image.config";
+import { MediaFrame } from "./media-layout";
+
+export type { ImageData };
+
+export function ImageBlock({ data, ctx }: BlockReadProps<ImageData>) {
+  return (
+    <MediaFrame
+      className="docs-image"
+      align={data.align}
+      width={data.width}
+      caption={data.caption}
+      text={data.text}
+      ctx={ctx}
+      media={<img src={data.src} alt={data.alt} loading="lazy" />}
+    />
+  );
+}
+
+export const imageBlock = defineBlock<ImageData>({
+  type: "image",
+  schema: imageSchema,
+  mdx: imageMdx,
+  Read: ImageBlock,
+  placement: ["block"],
+  label: "Image",
+  description:
+    "An image, full width or aligned left/right with paired markdown text and an optional caption.",
+  empty: () => ({
+    src: "/images/example.png",
+    alt: "Describe the image for screen readers.",
+    align: "full",
+  }),
+});
diff --git a/packages/docs/app/components/blocks/media-layout.tsx b/packages/docs/app/components/blocks/media-layout.tsx
new file mode 100644
index 0000000000..e3afd1891b
--- /dev/null
+++ b/packages/docs/app/components/blocks/media-layout.tsx
@@ -0,0 +1,74 @@
+import type { BlockRenderContext } from "@agent-native/core/blocks";
+import type { ReactNode } from "react";
+
+import type { MediaAlign } from "./media-shared";
+
+/**
+ * Shared layout for the `image` and `video` blocks: full width, or a flex row
+ * with the media on one side and markdown `text` as the paired content on the
+ * other. `align="left"` puts the media on the left (text on the right);
+ * `align="right"` mirrors it. Falls back to full width whenever there's no
+ * paired text, since a side-by-side row needs both columns to make sense.
+ */
+export function MediaFrame({
+  className,
+  align,
+  width,
+  caption,
+  text,
+  ctx,
+  media,
+}: {
+  className: string;
+  align?: MediaAlign;
+  width?: number;
+  caption?: string;
+  text?: string;
+  ctx: BlockRenderContext;
+  media: ReactNode;
+}) {
+  const resolvedAlign = align ?? "full";
+  const hasText = Boolean(text && text.trim());
+  const sideBySide = resolvedAlign !== "full" && hasText;
+
+  const figure = (
+    <div
+      className="docs-media-figure"
+      style={
+        sideBySide && width
+          ? { flexBasis: `${width}px`, maxWidth: `${width}px` }
+          : undefined
+      }
+    >
+      {media}
+      {caption && (
+        <div className="docs-media-caption">
+          {ctx.renderMarkdown?.(caption) ?? <p>{caption}</p>}
+        </div>
+      )}
+    </div>
+  );
+
+  const textColumn = hasText && (
+    <div className="docs-media-text">
+      {ctx.renderMarkdown?.(text!) ?? <p>{text}</p>}
+    </div>
+  );
+
+  if (!sideBySide) {
+    return (
+      <div className={`docs-media docs-media-full ${className}`}>
+        {figure}
+        {textColumn}
+      </div>
+    );
+  }
+
+  return (
+    <div className={`docs-media docs-media-${resolvedAlign} ${className}`}>
+      {resolvedAlign === "right" && textColumn}
+      {figure}
+      {resolvedAlign === "left" && textColumn}
+    </div>
+  );
+}
diff --git a/packages/docs/app/components/blocks/media-shared.ts b/packages/docs/app/components/blocks/media-shared.ts
new file mode 100644
index 0000000000..7eafbdc49d
--- /dev/null
+++ b/packages/docs/app/components/blocks/media-shared.ts
@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+/**
+ * Shared shape for the `image` and `video` docs blocks: full width, or
+ * aligned to one side with markdown "text" as the paired content on the
+ * other side. Kept in one place so both blocks validate `src`/`width`/etc
+ * identically instead of drifting.
+ */
+export type MediaAlign = "full" | "left" | "right";
+
+/** Rejects javascript:/data:/vbscript:/file:/protocol-relative sources —
+ *  only an absolute path or an https(s) URL is accepted. */
+export const mediaSrcSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(2_000)
+  .regex(/^(https?:\/\/|\/)/i, {
+    message: "src must be an absolute path (/...) or an https URL",
+  });
+
+export const mediaAlignSchema = z.enum(["full", "left", "right"]).optional();
+
+/** Pixel width hint for the media column when aligned left/right. */
+export const mediaWidthSchema = z.number().int().min(80).max(800).optional();
+
+export const mediaCaptionSchema = z.string().trim().max(400).optional();
+
+/** Markdown paired text, rendered beside the media when aligned. */
+export const mediaTextSchema = z.string().max(4_000).optional();
diff --git a/packages/docs/app/components/blocks/signature.config.ts b/packages/docs/app/components/blocks/signature.config.ts
new file mode 100644
index 0000000000..9bb0cc6805
--- /dev/null
+++ b/packages/docs/app/components/blocks/signature.config.ts
@@ -0,0 +1,77 @@
+import type { BlockMdxConfig } from "@agent-native/core/blocks";
+import { z } from "zod";
+
+/** One parameter, return type, or nested object field in a signature. */
+export interface SignatureField {
+  name: string;
+  /** Type shown in code style, e.g. "string" or "AskUserQuestionOption[]". */
+  type: string;
+  optional?: boolean;
+  /** Default value shown as code, e.g. "true" or '"guided-questions"'. */
+  default?: string;
+  description: string;
+}
+
+export interface SignatureParam extends SignatureField {
+  /** Breaks an object-shaped param (e.g. an options bag) into its own fields. */
+  fields?: SignatureField[];
+}
+
+export interface SignatureReturns {
+  type: string;
+  description?: string;
+}
+
+export interface SignatureData {
+  /** The function/hook name, e.g. "askUserQuestion". */
+  name: string;
+  params: SignatureParam[];
+  returns?: SignatureReturns;
+}
+
+const fieldSchema = z.object({
+  name: z.string().trim().min(1).max(80),
+  type: z.string().trim().min(1).max(200),
+  optional: z.boolean().optional(),
+  default: z.string().trim().max(200).optional(),
+  description: z.string().trim().min(1).max(2_000),
+}) as z.ZodType<SignatureField>;
+
+const paramSchema = z.object({
+  name: z.string().trim().min(1).max(80),
+  type: z.string().trim().min(1).max(200),
+  optional: z.boolean().optional(),
+  default: z.string().trim().max(200).optional(),
+  description: z.string().trim().min(1).max(2_000),
+  fields: z.array(fieldSchema).max(40).optional(),
+}) as unknown as z.ZodType<SignatureParam>;
+
+export const signatureSchema = z.object({
+  name: z.string().trim().min(1).max(120),
+  params: z.array(paramSchema).max(20),
+  returns: z
+    .object({
+      type: z.string().trim().min(1).max(200),
+      description: z.string().trim().max(2_000).optional(),
+    })
+    .optional(),
+}) as unknown as z.ZodType<SignatureData>;
+
+/**
+ * MDX config: `<Signature name params={[...]} returns={{...}} />` self-closing,
+ * matching the `FileTree`/`AnnotatedCode` JSON-attribute style rather than
+ * markdown children, since a signature is structured data, not prose.
+ */
+export const signatureMdx: BlockMdxConfig<SignatureData> = {
+  tag: "Signature",
+  toAttrs: (data) => ({
+    name: data.name,
+    params: data.params,
+    returns: data.returns as Record<string, unknown> | undefined,
+  }),
+  fromAttrs: (attrs) => ({
+    name: attrs.string("name") ?? "",
+    params: attrs.array<SignatureParam>("params") ?? [],
+    returns: attrs.object<SignatureReturns>("returns"),
+  }),
+};
diff --git a/packages/docs/app/components/blocks/signature.tsx b/packages/docs/app/components/blocks/signature.tsx
new file mode 100644
index 0000000000..a0d7c847dd
--- /dev/null
+++ b/packages/docs/app/components/blocks/signature.tsx
@@ -0,0 +1,141 @@
+import { defineBlock } from "@agent-native/core/blocks";
+import type {
+  BlockReadProps,
+  BlockRenderContext,
+} from "@agent-native/core/blocks";
+import { IconChevronRight } from "@tabler/icons-react";
+import { useState } from "react";
+
+import {
+  signatureSchema,
+  signatureMdx,
+  type SignatureData,
+  type SignatureField,
+} from "./signature.config";
+
+export type { SignatureData };
+
+function paramSignatureText(param: SignatureField): string {
+  return `${param.name}${param.optional ? "?" : ""}: ${param.type}`;
+}
+
+function FieldRow({
+  field,
+  ctx,
+}: {
+  field: SignatureField;
+  ctx: BlockRenderContext;
+}) {
+  return (
+    <div className="docs-sig-field">
+      <div className="docs-sig-field-head">
+        <span className="docs-sig-field-name">{field.name}</span>
+        <span className="docs-sig-field-type">{field.type}</span>
+        {field.optional && <span className="docs-sig-field-tag">optional</span>}
+        {field.default && (
+          <span className="docs-sig-field-tag">default {field.default}</span>
+        )}
+      </div>
+      {ctx.renderMarkdown?.(field.description) ?? (
+        <p className="docs-sig-field-desc">{field.description}</p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Read-only renderer for a `signature` block. Collapsed by default to just the
+ * code-style call line; clicking it reveals the parameter/return breakdown. The
+ * generic block `title` (falling back to "Signature") renders as a faded label
+ * above the whole thing, separate from the clickable header inside it.
+ */
+export function SignatureBlock({
+  data,
+  title,
+  ctx,
+}: BlockReadProps<SignatureData>) {
+  const [open, setOpen] = useState(false);
+  const signatureLine = `${data.name}(${data.params
+    .map(paramSignatureText)
+    .join(", ")})${data.returns ? `: ${data.returns.type}` : ""}`;
+
+  return (
+    <div className="docs-sig-wrap">
+      <p className="docs-sig-title">{title || "Signature"}</p>
+      <section className="docs-signature">
+        <button
+          type="button"
+          className="docs-sig-line"
+          aria-expanded={open}
+          onClick={() => setOpen((current) => !current)}
+        >
+          <IconChevronRight className="docs-sig-chevron" aria-hidden="true" />
+          <code className="docs-sig-code">{signatureLine}</code>
+        </button>
+
+        {open && (
+          <>
+            {data.params.length > 0 && (
+              <div className="docs-sig-section">
+                <p className="docs-sig-section-label">Parameters</p>
+                <div className="docs-sig-params">
+                  {data.params.map((param, i) => (
+                    <div key={i} className="docs-sig-param">
+                      <FieldRow field={param} ctx={ctx} />
+                      {param.fields && param.fields.length > 0 && (
+                        <div className="docs-sig-nested-fields">
+                          {param.fields.map((field, j) => (
+                            <FieldRow key={j} field={field} ctx={ctx} />
+                          ))}
+                        </div>
+                      )}
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {data.returns && (
+              <div className="docs-sig-section">
+                <p className="docs-sig-section-label">Returns</p>
+                <div className="docs-sig-returns">
+                  <span className="docs-sig-field-type">
+                    {data.returns.type}
+                  </span>
+                  {data.returns.description &&
+                    (ctx.renderMarkdown?.(data.returns.description) ?? (
+                      <p className="docs-sig-field-desc">
+                        {data.returns.description}
+                      </p>
+                    ))}
+                </div>
+              </div>
+            )}
+          </>
+        )}
+      </section>
+    </div>
+  );
+}
+
+export const signatureBlock = defineBlock<SignatureData>({
+  type: "signature",
+  schema: signatureSchema,
+  mdx: signatureMdx,
+  Read: SignatureBlock,
+  placement: ["block"],
+  label: "Signature",
+  description:
+    "A function/hook signature reference: a code-style call line plus a parameter and return-type breakdown.",
+  empty: () => ({
+    name: "myFunction",
+    params: [
+      {
+        name: "input",
+        type: "string",
+        description: "Describe the parameter.",
+      },
+    ],
+    returns: { type: "void" },
+  }),
+});
diff --git a/packages/docs/app/components/blocks/video.config.ts b/packages/docs/app/components/blocks/video.config.ts
new file mode 100644
index 0000000000..f8a4a93594
--- /dev/null
+++ b/packages/docs/app/components/blocks/video.config.ts
@@ -0,0 +1,71 @@
+import type { BlockMdxConfig } from "@agent-native/core/blocks";
+import { z } from "zod";
+
+import {
+  mediaAlignSchema,
+  mediaCaptionSchema,
+  mediaSrcSchema,
+  mediaTextSchema,
+  mediaWidthSchema,
+  type MediaAlign,
+} from "./media-shared";
+
+export interface VideoData {
+  /** Direct video file URL (mp4/webm), not a third-party embed iframe. */
+  src: string;
+  alt: string;
+  align?: MediaAlign;
+  width?: number;
+  caption?: string;
+  /** Markdown paired text shown beside the video when aligned left/right. */
+  text?: string;
+  /**
+   * Autoplay on load. The renderer always forces `muted` alongside this
+   * (browsers block autoplay with sound) and skips autoplaying entirely for
+   * viewers with `prefers-reduced-motion: reduce`, who instead get a normal
+   * paused player with full (unmuted) playback once they press play.
+   */
+  autoplay?: boolean;
+  /** Restart from the beginning on end, independent of `autoplay`. */
+  loop?: boolean;
+}
+
+export const videoSchema = z.object({
+  src: mediaSrcSchema,
+  alt: z.string().trim().min(1).max(400),
+  align: mediaAlignSchema,
+  width: mediaWidthSchema,
+  caption: mediaCaptionSchema,
+  text: mediaTextSchema,
+  autoplay: z.boolean().optional(),
+  loop: z.boolean().optional(),
+}) as unknown as z.ZodType<VideoData>;
+
+/**
+ * MDX config: `<Video src alt align width caption autoplay loop>text</Video>`,
+ * mirroring `image.config.ts` (minus `autoplay`/`loop`) so the two blocks stay
+ * in lockstep.
+ */
+export const videoMdx: BlockMdxConfig<VideoData> = {
+  tag: "Video",
+  childrenField: "text",
+  toAttrs: (data) => ({
+    src: data.src,
+    alt: data.alt,
+    align: data.align,
+    width: data.width,
+    caption: data.caption,
+    autoplay: data.autoplay,
+    loop: data.loop,
+  }),
+  fromAttrs: (attrs, children) => ({
+    src: attrs.string("src") ?? "",
+    alt: attrs.string("alt") ?? "",
+    align: attrs.string("align") as MediaAlign | undefined,
+    width: attrs.number("width"),
+    caption: attrs.string("caption"),
+    text: children.trim() ? children : undefined,
+    autoplay: attrs.bool("autoplay"),
+    loop: attrs.bool("loop"),
+  }),
+};
diff --git a/packages/docs/app/components/blocks/video.tsx b/packages/docs/app/components/blocks/video.tsx
new file mode 100644
index 0000000000..63b35bee02
--- /dev/null
+++ b/packages/docs/app/components/blocks/video.tsx
@@ -0,0 +1,77 @@
+import { defineBlock } from "@agent-native/core/blocks";
+import type { BlockReadProps } from "@agent-native/core/blocks";
+import { useEffect, useState } from "react";
+
+import { MediaFrame } from "./media-layout";
+import { videoSchema, videoMdx, type VideoData } from "./video.config";
+
+export type { VideoData };
+
+/**
+ * Tracks `prefers-reduced-motion: reduce`. Starts `false` (matches SSR, where
+ * there's no `window` to ask) and updates after mount, so a reduced-motion
+ * viewer never sees a flash of autoplay before it's suppressed.
+ */
+function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+
+  useEffect(() => {
+    if (typeof window === "undefined" || !window.matchMedia) return;
+    const query = window.matchMedia("(prefers-reduced-motion: reduce)");
+    setReduced(query.matches);
+    const onChange = (event: MediaQueryListEvent) => setReduced(event.matches);
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+  }, []);
+
+  return reduced;
+}
+
+export function VideoBlock({ data, ctx }: BlockReadProps<VideoData>) {
+  const prefersReducedMotion = usePrefersReducedMotion();
+  // Autoplay only fires when requested AND the viewer hasn't asked for less
+  // motion. Muted/playsInline are tied to that same resolved decision, not to
+  // the raw `autoplay` flag: a reduced-motion viewer who presses play
+  // themselves gets a normal, unmuted playback, not a silently-muted one.
+  const shouldAutoplay = Boolean(data.autoplay) && !prefersReducedMotion;
+
+  return (
+    <MediaFrame
+      className="docs-video"
+      align={data.align}
+      width={data.width}
+      caption={data.caption}
+      text={data.text}
+      ctx={ctx}
+      media={
+        // `<video>` has no native `alt`; `aria-label` is its text alternative.
+        <video
+          src={data.src}
+          aria-label={data.alt}
+          controls
+          preload="metadata"
+          autoPlay={shouldAutoplay}
+          muted={shouldAutoplay}
+          playsInline={shouldAutoplay}
+          loop={Boolean(data.loop)}
+        />
+      }
+    />
+  );
+}
+
+export const videoBlock = defineBlock<VideoData>({
+  type: "video",
+  schema: videoSchema,
+  mdx: videoMdx,
+  Read: VideoBlock,
+  placement: ["block"],
+  label: "Video",
+  description:
+    "A direct-file video (mp4/webm), full width or aligned left/right with paired markdown text, an optional caption, reduced-motion-aware autoplay, and looping.",
+  empty: () => ({
+    src: "/videos/example.mp4",
+    alt: "Describe the video for screen readers.",
+    align: "full",
+  }),
+});
diff --git a/packages/docs/app/components/docBlocks.tsx b/packages/docs/app/components/docBlocks.tsx
index 8a1997dd1c..6418118c6d 100644
--- a/packages/docs/app/components/docBlocks.tsx
+++ b/packages/docs/app/components/docBlocks.tsx
@@ -45,7 +45,10 @@ import {
 } from "../../lib/doc-block-segments";
 import { cardsBlock } from "./blocks/cards";
 import { comparisonBlock } from "./blocks/comparison";
+import { imageBlock } from "./blocks/image";
+import { signatureBlock } from "./blocks/signature";
 import { stepsBlock } from "./blocks/steps";
+import { videoBlock } from "./blocks/video";
 import { renderMarkdownToHtml } from "./MarkdownRenderer";
 
 export {
@@ -76,6 +79,9 @@ function getDocBlockRegistry(): BlockRegistry {
   registry.register(stepsBlock);
   registry.register(cardsBlock);
   registry.register(comparisonBlock);
+  registry.register(signatureBlock);
+  registry.register(imageBlock);
+  registry.register(videoBlock);
   cachedRegistry = registry;
   return registry;
 }
diff --git a/packages/docs/app/global.css b/packages/docs/app/global.css
index 82296be026..5ea9eb5f0b 100644
--- a/packages/docs/app/global.css
+++ b/packages/docs/app/global.css
@@ -681,6 +681,235 @@ h4 {
   font-size: 14px;
 }
 
+/* Signature: function/hook signature reference — call line + parameter/return
+   breakdown, collapsed to the call line until clicked.
+   Usage in MDX: <Signature name params={[...]} returns={{...}} /> */
+.docs-sig-wrap {
+  margin: 24px 0;
+}
+
+.docs-sig-title {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--fg-secondary);
+  margin: 0 0 8px;
+}
+
+.docs-sig-line {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  width: 100%;
+  margin: 0;
+  padding: 14px 16px;
+  background: var(--bg-secondary);
+  border: none;
+  border-bottom: 1px solid var(--docs-border);
+  border-radius: 0;
+  font: inherit;
+  text-align: left;
+  cursor: pointer;
+  overflow-x: auto;
+}
+
+.docs-sig-line:hover {
+  background: color-mix(in srgb, var(--bg-secondary) 85%, var(--fg) 6%);
+}
+
+.docs-sig-line:focus-visible {
+  outline: 2px solid var(--docs-accent);
+  outline-offset: -2px;
+}
+
+.docs-sig-chevron {
+  width: 14px;
+  height: 14px;
+  flex-shrink: 0;
+  color: var(--fg-secondary);
+  transition: transform 0.15s;
+}
+
+.docs-sig-line[aria-expanded="true"] .docs-sig-chevron {
+  transform: rotate(90deg);
+}
+
+.docs-sig-code {
+  font-family: var(--font-mono);
+  font-size: 13px;
+  color: var(--fg);
+  white-space: pre;
+}
+
+.docs-sig-section {
+  padding: 16px;
+}
+
+.docs-sig-section + .docs-sig-section {
+  border-top: 1px solid var(--docs-border);
+}
+
+.docs-sig-section-label {
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--fg-secondary);
+  margin: 0 0 12px;
+}
+
+.docs-sig-params {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+}
+
+.docs-sig-param + .docs-sig-param {
+  padding-top: 14px;
+  border-top: 1px dashed var(--docs-border);
+}
+
+.docs-sig-field-head {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.docs-sig-field-name {
+  font-family: var(--font-mono);
+  font-size: 13px;
+  font-weight: 600;
+  color: var(--fg);
+}
+
+.docs-sig-field-type {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  color: var(--docs-accent);
+}
+
+.docs-sig-field-tag {
+  font-size: 11px;
+  color: var(--fg-secondary);
+  padding: 1px 6px;
+  border-radius: 4px;
+  background: var(--bg-secondary);
+}
+
+.docs-sig-field-desc {
+  margin: 6px 0 0;
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--fg-secondary);
+}
+
+.docs-sig-field .docs-content {
+  margin-top: 6px;
+}
+
+.docs-sig-field .docs-content p {
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--fg-secondary);
+  margin: 0;
+}
+
+.docs-sig-nested-fields {
+  margin: 10px 0 0 16px;
+  padding-left: 12px;
+  border-left: 1px solid var(--docs-border);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+/* Image / Video: full width, or aligned left/right with paired markdown text.
+   Usage in MDX: <Image src alt align width caption>paired text</Image>
+   and the same shape for <Video>. Shared layout lives in media-layout.tsx. */
+.docs-media {
+  margin: 24px 0;
+}
+
+.docs-media-full {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+}
+
+.docs-media-full .docs-media-figure {
+  width: 100%;
+}
+
+.docs-media-left,
+.docs-media-right {
+  display: flex;
+  gap: 20px;
+  align-items: flex-start;
+}
+
+.docs-media-left .docs-media-figure,
+.docs-media-right .docs-media-figure {
+  flex: 0 0 40%;
+  max-width: 45%;
+}
+
+.docs-media-text {
+  flex: 1;
+  min-width: 0;
+  font-size: 14px;
+  line-height: 1.7;
+  color: var(--fg-secondary);
+}
+
+.docs-media-text p {
+  margin: 0 0 12px;
+  font-size: 14px;
+}
+
+.docs-media-text p:last-child {
+  margin-bottom: 0;
+}
+
+.docs-media img,
+.docs-media video {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: 8px;
+  border: 1px solid var(--docs-border);
+  background: var(--bg-secondary);
+}
+
+.docs-media-caption {
+  margin-top: 8px;
+  font-size: 12px;
+  line-height: 1.5;
+  color: var(--fg-secondary);
+}
+
+.docs-media-caption p {
+  margin: 0;
+  font-size: 12px;
+}
+
+.docs-media-full .docs-media-caption {
+  text-align: center;
+}
+
+@media (max-width: 640px) {
+  .docs-media-left,
+  .docs-media-right {
+    flex-direction: column;
+  }
+  .docs-media-left .docs-media-figure,
+  .docs-media-right .docs-media-figure {
+    max-width: 100%;
+    flex-basis: auto !important;
+  }
+}
+
 /* Sidebar nav */
 .docs-sidebar-nav {
   overflow-anchor: none;
diff --git a/packages/docs/lib/doc-block-segments.ts b/packages/docs/lib/doc-block-segments.ts
index b89634a8ed..7e8693c3e1 100644
--- a/packages/docs/lib/doc-block-segments.ts
+++ b/packages/docs/lib/doc-block-segments.ts
@@ -15,7 +15,13 @@ import {
   comparisonSchema,
   comparisonMdx,
 } from "../app/components/blocks/comparison.config";
+import { imageSchema, imageMdx } from "../app/components/blocks/image.config";
+import {
+  signatureSchema,
+  signatureMdx,
+} from "../app/components/blocks/signature.config";
 import { stepsSchema, stepsMdx } from "../app/components/blocks/steps.config";
+import { videoSchema, videoMdx } from "../app/components/blocks/video.config";
 
 const BLOCK_TYPE_ALIASES: Record<string, string> = {
   "an-diagram": "diagram",
@@ -95,6 +101,9 @@ const DOCS_EXTRA_BLOCKS: Array<{ type: string; schema: any; mdx: any }> = [
   { type: "steps", schema: stepsSchema, mdx: stepsMdx },
   { type: "cards", schema: cardsSchema, mdx: cardsMdx },
   { type: "comparison", schema: comparisonSchema, mdx: comparisonMdx },
+  { type: "signature", schema: signatureSchema, mdx: signatureMdx },
+  { type: "image", schema: imageSchema, mdx: imageMdx },
+  { type: "video", schema: videoSchema, mdx: videoMdx },
 ];
 
 function getDocBlockConfigRegistry(): BlockRegistry {

From 7f46bbba4d023c72f715f078b1079370a843327b Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Fri, 7 Aug 2026 14:59:56 -0700
Subject: [PATCH 02/22] feat: add hover-to-expand popup to the Image docs
 component

Hovering the image reveals a top-right button that opens it in a
larger popup, matching the Escape/click-outside/close-button contract
already established for diagrams. Paired left/right text and the
caption render stacked below the image inside the popup instead of
beside it, since the two-column layout only makes sense at the inline
aligned size. Video is unchanged.
---
 .../core/docs/content/docs-components.mdx     |   2 +
 packages/docs/app/components/blocks/image.tsx |   3 +-
 .../app/components/blocks/media-layout.tsx    | 121 +++++++++++++++---
 packages/docs/app/global.css                  | 102 +++++++++++++++
 4 files changed, 210 insertions(+), 18 deletions(-)

diff --git a/packages/core/docs/content/docs-components.mdx b/packages/core/docs/content/docs-components.mdx
index 5792cea51a..16c0452c4a 100644
--- a/packages/core/docs/content/docs-components.mdx
+++ b/packages/core/docs/content/docs-components.mdx
@@ -253,6 +253,8 @@ Aligning an image left or right turns it into a two-column row. The image sits o
 
 `alt` is required. `align` is `"full"` (the default), `"left"`, or `"right"`. `width` is an optional pixel hint for the image column when aligned, and has no effect on `"full"`. `caption` renders in small muted text under the image. Anything between the open and close tags is markdown, and becomes the paired text next to the image when aligned, or plain content below it when full width. Omit the children entirely for a self-closing `<Image ... />` with no paired text.
 
+Hovering the image reveals a top-right expand button that opens it in a larger popup. If the image has paired text (or a caption), the popup stacks it below the image instead of beside it, since the two-column layout only makes sense at the inline aligned size.
+
 For a plain full-width image with no paired text, omit `align` (or set it to `"full"`) and skip the children entirely:
 
 <Image
diff --git a/packages/docs/app/components/blocks/image.tsx b/packages/docs/app/components/blocks/image.tsx
index 5e1f4bb483..3615493170 100644
--- a/packages/docs/app/components/blocks/image.tsx
+++ b/packages/docs/app/components/blocks/image.tsx
@@ -16,6 +16,7 @@ export function ImageBlock({ data, ctx }: BlockReadProps<ImageData>) {
       text={data.text}
       ctx={ctx}
       media={<img src={data.src} alt={data.alt} loading="lazy" />}
+      expandable
     />
   );
 }
@@ -28,7 +29,7 @@ export const imageBlock = defineBlock<ImageData>({
   placement: ["block"],
   label: "Image",
   description:
-    "An image, full width or aligned left/right with paired markdown text and an optional caption.",
+    "An image, full width or aligned left/right with paired markdown text, an optional caption, and a hover-to-expand popup.",
   empty: () => ({
     src: "/images/example.png",
     alt: "Describe the image for screen readers.",
diff --git a/packages/docs/app/components/blocks/media-layout.tsx b/packages/docs/app/components/blocks/media-layout.tsx
index e3afd1891b..edb352764d 100644
--- a/packages/docs/app/components/blocks/media-layout.tsx
+++ b/packages/docs/app/components/blocks/media-layout.tsx
@@ -1,14 +1,72 @@
 import type { BlockRenderContext } from "@agent-native/core/blocks";
-import type { ReactNode } from "react";
+import { IconArrowsMaximize, IconX } from "@tabler/icons-react";
+import { useEffect, useState, type ReactNode } from "react";
 
 import type { MediaAlign } from "./media-shared";
 
+/**
+ * Fixed-backdrop popup for `expandable` media. Mirrors core's
+ * `DiagramLightbox` contract (Escape to close, click-the-backdrop to close,
+ * top-right close button, body scroll locked while open) rather than
+ * importing it, since that lives in `@agent-native/core`'s public blocks
+ * surface and would need a changeset for what's a docs-site-only need.
+ */
+function MediaLightbox({
+  children,
+  onClose,
+}: {
+  children: ReactNode;
+  onClose: () => void;
+}) {
+  useEffect(() => {
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") onClose();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    document.body.style.overflow = "hidden";
+    return () => {
+      document.removeEventListener("keydown", onKeyDown);
+      document.body.style.overflow = "";
+    };
+  }, [onClose]);
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      aria-label="Media preview"
+      onClick={onClose}
+      className="docs-media-lightbox-backdrop"
+    >
+      <div
+        onClick={(event) => event.stopPropagation()}
+        className="docs-media-lightbox-panel"
+      >
+        {children}
+      </div>
+      <button
+        type="button"
+        onClick={onClose}
+        aria-label="Close preview"
+        className="docs-media-lightbox-close"
+      >
+        <IconX className="docs-media-lightbox-close-icon" aria-hidden="true" />
+      </button>
+    </div>
+  );
+}
+
 /**
  * Shared layout for the `image` and `video` blocks: full width, or a flex row
  * with the media on one side and markdown `text` as the paired content on the
  * other. `align="left"` puts the media on the left (text on the right);
  * `align="right"` mirrors it. Falls back to full width whenever there's no
  * paired text, since a side-by-side row needs both columns to make sense.
+ *
+ * `expandable` adds a hover-revealed top-right button that opens the same
+ * media in a larger popup. Inside the popup, paired `text` always renders
+ * stacked below the media instead of beside it, since the two-column layout
+ * only makes sense at the inline aligned size.
  */
 export function MediaFrame({
   className,
@@ -18,6 +76,7 @@ export function MediaFrame({
   text,
   ctx,
   media,
+  expandable,
 }: {
   className: string;
   align?: MediaAlign;
@@ -26,11 +85,19 @@ export function MediaFrame({
   text?: string;
   ctx: BlockRenderContext;
   media: ReactNode;
+  expandable?: boolean;
 }) {
+  const [expanded, setExpanded] = useState(false);
   const resolvedAlign = align ?? "full";
   const hasText = Boolean(text && text.trim());
   const sideBySide = resolvedAlign !== "full" && hasText;
 
+  const captionNode = caption && (
+    <div className="docs-media-caption">
+      {ctx.renderMarkdown?.(caption) ?? <p>{caption}</p>}
+    </div>
+  );
+
   const figure = (
     <div
       className="docs-media-figure"
@@ -40,12 +107,23 @@ export function MediaFrame({
           : undefined
       }
     >
-      {media}
-      {caption && (
-        <div className="docs-media-caption">
-          {ctx.renderMarkdown?.(caption) ?? <p>{caption}</p>}
-        </div>
-      )}
+      <div className="docs-media-figure-inner">
+        {media}
+        {expandable && (
+          <button
+            type="button"
+            className="docs-media-expand"
+            aria-label="Expand"
+            onClick={() => setExpanded(true)}
+          >
+            <IconArrowsMaximize
+              className="docs-media-expand-icon"
+              aria-hidden="true"
+            />
+          </button>
+        )}
+      </div>
+      {captionNode}
     </div>
   );
 
@@ -55,20 +133,29 @@ export function MediaFrame({
     </div>
   );
 
-  if (!sideBySide) {
-    return (
-      <div className={`docs-media docs-media-full ${className}`}>
-        {figure}
-        {textColumn}
-      </div>
-    );
-  }
-
-  return (
+  const frame = !sideBySide ? (
+    <div className={`docs-media docs-media-full ${className}`}>
+      {figure}
+      {textColumn}
+    </div>
+  ) : (
     <div className={`docs-media docs-media-${resolvedAlign} ${className}`}>
       {resolvedAlign === "right" && textColumn}
       {figure}
       {resolvedAlign === "left" && textColumn}
     </div>
   );
+
+  return (
+    <>
+      {frame}
+      {expandable && expanded && (
+        <MediaLightbox onClose={() => setExpanded(false)}>
+          {media}
+          {captionNode}
+          {textColumn}
+        </MediaLightbox>
+      )}
+    </>
+  );
 }
diff --git a/packages/docs/app/global.css b/packages/docs/app/global.css
index 5ea9eb5f0b..6ee25a2985 100644
--- a/packages/docs/app/global.css
+++ b/packages/docs/app/global.css
@@ -882,6 +882,108 @@ h4 {
   background: var(--bg-secondary);
 }
 
+.docs-media-figure-inner {
+  position: relative;
+}
+
+.docs-media-expand {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  border-radius: 6px;
+  border: 1px solid var(--docs-border);
+  background: var(--bg);
+  color: var(--fg-secondary);
+  opacity: 0;
+  cursor: pointer;
+  transition:
+    opacity 0.15s,
+    color 0.15s;
+}
+
+.docs-media-figure-inner:hover .docs-media-expand,
+.docs-media-expand:focus-visible {
+  opacity: 1;
+}
+
+.docs-media-expand:hover {
+  color: var(--fg);
+}
+
+.docs-media-expand-icon {
+  width: 16px;
+  height: 16px;
+}
+
+.docs-media-lightbox-backdrop {
+  position: fixed;
+  inset: 0;
+  z-index: 300;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: auto;
+  background: rgba(0, 0, 0, 0.8);
+  padding: 24px;
+  cursor: zoom-out;
+}
+
+.docs-media-lightbox-panel {
+  max-height: 100%;
+  width: 100%;
+  max-width: 960px;
+  cursor: default;
+  overflow: auto;
+  border-radius: 8px;
+  background: var(--bg);
+  padding: 20px;
+  box-shadow: 0 20px 60px rgba(0, 0, 0, 0.35);
+}
+
+.docs-media-lightbox-panel img,
+.docs-media-lightbox-panel video {
+  display: block;
+  width: 100%;
+  height: auto;
+  border-radius: 8px;
+  border: 1px solid var(--docs-border);
+}
+
+.docs-media-lightbox-panel .docs-media-caption,
+.docs-media-lightbox-panel .docs-media-text {
+  margin-top: 12px;
+}
+
+.docs-media-lightbox-close {
+  position: absolute;
+  top: 16px;
+  right: 16px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 32px;
+  height: 32px;
+  border-radius: 999px;
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  background: rgba(0, 0, 0, 0.4);
+  color: #fff;
+  cursor: pointer;
+}
+
+.docs-media-lightbox-close:hover {
+  background: rgba(0, 0, 0, 0.6);
+}
+
+.docs-media-lightbox-close-icon {
+  width: 16px;
+  height: 16px;
+}
+
 .docs-media-caption {
   margin-top: 8px;
   font-size: 12px;

From ed34c3b211a4420f7bd2f78ff9fef1cb659a099c Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Fri, 7 Aug 2026 15:30:50 -0700
Subject: [PATCH 03/22] feat: polish the Signature docs component's title and
 expanded border

Adds a static "Function signature" caption above the component (no
longer forced to uppercase, which mangled camelCase function names),
and a thin border around the expanded parameter/return content so
it's clear where the expanded state ends.
---
 .../docs/app/components/blocks/signature.tsx   | 18 +++++++-----------
 packages/docs/app/global.css                   |  8 ++++++--
 2 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/packages/docs/app/components/blocks/signature.tsx b/packages/docs/app/components/blocks/signature.tsx
index a0d7c847dd..4f02f67eb0 100644
--- a/packages/docs/app/components/blocks/signature.tsx
+++ b/packages/docs/app/components/blocks/signature.tsx
@@ -45,15 +45,11 @@ function FieldRow({
 
 /**
  * Read-only renderer for a `signature` block. Collapsed by default to just the
- * code-style call line; clicking it reveals the parameter/return breakdown. The
- * generic block `title` (falling back to "Signature") renders as a faded label
- * above the whole thing, separate from the clickable header inside it.
+ * code-style call line; clicking it reveals the parameter/return breakdown. A
+ * static "Function signature" label renders as a faded caption above the
+ * whole thing, separate from the clickable header inside it.
  */
-export function SignatureBlock({
-  data,
-  title,
-  ctx,
-}: BlockReadProps<SignatureData>) {
+export function SignatureBlock({ data, ctx }: BlockReadProps<SignatureData>) {
   const [open, setOpen] = useState(false);
   const signatureLine = `${data.name}(${data.params
     .map(paramSignatureText)
@@ -61,7 +57,7 @@ export function SignatureBlock({
 
   return (
     <div className="docs-sig-wrap">
-      <p className="docs-sig-title">{title || "Signature"}</p>
+      <p className="docs-sig-title">Function signature</p>
       <section className="docs-signature">
         <button
           type="button"
@@ -74,7 +70,7 @@ export function SignatureBlock({
         </button>
 
         {open && (
-          <>
+          <div className="docs-sig-body">
             {data.params.length > 0 && (
               <div className="docs-sig-section">
                 <p className="docs-sig-section-label">Parameters</p>
@@ -111,7 +107,7 @@ export function SignatureBlock({
                 </div>
               </div>
             )}
-          </>
+          </div>
         )}
       </section>
     </div>
diff --git a/packages/docs/app/global.css b/packages/docs/app/global.css
index 6ee25a2985..c8fd82afb8 100644
--- a/packages/docs/app/global.css
+++ b/packages/docs/app/global.css
@@ -691,8 +691,6 @@ h4 {
 .docs-sig-title {
   font-size: 11px;
   font-weight: 700;
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
   color: var(--fg-secondary);
   margin: 0 0 8px;
 }
@@ -742,6 +740,12 @@ h4 {
   white-space: pre;
 }
 
+.docs-sig-body {
+  border: 1px solid var(--docs-border);
+  border-top: none;
+  border-radius: 0;
+}
+
 .docs-sig-section {
   padding: 16px;
 }

From 19c4d1d7b90055f8d0a39eb8c4746ff2864d4116 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Fri, 7 Aug 2026 15:40:57 -0700
Subject: [PATCH 04/22] docs: add Client Overview draft page

Covers app/ and public/: where the display of an agent-native app is
built, the browser runtime pieces nothing else documents (root.tsx,
AppProviders, entry points), and static assets. Links out to the
focused Data & Sync and Agent Chat pages for the data/agent hooks.
---
 .../core/docs/content/client-overview.mdx     | 200 ++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 packages/core/docs/content/client-overview.mdx

diff --git a/packages/core/docs/content/client-overview.mdx b/packages/core/docs/content/client-overview.mdx
new file mode 100644
index 0000000000..baa289a67a
--- /dev/null
+++ b/packages/core/docs/content/client-overview.mdx
@@ -0,0 +1,200 @@
+---
+title: "Overview"
+description: "The app/ and public/ directories: where you build the display of an agent-native app, and the browser APIs it uses to stay in sync with the agent."
+draft: true
+---
+
+# Overview
+
+`app/` is where you build the actual display of an agent-native app: pages, layout, components, styles. `public/` holds the static assets served alongside it — icons, manifest, brand marks. This is a typical React Router v8 app, not a special agent-only surface, and it's where most development time goes.
+
+The one architectural difference from a typical frontend: this layer has no backend-for-frontend of its own. It reads and writes data through the same actions the agent calls, so anything wired up here is automatically something the agent can also do.
+
+<Diagram id="doc-block-client-overview-1" title="Traditional frontend vs. Agent Native" summary="A traditional frontend calls its own API layer, which only it can reach. In Agent Native, app/ and the agent both call the same actions, so every capability built here is agent-callable for free.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Traditional</div>
+    <div class="diagram-node">app/ (React frontend)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API layer</strong>
+      <small class="diagram-muted">only the frontend calls it</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React frontend)</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">equal partners, same operations</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL database</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Where the Client Fits {#role}
+
+Browser requests, the agent loop, and external API clients all resolve to the same actions and the same SQL database — there is no separate "app backend" this layer talks to that the agent can't also reach. Building a feature here means building a UI on top of an operation the agent already has, or defining a new action and getting a UI for it at the same time. See [Actions](/docs/actions) for the operation side of that contract.
+
+This page covers the directories you build in and the pieces of the browser runtime nothing else documents (`root.tsx`, `public/`). The React hooks that connect your components to actions and to the agent live on their own focused pages:
+
+| Page | What it covers |
+| --- | --- |
+| **[Data & Sync](/docs/client-data)** | `useActionQuery`, `useActionMutation`, `callAction`, and `useDbSync` |
+| **[Agent Chat](/docs/client-agent-chat)** | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, and dynamic suggestions |
+| **[Advanced](/docs/client-advanced)** | Direct `application_state` access, `useChangeVersion`, agent chat context state, the MCP App host bridge, and the SSR entry points |
+
+## What's in app/ and public/ {#project-directories}
+
+| Path | What it covers |
+| --- | --- |
+| **`app/root.tsx`** | The HTML shell and provider stack — see [The Browser Shell](#app-shell) below |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration and SSR bootstrap — see [Advanced](/docs/client-advanced#entry-points) |
+| **`app/routes.ts` + `app/routes/`** | File-based pages and navigation — see [Routing](/docs/routing) |
+| **`app/components/`** | Your UI: shadcn-style primitives plus app-specific components — see [shadcn/ui](/docs/shadcn-ui) |
+| **`app/hooks/`** | Data, sync, and agent-chat hooks — see [Data & Sync](/docs/client-data) and [Agent Chat](/docs/client-agent-chat) |
+| **`app/lib/`** | Shared client utilities (app config, tab id, `cn`) — see [Utilities](#utilities) below |
+| **`app/design-system.ts`** | Optional custom design system adapter — see [Custom Design Systems](/docs/custom-design-system) |
+| **`app/i18n/`** | Localized UI copy catalogs — see [Internationalization](/docs/internationalization) |
+| **`app/global.css`** | Base styles and the Tailwind entry point |
+| **`public/`** | Static assets served as-is — see [Static Assets](#public-directory) below |
+
+## The Browser Shell: root.tsx and AppProviders {#app-shell}
+
+`app/root.tsx` is the top of the React tree: the HTML document shell (`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`) plus the provider stack every route renders inside.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` is the single wrapper that wires up:
+
+- The React Query client used by `useActionQuery`/`useActionMutation` (see [Data & Sync](/docs/client-data#fetching-mutating)).
+- The i18n catalog passed as `i18n.catalog` (see [Internationalization](/docs/internationalization)).
+- Client-side session checks: on a private path, an anonymous visitor is redirected to sign-in before any private UI mounts. Pass `isPublicPath` for public/SEO routes, or `sessionBypass` for a surface that authenticates another way, such as an MCP embed token. See [Authentication](/docs/authentication).
+
+Most apps also mount `<AgentSidebar>` or `<AgentPanel>` here so every route gets the agent panel for free. See [Drop-in Agent](/docs/drop-in-agent#sidebar).
+
+## Static Assets: public/ {#public-directory}
+
+Everything in `public/` is served as-is at the site root, unprocessed by the build. Every template ships:
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+`manifest.json` controls what shows up if a visitor installs the app to a home screen or app dock — name, short name, theme/background color, and the icon set:
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [{ "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }]
+}
+```
+
+Rebrand an app by replacing these files and updating `manifest.json` and the `<link rel="icon">`/`<link rel="apple-touch-icon">` tags in `root.tsx` that reference them — there's no separate registration step. For pulling a full brand system (colors, fonts, favicon) from an existing site instead of hand-editing these, see [Brand Systems and Figma](/docs/template-design-brand-and-figma).
+
+## Utilities: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` merges class names (clsx + tailwind-merge) and is the standard way to compose conditional Tailwind classes across `app/components/`.
+
+## What's next
+
+- [**Data & Sync**](/docs/client-data) — action hooks and `useDbSync`
+- [**Agent Chat**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion`, and dynamic suggestions
+- [**Advanced**](/docs/client-advanced) — application state, custom query keys, and the MCP App host bridge
+- [**Routing**](/docs/routing) — file-based pages, dynamic params, and navigation
+- [**Actions**](/docs/actions) — the `defineAction` surface behind every data hook
+- [**Custom Design Systems**](/docs/custom-design-system) — swapping in your own component library via `app/design-system.ts`
+- [**Authentication**](/docs/authentication) — the session checks `AppProviders` runs on private paths

From 5e858f9881fa63a1f64e0523e5e5e97a0bff1ddb Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Fri, 7 Aug 2026 15:41:13 -0700
Subject: [PATCH 05/22] docs: add Data & Sync draft page

Covers useActionQuery, useActionMutation, callAction, and useDbSync:
the action hooks app/ uses to read, write, and stay live-synced with
the same actions the agent calls. Examples are grounded in a real
ticket-support reference app rather than a hypothetical domain.
---
 packages/core/docs/content/client-data.mdx | 248 +++++++++++++++++++++
 1 file changed, 248 insertions(+)
 create mode 100644 packages/core/docs/content/client-data.mdx

diff --git a/packages/core/docs/content/client-data.mdx b/packages/core/docs/content/client-data.mdx
new file mode 100644
index 0000000000..f59e39632a
--- /dev/null
+++ b/packages/core/docs/content/client-data.mdx
@@ -0,0 +1,248 @@
+---
+title: "Data & Sync"
+description: "The action hooks app/ uses to read, write, and stay live-synced with the same actions the agent calls."
+draft: true
+---
+
+# Data & Sync
+
+The primary way to read and write app data from client application is through [action](/docs/actions) hooks. By embedding requests into actions, both your client and agent can interact with your application in the same way.
+
+In the example below, a ticket is assigned to the current user manually through a dropdown, and then through the chat agent. Both the UI and agent access the same action.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="Example of a UI action and an agent action having the same result."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Example of a UI action and an agent action having the same result."
+/>
+
+## Fetch and mutate data {#fetching-mutating}
+
+A typical app builds its own API layer and calls it with hand-written `fetch` requests. An agent-native app skips that layer: `app/` calls the same actions the agent already has as tools, through the hooks below.
+
+<Diagram id="doc-block-client-data-fm-1" title="Typical fetch vs. an action hook" summary="A typical component calls a route only it can reach. An agent-native component calls an action the agent can call too.">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Typical</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Your API route</strong>
+      <small class="diagram-muted">only the frontend can call it</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Database</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead action</span>
+      <small class="diagram-muted">also an agent tool</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL database</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Action hooks {#action-hooks}
+
+There are two action hooks you are most likely to use: `useActionQuery()` and `useActionMutation()`. These two hooks provide access to your app's actions.
+
+#### useActionQuery {#use-action-query}
+
+This hook is intended to be used for read-only actions. It is a thin wrapper around the [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) function. `useActionQuery()` accepts three arguments:
+
+- **actionName**: the action's registered name.
+- **params**: the action's input, typed from its `defineAction()` schema.
+- **options**: everything from the [useQuery options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) except `queryKey` and `queryFn`, which the hook
+  sets itself.
+
+In the example below, the `list-tickets` action is called. This is similar to making a GET request for all tickets.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+The following example shows a request to fetch a single ticket, through the `get-ticket` action. A `ticketId` is provided to scope the query to only return a specific ticket. The additional `enabled` option is provided to ensure the query does not automatically run, and instead only runs when a `ticketId` is present.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+Results are cached under `["action", name, params]` and refetch automatically whenever a mutating action completes, with no manual invalidation needed.
+
+#### useActionMutation {#use-action-mutation}
+
+This hook is intended to be used for actions that change data, like creating, updating, or sending something. It is a thin wrapper around the [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) function. `useActionMutation()` accepts two arguments:
+
+- **actionName**: the action's registered name.
+- **options**: everything from the [useMutation options](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) except `mutationFn`, which the hook sets itself. Two extra options are available. `method` overrides the default `POST` request. `skipActionQueryInvalidation` opts out of the automatic cache refresh described below.
+
+Unlike `useActionQuery()`, the action's input is not passed to the hook itself. It is passed to `mutate()` or `mutateAsync()` when you are ready to run the mutation.
+
+In the example below, the `send-ticket-reply` action is called to post a reply to a ticket. Call `mutate()` from an event handler, such as a button's `onClick`.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+The following example shows the same mutation with an `onSuccess` option. Cache invalidation happens automatically after every mutation, so `onSuccess` is only needed for local side effects, like clearing the reply composer once the reply is sent.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+On success, the hook emits a change event with `source: "action"`, so every `useActionQuery` reading affected data refetches automatically. No manual invalidation is needed.
+
+### callAction {#call-action}
+
+This function is for imperative one-off action calls outside of a React render flow, such as a plain event handler, a script, or any other non-React code path. It returns a promise directly instead of a hook result. `callAction()` accepts three arguments:
+
+- **actionName**: the action's registered name.
+- **params**: the action's input, typed from its `defineAction()` schema.
+- **options**: `method` overrides the default `POST` request. `signal` accepts an `AbortSignal`. `timeoutMs` overrides the default 60 second timeout.
+
+In the example below, the `update-ticket` action is called from a keyboard shortcut handler outside of React's render flow, assigning the ticket to a rep.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+The following example shows the same call with a `timeoutMs` option, useful for actions that legitimately take longer than the default 60 second timeout.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+Unlike the hooks above, `callAction()` has no cache and no automatic refetch. Pair it with a manual invalidation if other UI depends on the result.
+
+Every `useActionQuery()`, `useActionMutation()`, and `callAction()` request is bounded by a 60 second timeout, and timeouts surface as errors instead of retrying silently. `useActionQuery()` also cancels superseded requests automatically, using React Query's abort signal.
+
+## useDbSync {#usedbsync}
+
+This hook is intended to keep the UI in sync with database changes that happen outside of your own actions, like an agent write, a webhook, or a change made from another browser tab. It listens for changes over server-sent events, and falls back to polling when server-sent events are unavailable. `useDbSync()` accepts a single options argument. The full list of options is in the table below.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+### Options {#usedbsync-options}
+
+| Option             | Type               | Description                                                                                                                                                  |
+| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `queryClient`      | `QueryClient?`     | React-query client for cache invalidation                                                                                                                    |
+| `queryKeys`        | `string[]?`        | Deprecated and ignored. Kept for old call sites                                                                                                              |
+| `pollUrl`          | `string?`          | Poll endpoint URL. Default: `"/_agent-native/poll"`                                                                                                          |
+| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`. Pass `false` to use polling only                                                                       |
+| `interval`         | `number?`          | Polling interval in ms. Default: `2000`                                                                                                                      |
+| `fallbackInterval` | `number?`          | Fallback polling interval when SSE is unavailable. Default: `60000`                                                                                          |
+| `pauseWhenHidden`  | `boolean?`         | Pause polling when the browser tab is hidden. Default: `false`. Hidden tabs keep SSE connected and poll no faster than every 10s while active, 60s once idle |
+| `ignoreSource`     | `string?`          | Per-tab request source to ignore so a tab does not refetch from its own writes                                                                               |
+| `onEvent`          | `(data) => void`   | Optional callback when SSE/polling receives a change event                                                                                                   |
+
+For normal CRUD, prefer `useActionQuery()` and `useActionMutation()`. Mutating actions emit `source: "action"`, so those hooks refetch right away. Changes from the agent, a webhook, or another tab arrive through `useDbSync()` instead, over SSE or the polling fallback. If a raw `useQuery()` call needs to sync on a custom key, or you need to write to `application_state` directly, see [Advanced](/docs/client-advanced).
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout this page's hooks live in
+- [**Agent Chat**](/docs/client-agent-chat) — sending prompts and staging context for the agent
+- [**Actions**](/docs/actions) — the `defineAction` surface behind every hook on this page
+- [**Advanced**](/docs/client-advanced) — direct `application_state` access and syncing a raw `useQuery` with `useChangeVersion`
+- [**Real-Time Sync**](/docs/key-concepts#polling-sync) — how `useDbSync` keeps the UI current

From 097a1171f8bc2c67902244b86e36f39bccbae69e Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Fri, 7 Aug 2026 15:41:30 -0700
Subject: [PATCH 06/22] docs: add Agent Chat draft page

Covers askUserQuestion, useAgentChatGenerating, sendToAgentChat,
openAgentSettings, and dynamic suggestions: the client entry points
into agent chat. Ordered around a running "Draft Response" ticket
example, built up from askUserQuestion() through the full handler.
---
 .../core/docs/content/client-agent-chat.mdx   | 253 ++++++++++++++++++
 1 file changed, 253 insertions(+)
 create mode 100644 packages/core/docs/content/client-agent-chat.mdx

diff --git a/packages/core/docs/content/client-agent-chat.mdx b/packages/core/docs/content/client-agent-chat.mdx
new file mode 100644
index 0000000000..56a93f7569
--- /dev/null
+++ b/packages/core/docs/content/client-agent-chat.mdx
@@ -0,0 +1,253 @@
+---
+title: "Agent Chat"
+description: "Client-side entry points into agent chat: sendToAgentChat, openAgentSettings, askUserQuestion, dynamic suggestions, and useAgentChatGenerating."
+draft: true
+---
+
+# Agent Chat
+
+Your application's client can talk to the agent through a small set of client helpers. These cover sending a prompt, staging hidden context, asking the user a blocking question, and opening the agent panel.
+
+In the example below, a **Draft response** button prompts the agent to ask the user a question. Once the user answers, the agent goes about drafting a response keeping the current page context and the user's response in mind.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="Dispatch app screenshot showing the run history sidebar"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Dispatch's run history sidebar."
+/>
+
+## How it works
+
+By using the client helper methods provided by Agent-Native, your UI can prompt the agent to interact with the user in a variety of ways. The diagram below demonstrates how a "Draft response" button can be clicked by the user, which then prompts the agent to interact with the user before generating a response.
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="Sequence diagram titled 'who owns each step,' showing three lifelines: App Code, UI, and Agent. The user clicks 'draft response,' triggering askUserQuestion(). A note explains this renders inline in the agent panel. The user replies, then sendDraftRequest() is called on Agent, which calls draft-ticket-reply and returns a drafted reply to UI's composer."
+  align="full"
+  width={600}
+  caption="Sequence diagram visualizing a 'Draft response' button flow."
+/>
+
+The user experience is as follows:
+
+1. The user clicks the **Draft response** button, which causes the `askUserQuestion()` function to get called. The question is answered inline in the agent panel.
+
+1. The user picks **Offer a refund**, which causes `sendDraftRequest()` to send the prompt and ticket context to the agent.
+
+1. The agent calls the `draft-ticket-reply` [action](http://localhost:3000/docs/actions), and the drafted reply appears in the reply composer.
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "The question, its options, and how it should behave.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "The complete question. Clear, specific, ends with a question mark.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'Very short chip/heading, about 12 characters, e.g. `"Response"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2-4 distinct options. Each is `{ label, value?, description?, preview?, recommended? }`. `value` defaults to `label`.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description: 'Adds a free-text "Other" option the rep can type into.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Multi-select instead of single-select.",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description: "Application-state key the agent panel polls.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'The picked `value` (or `value[]` when `allowMultiple`), the rep\'s typed "Other" text, or `null` if they skip. Stays pending until they answer. Requires the agent panel to be mounted, which it is in every template.',
+  }}
+/>
+
+This function asks the user a multiple-choice question from app code, renders it inline in the agent panel, and awaits their answer. Use it when the UI needs one small decision with two to four options before it kicks off agent work, instead of building a custom modal.
+
+In the example below, a "Draft Response" button on a ticket page asks the rep how they'd like to respond before it sends anything to the agent:
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "A `[isGenerating, send]` tuple. `isGenerating` is `true` from the moment `send()` is called until the agent chat run reports it has stopped. `send(opts)` has the same signature as `sendToAgentChat()`, and returns the tab id it dispatched to.",
+  }}
+/>
+
+This React hook wraps `sendToAgentChat()` with loading state tracking.
+
+1. The first argument, `isGenerating`, turns true when you call it, then resets to false when the agent finishes generating.
+
+1. The second argument, `send()`, mirrors the `sendToAgentChat()` function.
+
+Combining this with the `askUserQuestion()` example above completes the button's handler:
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="Completing the Draft Response handler"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "Loading state + send, together",
+      note: "`useAgentChatGenerating()` returns the same tuple shape as a bare `sendToAgentChat()` call, but adds `isDrafting` so the button can disable itself while the request is in flight.",
+    },
+    {
+      lines: "10-17",
+      label: "Reuses the ask step",
+      note: "This is the exact `askUserQuestion()` call from the section above, now inside the button's own handler.",
+    },
+    {
+      lines: "18",
+      label: "Narrow before using the answer",
+      note: "The return type always allows for `string[]` from `allowMultiple`, so this check is required even though this call never sets it.",
+    },
+    {
+      lines: "20-25",
+      label: "Turn the pick into a sentence",
+      note: "Maps the selected value, or the rep's own typed text, into the phrase the prompt below reads naturally.",
+    },
+    {
+      lines: "27-32",
+      label: "Name the action and the intent",
+      note: "The message tells the agent exactly which action to call (`draft-ticket-reply`) and reminds it not to send the reply outright. `openSidebar: true` makes sure the drafted reply is visible even if the sidebar was closed.",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting drives the button",
+      note: "Disabled and re-labeled only while `sendDraftRequest()` is in flight. The button stays clickable while `askUserQuestion()` is waiting on the rep, since that happens before `sendDraftRequest()` is ever called.",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Send a message to the agent chat via `postMessage`. This is the lower-level primitive `useAgentChatGenerating()` above wraps, useful when a UI interaction doesn't need loading-state tracking of its own. Pass `context` for hidden model context, and `submit: true` to send immediately or `submit: false` to prefill a draft the user reviews first.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with hidden context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| Option        | Type       | Description                                             |
+| ------------- | ---------- | ------------------------------------------------------- |
+| `message`     | `string`   | The visible prompt sent to the chat                     |
+| `context`     | `string?`  | Hidden context appended (not shown in chat UI)          |
+| `submit`      | `boolean?` | true = auto-submit, false = prefill only                |
+| `newTab`      | `boolean?` | Create a separate chat thread for this prompt           |
+| `openSidebar` | `boolean?` | Set false to submit/prefill without opening the sidebar |
+
+Running this from inside an MCP App embed, or backgrounding the run without opening the sidebar, are both covered in [Advanced](/docs/client-advanced#background-send).
+
+## Dynamic Suggestions {#dynamic-suggestions}
+
+Before a conversation starts, `<AgentSidebar>`, `<AgentPanel>`, and `<AssistantChat>` show prompt chips on the empty chat. By default those aren't just your fixed `suggestions` list: the framework reads `navigation`, `selection`, `pending-selection-context`, and the current URL from application state, and merges in chips that match what's actually on screen.
+
+It does this with two checks. If something is selected, it adds generic chips like "Summarize this selection". Separately, it looks at `navigation` for field names common apps already use, such as `threadId`/`emailId` for an email thread or `dashboardId`/`chartId` for a chart, and adds chips tailored to that kind of screen, like "Draft a reply" for a thread or "Find anomalies in this data" for a chart. Whatever it comes up with is merged with your static `suggestions`, deduplicated, and capped at `max`.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+If the current screen doesn't match anything the heuristic recognizes and nothing is selected, it contributes no chips, and the empty chat falls back to your static `suggestions` alone. Set `dynamicSuggestions={false}` to keep only static chips. If your app's navigation shape doesn't match the built-in heuristic, or you want fully deterministic app-specific chips, see [Advanced](/docs/client-advanced#custom-suggestions).
+
+## openAgentSettings(section?) {#openagentsettings}
+
+Use `openAgentSettings()` when an app settings page or setup card should open
+the agent sidebar's Settings tab. Pass a section id such as `"llm"`, `"secrets"`,
+`"automations"`, `"voice"`, or `"limits"` to open a specific section.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Prefer this helper over dispatching `agent-panel:open-settings` directly.
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — where these helpers fit in `app/`
+- [**Data & Sync**](/docs/client-data) — the action hooks and `useDbSync` that keep the UI itself current
+- [**Drop-in Agent**](/docs/drop-in-agent) — mounting `<AgentSidebar>`/`<AgentPanel>` so these helpers have somewhere to render
+- [**Advanced**](/docs/client-advanced) — background sends, staged context-state APIs, custom suggestion chips, and the MCP App host bridge
+- [**Generative UI**](/docs/generative-ui) — building richer inline chat controls beyond `askUserQuestion`

From 3884ad35c4630aa23622b47d80d002e8d83ee9bd Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 09:56:10 -0700
Subject: [PATCH 07/22] docs: add Routing draft page

Covers file-based client routing in app/routes/ with React Router v8:
the file-to-URL table (including the trailing-underscore convention
for opting out of layout nesting), adding a page, dynamic params, and
navigation. Distinguishes client routes from the separate server-side
routing system, and points to the Routes page for that.
---
 packages/core/docs/content/client-routing.mdx | 122 ++++++++++++++++++
 1 file changed, 122 insertions(+)
 create mode 100644 packages/core/docs/content/client-routing.mdx

diff --git a/packages/core/docs/content/client-routing.mdx b/packages/core/docs/content/client-routing.mdx
new file mode 100644
index 0000000000..21379d84a3
--- /dev/null
+++ b/packages/core/docs/content/client-routing.mdx
@@ -0,0 +1,122 @@
+---
+title: "Routing"
+description: "File-based routing for agent-native apps with React Router v8: pages, dynamic params, and navigation."
+draft: true
+---
+
+# Routing
+
+Agent-native apps use **React Router v8** with file-based routing via `flatRoutes()` from `@react-router/fs-routes`. Every file in `app/routes/` becomes a URL. Templates use the dot-notation convention. Dots separate URL segments inside a single filename.
+
+This page covers client routes, the pages rendered in the browser from `app/routes/`. Server routes are a separate system: Nitro file routes under `server/routes/`, plus the framework's own `/_agent-native/*` endpoints. Those live on the [Routes](/docs/server-routes) page. The two don't share a directory, a naming convention, or a router, so a `server/routes/` file never becomes a page here and an `app/routes/` file never becomes a server endpoint.
+
+<Diagram id="doc-block-client-routing-1" title="File name → URL" summary="Each file in app/routes/ becomes a URL. Dots become slashes, and a $ segment becomes a dynamic param.">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## File-based routing {#file-based-routing}
+
+### File → URL mapping
+
+| File                       | URL                    | Notes                                                                     |
+| -------------------------- | ---------------------- | ------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | Index route                                                               |
+| `dashboard.tsx`            | `/dashboard`           | Simple page                                                               |
+| `extensions.$id.tsx`       | `/extensions/:id`      | Nests inside `extensions.tsx`'s `<Outlet/>`. `$` is a dynamic param       |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | Trailing `_` skips nesting under `dashboard.tsx`, so this is its own page |
+| `_app.tsx`                 | (no URL segment)       | Pathless layout. Prefix with `_`                                          |
+| `inbox/route.tsx`          | `/inbox`               | Folder form. `route.tsx` is the index                                     |
+
+Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a pathless layout route (no URL segment), or add a trailing `_` before a dot to opt a nested-looking path out of nesting under its parent's layout. Templates use `flatRoutes()`. The dot-notation file above is primary. The nested-folder form `inbox/route.tsx` also works.
+
+## Adding a new page {#adding-a-page}
+
+Create the file and export a default component:
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+That's it. React Router picks it up automatically, no registration needed.
+
+## Dynamic params {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+The trailing `_` before the dot keeps this page from nesting inside `dashboard.tsx`'s `<Outlet/>`, so it renders as its own full page at `/dashboard/:ticketId` instead of appearing inside the ticket queue's layout.
+
+## Navigation {#navigation}
+
+Use `<Link>` for client-side navigation and `useNavigate()` for programmatic navigation:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+Neither of these tells the agent what the user is looking at on their own. That's a separate concern, handled by `useAgentRouteState()` writing the current route into application state. See [Context Awareness](/docs/context-awareness).
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — where `app/routes/` fits among the rest of `app/` and `public/`
+- [**Data & Sync**](/docs/client-data) — reading and writing data from inside a route
+- [**Agent Chat**](/docs/client-agent-chat) — sending prompts and staging context from a route
+- [**Routes**](/docs/server-routes) — the separate server-routing system: file routes under `server/routes/` and the framework's `/_agent-native/` namespace
+- [**Context Awareness**](/docs/context-awareness) — how the agent learns the current route and selection

From e7df9223f8ac9d3b0dd0c5be9981feb1b7cabf80 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 09:59:18 -0700
Subject: [PATCH 08/22] docs: fix ordered list numbering in Agent Chat draft

---
 packages/core/docs/content/client-agent-chat.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/docs/content/client-agent-chat.mdx b/packages/core/docs/content/client-agent-chat.mdx
index 56a93f7569..7d5defba93 100644
--- a/packages/core/docs/content/client-agent-chat.mdx
+++ b/packages/core/docs/content/client-agent-chat.mdx
@@ -135,7 +135,7 @@ This React hook wraps `sendToAgentChat()` with loading state tracking.
 
 1. The first argument, `isGenerating`, turns true when you call it, then resets to false when the agent finishes generating.
 
-1. The second argument, `send()`, mirrors the `sendToAgentChat()` function.
+2. The second argument, `send()`, mirrors the `sendToAgentChat()` function.
 
 Combining this with the `askUserQuestion()` example above completes the button's handler:
 

From 832bfefcc3463e709572cf394852d8a110a80806 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 11:12:37 -0700
Subject: [PATCH 09/22] docs: split client-advanced into Advanced, Sync
 Internals, and Entry Points

Advanced was overloaded with unrelated concerns. Agent Chat Context
State moves into client-agent-chat.mdx (it's part of Agent Chat, just
deeper). useChangeVersion/useChangeVersions and the latency-model
explainer move to a new Sync Internals page, the real depth for this
previously existed only in the dev-facing real-time-sync skill, not
in any public doc. The SSR entry-point content moves to a new Entry
Points page.

Also trims the duplicated TAB_ID/jitter-prevention walkthrough on
Advanced down to a link to context-awareness's existing version, adds
the previously-undocumented readClientAppStateMany plus the failure
behavior of the application-state functions, and wires both new pages
into the nav (English labels only; other-locale nav labels are a
separate uncommitted follow-up).
---
 .../core/docs/content/client-advanced.mdx     | 193 ++++++++++++++++++
 .../core/docs/content/client-agent-chat.mdx   |  63 +++++-
 packages/core/docs/content/client-data.mdx    |   5 +-
 .../core/docs/content/client-entry-points.mdx |  28 +++
 .../core/docs/content/client-overview.mdx     |  44 ++--
 .../docs/content/client-sync-internals.mdx    | 125 ++++++++++++
 packages/core/docs/content/key-concepts.mdx   |   1 +
 packages/docs/app/components/docsNavItems.ts  |  49 +++++
 packages/docs/app/i18n/en-US.ts               |   6 +
 9 files changed, 491 insertions(+), 23 deletions(-)
 create mode 100644 packages/core/docs/content/client-advanced.mdx
 create mode 100644 packages/core/docs/content/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/client-sync-internals.mdx

diff --git a/packages/core/docs/content/client-advanced.mdx b/packages/core/docs/content/client-advanced.mdx
new file mode 100644
index 0000000000..6e8207f25d
--- /dev/null
+++ b/packages/core/docs/content/client-advanced.mdx
@@ -0,0 +1,193 @@
+---
+title: "Advanced"
+description: "Lower-level app/ primitives and escape hatches: direct application-state access, background chat sends, custom suggestion chips, and the MCP App host bridge."
+draft: true
+---
+
+# Advanced
+
+Overview, Data & Sync, Agent Chat, and Routing cover the typical case: the hooks and helpers most pages need. This page covers the lower-level primitives and narrower escape hatches underneath them. Most apps never touch these directly. Reach for one when you're building something more custom than the default hooks support, such as a custom selection sync or an embedded MCP App. For syncing a raw `useQuery` with a hand-rolled key, see [Sync Internals](/docs/client-sync-internals) instead.
+
+## Application State {#application-state}
+
+`application_state` is the SQL-backed key/value store the agent reads to know what the UI is currently looking at, including navigation, selection, and other focused-object context (see [Context Awareness](/docs/context-awareness)). `useAgentRouteState` and `useSemanticNavigationState` (also covered in Context Awareness) already wrap these for the common navigation case. Reach for the primitives below directly when you're syncing something they don't cover, such as a custom selection, or writing from outside a component's render.
+
+### readClientAppState {#read-client-app-state}
+
+Read the current value for a key. Resolves to whatever was last written for that key, or `null` if the key has never been written.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+Write a value for a key. Unlike `setClientAppState` below, it always writes, even if you pass `null` or `undefined`.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+The convenience wrapper most UI code should reach for: writes the value, or deletes the key when you pass `null`/`undefined`. Use this instead of `writeClientAppState` unless a call site genuinely needs "always write, never delete."
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+Remove a key entirely.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+Read several keys in one request. Returns `{ values, missing }`. `values` holds an entry for every key the server has a row for, including a key that was explicitly written as `null`. `missing` lists the keys that have never been written at all. This is how "never written" stays distinguishable from "written as null."
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+Requests over 100 keys are chunked automatically. `readClientAppState()` itself is built on this: calls issued in the same tick are coalesced into one batched request behind the scenes, so calling it many times in a single render pass costs one round trip, not one per call.
+
+### Options {#application-state-options}
+
+`signal` is accepted by all five functions above, to cancel an in-flight call. `requestSource` and `keepalive` only apply to the three write functions, since they don't mean anything for a read.
+
+| Option          | Type           | Applies to                                                         | Description                                                                                  |
+| --------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Tags the write with an id so a matching `useDbSync({ ignoreSource })` can skip refetching it |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Lets the request outlive page unload. Use for cleanup writes like clearing selection         |
+| `signal`        | `AbortSignal?` | all five functions                                                 | Cancels the request                                                                          |
+
+### Failure behavior {#failure-behavior}
+
+All five functions throw on a failed request, a non-2xx response, or a body that can't be parsed. The thrown `Error` carries a `.status` property when the server responded, so a caller can branch on the HTTP status if needed. Wrap a call in `try`/`catch`, or let it propagate to an error boundary, the same as any other network call.
+
+### What TAB_ID is {#tab-id}
+
+`requestSource` is commonly set to `TAB_ID`, a plain constant every template exports from `app/lib/tab-id.ts`: a short random string that stays the same for the life of a tab and differs between tabs. Pairing `requestSource: TAB_ID` on a write with `useDbSync({ ignoreSource: TAB_ID })` on the read side is how a tab avoids refetching its own write while still reacting to everyone else. See [Context Awareness](/docs/context-awareness#jitter-prevention) for the full walkthrough.
+
+## sendToAgentChat: Background Sends {#background-send}
+
+Use `background: true` when a UI action should kick off real agent work without
+opening or focusing the sidebar. This still creates a normal chat thread/run,
+uses the agent's tools/actions/context, and keeps the work observable through
+the runs tray. It is not a raw one-shot model call.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` is intended to be paired with `newTab` so the hidden work does not
+overwrite the user's active conversation. Use the returned `tabId` if the UI
+needs to correlate follow-up status or deep-link into the run later.
+
+A few more `AgentChatMessage` options exist beyond the ones covered in [Agent Chat](/docs/client-agent-chat#agentchatmessage), mostly for embedded or downstream-integration cases:
+
+| Option                | Type        | Description                                                                |
+| --------------------- | ----------- | -------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | With `newTab`, run without focusing the tab and show the run in `RunsTray` |
+| `projectSlug`         | `string?`   | Optional project slug for structured context                               |
+| `preset`              | `string?`   | Optional preset name for downstream consumers                              |
+| `referenceImagePaths` | `string[]?` | Optional reference image paths                                             |
+
+## MCP App Host Bridge {#mcp-app-host-bridge}
+
+Routes embedded as MCP Apps should be URL-first: load the current artifact from
+path/query params, render the real React route or a focused shared component,
+and use the host bridge only for host-owned behavior. `@agent-native/core/client`
+exports the helpers embedded routes call:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` reads the latest pushed host context snapshot.
+`useMcpAppHostContext()` subscribes React components to changes. The request
+helpers (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) return `false` outside an embedded MCP App frame, or
+`Promise<boolean>` inside a frame.
+
+`sendToAgentChat()` (see [Agent Chat](/docs/client-agent-chat#sendtoagentchat)) uses the same bridge for auto-submitted prompts from embedded routes. Inside an MCP App embed created with `embedApp()`, auto-submitted messages (`submit` omitted or `true`) are forwarded to the bridge, which asks the containing host to add hidden context and send the visible user turn. `context` stays model-visible without being posted as user-facing chat. `submit: false` keeps the local prefill/review behavior because MCP Apps do not define a standard draft-prefill API. Internally this is the submitted-chat path sometimes surfaced as `agentNative.submitChat`. App code should still call `sendToAgentChat()` rather than posting that event directly.
+
+The bridge itself, the `ui/*` JSON-RPC messages, the `agentNative.mcpHost.*`
+wrapper relay, transplant vs. controlled-frame rendering, host context, and
+display-mode requests, is owned by
+[External Agents](/docs/external-agents#mcp-app-bridge). See [MCP Apps](/docs/mcp-apps) for the full protocol.
+
+## Custom Suggestion Chips {#custom-suggestions}
+
+`<AgentSidebar>`'s `dynamicSuggestions` (see [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) already merges static `suggestions` with the framework's own context-aware heuristic. Pass `getSuggestions` instead when an app wants deterministic, domain-specific chips computed from the same `application_state` context rather than the framework's default heuristic.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` receives the same `navigation`/`selection`/`pending-selection-context` snapshot the built-in heuristic reads, so a custom implementation can react to exactly the state the default one does, just with app-specific rules instead of generic ones.
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout these primitives live in
+- [**Data & Sync**](/docs/client-data) — the default action hooks and `useDbSync` most pages should use instead
+- [**Sync Internals**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` and the two latency paths a refetch can take
+- [**Agent Chat**](/docs/client-agent-chat) — the default `sendToAgentChat`/`askUserQuestion` helpers most UI should use instead, and the staged agent chat context-state APIs
+- [**Entry Points**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` and SSR streaming customization
+- [**Context Awareness**](/docs/context-awareness) — the `navigation`/`selection` semantics built on `application_state`, and the `TAB_ID`/jitter-prevention walkthrough
+- [**Generative UI**](/docs/generative-ui) — richer inline chat controls beyond `askUserQuestion`
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — the full MCP App host bridge internals
diff --git a/packages/core/docs/content/client-agent-chat.mdx b/packages/core/docs/content/client-agent-chat.mdx
index 7d5defba93..ab594d059e 100644
--- a/packages/core/docs/content/client-agent-chat.mdx
+++ b/packages/core/docs/content/client-agent-chat.mdx
@@ -1,6 +1,6 @@
 ---
 title: "Agent Chat"
-description: "Client-side entry points into agent chat: sendToAgentChat, openAgentSettings, askUserQuestion, dynamic suggestions, and useAgentChatGenerating."
+description: "Client-side entry points into agent chat: sendToAgentChat, openAgentSettings, askUserQuestion, dynamic suggestions, useAgentChatGenerating, and staged agent chat context state."
 draft: true
 ---
 
@@ -244,10 +244,69 @@ openAgentSettings("secrets");
 
 Prefer this helper over dispatching `agent-panel:open-settings` directly.
 
+## Agent Chat Context State {#agent-chat-context-state}
+
+The context-state APIs are optional plumbing for UI that needs two-way sync with staged context chips: rendering the current staged items outside the composer, reflecting whether an item is already attached, or providing explicit remove/clear controls.
+
+Do not reach for these helpers for simple "send this to the agent" or "prefill this draft for review" flows. Use [`sendToAgentChat()`](#sendtoagentchat) with `context` and `submit` for those.
+
+| API                               | Use when                                                               |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `useAgentChatContext()`           | A React component needs the live staged context list                   |
+| `setAgentChatContextItem(item)`   | Imperative code should stage or replace one keyed context item         |
+| `listAgentChatContext()`          | Non-React code needs a one-time snapshot of staged context             |
+| `removeAgentChatContextItem(key)` | UI should remove one staged context item by its stable `key`           |
+| `clearAgentChatContext()`         | UI should clear all staged context, such as after a view or mode reset |
+| `refreshAgentChatContext()`       | Imperative code should re-read the latest persisted context snapshot   |
+
+`useAgentChatContext()` returns `{ items, set, remove, clear, refresh }`.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` is for imperative code that only needs to inspect the current staged items once. `clearAgentChatContext()` is intentionally broad. Use `removeAgentChatContextItem(key)` when only one selection changed.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| Option        | Type       | Description                                            |
+| ------------- | ---------- | ------------------------------------------------------ |
+| `key`         | `string`   | Stable identifier used to replace an existing nugget   |
+| `title`       | `string`   | Short label shown in the composer chip                 |
+| `context`     | `string`   | Hidden context included with the next submitted prompt |
+| `openSidebar` | `boolean?` | Defaults to true. Pass false to stage context silently |
+
 ## What's next
 
 - [**Overview**](/docs/client-overview) — where these helpers fit in `app/`
 - [**Data & Sync**](/docs/client-data) — the action hooks and `useDbSync` that keep the UI itself current
 - [**Drop-in Agent**](/docs/drop-in-agent) — mounting `<AgentSidebar>`/`<AgentPanel>` so these helpers have somewhere to render
-- [**Advanced**](/docs/client-advanced) — background sends, staged context-state APIs, custom suggestion chips, and the MCP App host bridge
+- [**Advanced**](/docs/client-advanced) — background sends, custom suggestion chips, and the MCP App host bridge
 - [**Generative UI**](/docs/generative-ui) — building richer inline chat controls beyond `askUserQuestion`
diff --git a/packages/core/docs/content/client-data.mdx b/packages/core/docs/content/client-data.mdx
index f59e39632a..c7395d1057 100644
--- a/packages/core/docs/content/client-data.mdx
+++ b/packages/core/docs/content/client-data.mdx
@@ -237,12 +237,13 @@ function App() {
 | `ignoreSource`     | `string?`          | Per-tab request source to ignore so a tab does not refetch from its own writes                                                                               |
 | `onEvent`          | `(data) => void`   | Optional callback when SSE/polling receives a change event                                                                                                   |
 
-For normal CRUD, prefer `useActionQuery()` and `useActionMutation()`. Mutating actions emit `source: "action"`, so those hooks refetch right away. Changes from the agent, a webhook, or another tab arrive through `useDbSync()` instead, over SSE or the polling fallback. If a raw `useQuery()` call needs to sync on a custom key, or you need to write to `application_state` directly, see [Advanced](/docs/client-advanced).
+For normal CRUD, prefer `useActionQuery()` and `useActionMutation()`. Mutating actions emit `source: "action"`, so those hooks refetch right away. Changes from the agent, a webhook, or another tab arrive through `useDbSync()` instead, over SSE or the polling fallback. If a raw `useQuery()` call needs to sync on a custom key, see [Sync Internals](/docs/client-sync-internals). If you need to write to `application_state` directly, see [Advanced](/docs/client-advanced).
 
 ## What's next
 
 - [**Overview**](/docs/client-overview) — the `app/` and `public/` directory layout this page's hooks live in
 - [**Agent Chat**](/docs/client-agent-chat) — sending prompts and staging context for the agent
 - [**Actions**](/docs/actions) — the `defineAction` surface behind every hook on this page
-- [**Advanced**](/docs/client-advanced) — direct `application_state` access and syncing a raw `useQuery` with `useChangeVersion`
+- [**Advanced**](/docs/client-advanced) — direct `application_state` access
+- [**Sync Internals**](/docs/client-sync-internals) — syncing a raw `useQuery` with `useChangeVersion`
 - [**Real-Time Sync**](/docs/key-concepts#polling-sync) — how `useDbSync` keeps the UI current
diff --git a/packages/core/docs/content/client-entry-points.mdx b/packages/core/docs/content/client-entry-points.mdx
new file mode 100644
index 0000000000..051b35a4d7
--- /dev/null
+++ b/packages/core/docs/content/client-entry-points.mdx
@@ -0,0 +1,28 @@
+---
+title: "Entry Points"
+description: "app/entry.client.tsx and app/entry.server.tsx: the thin hydration and SSR bootstrap wrappers, and when to customize streaming behavior."
+draft: true
+---
+
+# Entry Points
+
+`app/entry.client.tsx` hydrates the server-rendered HTML in the browser, and `app/entry.server.tsx` renders that HTML on the server. Both are thin wrappers generated by React Router. You rarely need to edit them.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+Reach for these only for advanced SSR customization, for example changing streaming behavior. Ordinary pages, layout, and data don't need changes here. See [Routing](/docs/routing) for adding pages instead.
+
+## What's next
+
+- [**Overview**](/docs/client-overview) — where these files sit in `app/`
+- [**Routing**](/docs/routing) — adding pages, the normal way to extend `app/`
+- [**Advanced**](/docs/client-advanced) — the other lower-level client primitives and escape hatches
diff --git a/packages/core/docs/content/client-overview.mdx b/packages/core/docs/content/client-overview.mdx
index baa289a67a..392111b667 100644
--- a/packages/core/docs/content/client-overview.mdx
+++ b/packages/core/docs/content/client-overview.mdx
@@ -97,26 +97,28 @@ Browser requests, the agent loop, and external API clients all resolve to the sa
 
 This page covers the directories you build in and the pieces of the browser runtime nothing else documents (`root.tsx`, `public/`). The React hooks that connect your components to actions and to the agent live on their own focused pages:
 
-| Page | What it covers |
-| --- | --- |
-| **[Data & Sync](/docs/client-data)** | `useActionQuery`, `useActionMutation`, `callAction`, and `useDbSync` |
-| **[Agent Chat](/docs/client-agent-chat)** | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, and dynamic suggestions |
-| **[Advanced](/docs/client-advanced)** | Direct `application_state` access, `useChangeVersion`, agent chat context state, the MCP App host bridge, and the SSR entry points |
+| Page                                              | What it covers                                                                                                      |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| **[Data & Sync](/docs/client-data)**              | `useActionQuery`, `useActionMutation`, `callAction`, and `useDbSync`                                                |
+| **[Agent Chat](/docs/client-agent-chat)**         | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, dynamic suggestions, and staged agent chat context state |
+| **[Advanced](/docs/client-advanced)**             | Direct `application_state` access, background chat sends, custom suggestion chips, and the MCP App host bridge      |
+| **[Sync Internals](/docs/client-sync-internals)** | `useChangeVersion`/`useChangeVersions` for syncing a raw `useQuery`                                                 |
+| **[Entry Points](/docs/client-entry-points)**     | `app/entry.client.tsx`/`app/entry.server.tsx` and SSR customization                                                 |
 
 ## What's in app/ and public/ {#project-directories}
 
-| Path | What it covers |
-| --- | --- |
-| **`app/root.tsx`** | The HTML shell and provider stack — see [The Browser Shell](#app-shell) below |
-| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration and SSR bootstrap — see [Advanced](/docs/client-advanced#entry-points) |
-| **`app/routes.ts` + `app/routes/`** | File-based pages and navigation — see [Routing](/docs/routing) |
-| **`app/components/`** | Your UI: shadcn-style primitives plus app-specific components — see [shadcn/ui](/docs/shadcn-ui) |
-| **`app/hooks/`** | Data, sync, and agent-chat hooks — see [Data & Sync](/docs/client-data) and [Agent Chat](/docs/client-agent-chat) |
-| **`app/lib/`** | Shared client utilities (app config, tab id, `cn`) — see [Utilities](#utilities) below |
-| **`app/design-system.ts`** | Optional custom design system adapter — see [Custom Design Systems](/docs/custom-design-system) |
-| **`app/i18n/`** | Localized UI copy catalogs — see [Internationalization](/docs/internationalization) |
-| **`app/global.css`** | Base styles and the Tailwind entry point |
-| **`public/`** | Static assets served as-is — see [Static Assets](#public-directory) below |
+| Path                                                | What it covers                                                                                                    |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | The HTML shell and provider stack — see [The Browser Shell](#app-shell) below                                     |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration and SSR bootstrap — see [Entry Points](/docs/client-entry-points)                                       |
+| **`app/routes.ts` + `app/routes/`**                 | File-based pages and navigation — see [Routing](/docs/routing)                                                    |
+| **`app/components/`**                               | Your UI: shadcn-style primitives plus app-specific components — see [shadcn/ui](/docs/shadcn-ui)                  |
+| **`app/hooks/`**                                    | Data, sync, and agent-chat hooks — see [Data & Sync](/docs/client-data) and [Agent Chat](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | Shared client utilities (app config, tab id, `cn`) — see [Utilities](#utilities) below                            |
+| **`app/design-system.ts`**                          | Optional custom design system adapter — see [Custom Design Systems](/docs/custom-design-system)                   |
+| **`app/i18n/`**                                     | Localized UI copy catalogs — see [Internationalization](/docs/internationalization)                               |
+| **`app/global.css`**                                | Base styles and the Tailwind entry point                                                                          |
+| **`public/`**                                       | Static assets served as-is — see [Static Assets](#public-directory) below                                         |
 
 ## The Browser Shell: root.tsx and AppProviders {#app-shell}
 
@@ -169,7 +171,9 @@ public/
   "name": "My App",
   "short_name": "My App",
   "theme_color": "#18181B",
-  "icons": [{ "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }]
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
 }
 ```
 
@@ -193,7 +197,9 @@ import { cn } from "@agent-native/toolkit/utils";
 
 - [**Data & Sync**](/docs/client-data) — action hooks and `useDbSync`
 - [**Agent Chat**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion`, and dynamic suggestions
-- [**Advanced**](/docs/client-advanced) — application state, custom query keys, and the MCP App host bridge
+- [**Advanced**](/docs/client-advanced) — application state, background chat sends, and the MCP App host bridge
+- [**Sync Internals**](/docs/client-sync-internals) — `useChangeVersion` for syncing a raw `useQuery`
+- [**Entry Points**](/docs/client-entry-points) — SSR bootstrap customization
 - [**Routing**](/docs/routing) — file-based pages, dynamic params, and navigation
 - [**Actions**](/docs/actions) — the `defineAction` surface behind every data hook
 - [**Custom Design Systems**](/docs/custom-design-system) — swapping in your own component library via `app/design-system.ts`
diff --git a/packages/core/docs/content/client-sync-internals.mdx b/packages/core/docs/content/client-sync-internals.mdx
new file mode 100644
index 0000000000..654e4d9ff3
--- /dev/null
+++ b/packages/core/docs/content/client-sync-internals.mdx
@@ -0,0 +1,125 @@
+---
+title: "Sync Internals"
+description: "The change-version mechanism behind useDbSync: useChangeVersion/useChangeVersions for syncing a raw useQuery, and the two latency paths a refetch can take."
+draft: true
+---
+
+# Sync Internals
+
+[Live Sync](/docs/key-concepts#polling-sync) covers the mental model: an agent write becomes a change event, `useDbSync()` picks it up, and affected queries refetch. This page covers the mechanism underneath that most apps never touch directly: the change-version counters `useDbSync()` bumps, and how to fold them into a raw `useQuery()` call that isn't going through `useActionQuery()`.
+
+`useActionQuery()` already refetches automatically when a mutating action completes (see [Data & Sync](/docs/client-data#fetching-mutating)). Reach for `useChangeVersion()`/`useChangeVersions()` only when you're syncing a raw `useQuery()` call outside that path, such as a low-level client helper reading integration status.
+
+## How change versions work {#how-it-works}
+
+When a server-side database mutation occurs, the server records a change event tagged with a `source` key. `useDbSync()` receives that event and bumps a local counter for that source. Folding the counter into a React Query key makes the query refetch automatically whenever the backend reports new activity for that source.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description: 'The change-event source to watch, e.g. `"dashboards"`.',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description:
+      "A counter that increments whenever the given source is mutated.",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "Multiple change-event sources to watch at once.",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "The sum of the version counters for every given source.",
+  }}
+/>
+
+In the example below, a raw `useQuery()` call reads a dashboard directly, folding the `"dashboards"` source's version counter into its query key so it refetches whenever that source changes:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` keeps the previous data on screen during the refetch, so the view doesn't flicker to a loading state.
+
+## Two paths to a refetch {#latency-models}
+
+A mutation reaches the UI one of two ways, and they have different latency.
+
+A local mutation, one your own `useActionMutation()` call just made, fires a `source: "action"` event as soon as it succeeds. Every query depending on that action refetches immediately. There's no round-trip delay, since the tab that made the write already knows about it.
+
+A remote mutation, from the agent, a webhook, another tab, or another user, has to reach this tab first. `useDbSync()` picks it up over SSE almost immediately, or over the polling fallback within about two seconds if SSE isn't available. Only once that event arrives does the relevant version counter bump and the query refetch in the background.
+
+<Diagram id="doc-block-client-sync-internals-3" title="Two paths to a refetch" summary="A local mutation invalidates its own caches instantly. A remote write reaches this tab over SSE, or the polling tick as a fallback.">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">This tab</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >fires source: "action" on success &rarr; instant local refetch</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">Agent · webhook · other tab</span
+      ><strong>Remote write</strong
+      ><small class="diagram-muted"
+        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
+        &rarr; background refetch</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## What's next
+
+- [**Live Sync**](/docs/key-concepts#polling-sync) — the conceptual mental model this page goes underneath
+- [**Data & Sync**](/docs/client-data) — `useActionQuery`/`useDbSync`, which most pages should use instead of these primitives
+- [**Advanced**](/docs/client-advanced) — the other lower-level client primitives and escape hatches
diff --git a/packages/core/docs/content/key-concepts.mdx b/packages/core/docs/content/key-concepts.mdx
index ddc5380d28..9894c1fde8 100644
--- a/packages/core/docs/content/key-concepts.mdx
+++ b/packages/core/docs/content/key-concepts.mdx
@@ -459,6 +459,7 @@ That's the "and everything else" you'd otherwise be gluing together yourself.
 
 - [**What Is Agent-Native?**](/docs/what-is-agent-native) — the vision and philosophy behind these rules
 - [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, and navigate commands in depth
+- [**Sync Internals**](/docs/client-sync-internals) — the change-version mechanism behind live sync, for syncing a raw `useQuery`
 - [**Skills Guide**](/docs/skills-guide) — framework skills, domain skills, and creating custom skills
 - [**Native Chat UI**](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture
 - [**Agent Surfaces**](/docs/agent-surfaces) — chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths
diff --git a/packages/docs/app/components/docsNavItems.ts b/packages/docs/app/components/docsNavItems.ts
index acfba01af2..6e1497e9d8 100644
--- a/packages/docs/app/components/docsNavItems.ts
+++ b/packages/docs/app/components/docsNavItems.ts
@@ -117,6 +117,55 @@ const NAV_SECTION_CONFIG: NavSectionConfig[] = [
         ],
       },
       { id: "client", labelKey: "client", slug: "client" },
+      {
+        id: "client-section",
+        labelKey: "client",
+        draft: true,
+        children: [
+          {
+            id: "client-overview",
+            labelKey: "clientOverview",
+            slug: "client-overview",
+            draft: true,
+          },
+          {
+            id: "client-data",
+            labelKey: "clientDataSync",
+            slug: "client-data",
+            draft: true,
+          },
+          {
+            id: "client-agent-chat",
+            labelKey: "clientAgentChat",
+            slug: "client-agent-chat",
+            draft: true,
+          },
+          {
+            id: "client-routing",
+            labelKey: "routing",
+            slug: "client-routing",
+            draft: true,
+          },
+          {
+            id: "client-advanced",
+            labelKey: "clientAdvanced",
+            slug: "client-advanced",
+            draft: true,
+          },
+          {
+            id: "client-sync-internals",
+            labelKey: "clientSyncInternals",
+            slug: "client-sync-internals",
+            draft: true,
+          },
+          {
+            id: "client-entry-points",
+            labelKey: "clientEntryPoints",
+            slug: "client-entry-points",
+            draft: true,
+          },
+        ],
+      },
       { id: "routing", labelKey: "routing", slug: "routing" },
       { id: "actions", labelKey: "actions", slug: "actions" },
       {
diff --git a/packages/docs/app/i18n/en-US.ts b/packages/docs/app/i18n/en-US.ts
index 29c8e479ed..07e43f9503 100644
--- a/packages/docs/app/i18n/en-US.ts
+++ b/packages/docs/app/i18n/en-US.ts
@@ -1517,6 +1517,12 @@ const enUS = {
     serverPlugins: "Plugins",
     serverRoutes: "Routes",
     client: "Client",
+    clientOverview: "Overview",
+    clientDataSync: "Data & Sync",
+    clientAgentChat: "Agent Chat",
+    clientAdvanced: "Advanced",
+    clientSyncInternals: "Sync Internals",
+    clientEntryPoints: "Entry Points",
     routing: "Routing",
     actions: "Actions",
     humanApproval: "Human Approval",

From 51cdac33cc84ea72ac47d0a3a99febafcd2f26a3 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 13:57:52 -0700
Subject: [PATCH 10/22] docs: add Signature components to Data & Sync

Replaces the hand-written argument bullet lists for useActionQuery,
useActionMutation, and callAction, and the full options table for
useDbSync, with Signature blocks. Folds each hook's trailing behavior
paragraph into its Signature's returns description instead of stating
it twice.

Also documents two real useDbSync options that existed in source but
weren't covered anywhere: actionInvalidatePredicate and
suppressActionInvalidationFor.
---
 packages/core/docs/content/client-data.mdx | 249 ++++++++++++++++++---
 1 file changed, 216 insertions(+), 33 deletions(-)

diff --git a/packages/core/docs/content/client-data.mdx b/packages/core/docs/content/client-data.mdx
index c7395d1057..0ccd6b1663 100644
--- a/packages/core/docs/content/client-data.mdx
+++ b/packages/core/docs/content/client-data.mdx
@@ -105,12 +105,38 @@ There are two action hooks you are most likely to use: `useActionQuery()` and `u
 
 #### useActionQuery {#use-action-query}
 
-This hook is intended to be used for read-only actions. It is a thin wrapper around the [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) function. `useActionQuery()` accepts three arguments:
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "The action's registered name.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "The action's input, typed from its `defineAction()` schema.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "Everything from the [useQuery options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) except `queryKey` and `queryFn`, which the hook sets itself.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      'Cached under `["action", name, params]`. Refetches automatically whenever a mutating action completes, with no manual invalidation needed.',
+  }}
+/>
 
-- **actionName**: the action's registered name.
-- **params**: the action's input, typed from its `defineAction()` schema.
-- **options**: everything from the [useQuery options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) except `queryKey` and `queryFn`, which the hook
-  sets itself.
+This hook is intended to be used for read-only actions. It is a thin wrapper around the [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) function.
 
 In the example below, the `list-tickets` action is called. This is similar to making a GET request for all tickets.
 
@@ -132,14 +158,49 @@ const { data, isLoading } = useActionQuery(
 );
 ```
 
-Results are cached under `["action", name, params]` and refetch automatically whenever a mutating action completes, with no manual invalidation needed.
-
 #### useActionMutation {#use-action-mutation}
 
-This hook is intended to be used for actions that change data, like creating, updating, or sending something. It is a thin wrapper around the [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) function. `useActionMutation()` accepts two arguments:
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "The action's registered name.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "Everything from the [useMutation options](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) except `mutationFn`, which the hook sets itself.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Overrides the default request method.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Opts out of the automatic cache refresh on success.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'On success, emits a change event with `source: "action"`, so every `useActionQuery()` reading affected data refetches automatically. No manual invalidation is needed.',
+  }}
+/>
 
-- **actionName**: the action's registered name.
-- **options**: everything from the [useMutation options](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) except `mutationFn`, which the hook sets itself. Two extra options are available. `method` overrides the default `POST` request. `skipActionQueryInvalidation` opts out of the automatic cache refresh described below.
+This hook is intended to be used for actions that change data, like creating, updating, or sending something. It is a thin wrapper around the [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) function.
 
 Unlike `useActionQuery()`, the action's input is not passed to the hook itself. It is passed to `mutate()` or `mutateAsync()` when you are ready to run the mutation.
 
@@ -165,15 +226,62 @@ const { mutate, isPending } = useActionMutation("send-ticket-reply", {
 mutate({ ticketId, body: draft });
 ```
 
-On success, the hook emits a change event with `source: "action"`, so every `useActionQuery` reading affected data refetches automatically. No manual invalidation is needed.
-
 ### callAction {#call-action}
 
-This function is for imperative one-off action calls outside of a React render flow, such as a plain event handler, a script, or any other non-React code path. It returns a promise directly instead of a hook result. `callAction()` accepts three arguments:
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "The action's registered name.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "The action's input, typed from its `defineAction()` schema.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "Everything below is optional.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Overrides the default request method.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "Cancels the request.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Overrides the default 60 second timeout, for actions that legitimately take longer.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "Unlike the hooks above, there is no cache and no automatic refetch. Pair it with a manual invalidation if other UI depends on the result.",
+  }}
+/>
 
-- **actionName**: the action's registered name.
-- **params**: the action's input, typed from its `defineAction()` schema.
-- **options**: `method` overrides the default `POST` request. `signal` accepts an `AbortSignal`. `timeoutMs` overrides the default 60 second timeout.
+This function is for imperative one-off action calls outside of a React render flow, such as a plain event handler, a script, or any other non-React code path. It returns a promise directly instead of a hook result.
 
 In the example below, the `update-ticket` action is called from a keyboard shortcut handler outside of React's render flow, assigning the ticket to a rep.
 
@@ -198,13 +306,102 @@ await callAction(
 );
 ```
 
-Unlike the hooks above, `callAction()` has no cache and no automatic refetch. Pair it with a manual invalidation if other UI depends on the result.
-
 Every `useActionQuery()`, `useActionMutation()`, and `callAction()` request is bounded by a 60 second timeout, and timeouts surface as errors instead of retrying silently. `useActionQuery()` also cancels superseded requests automatically, using React Query's abort signal.
 
 ## useDbSync {#usedbsync}
 
-This hook is intended to keep the UI in sync with database changes that happen outside of your own actions, like an agent write, a webhook, or a change made from another browser tab. It listens for changes over server-sent events, and falls back to polling when server-sent events are unavailable. `useDbSync()` accepts a single options argument. The full list of options is in the table below.
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "Every field is optional.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "React Query client used for cache invalidation.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "Poll endpoint URL.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description: "SSE endpoint URL. Pass `false` to use polling only.",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "Polling interval in ms.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description: "Fallback polling interval when SSE is unavailable.",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Pause polling when the browser tab is hidden. Hidden tabs keep SSE connected and poll no faster than every 10s while active, 60s once idle.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "Per-tab request source to ignore, so a tab does not refetch from its own writes.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "Optional callback when SSE or polling receives a change event.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "Filters the broad invalidation an action event triggers. Rarely needed. Use it to keep an expensive active query on explicit-refresh semantics while normal source-versioned queries still react through `useChangeVersion`.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "Action names whose sync events should not invalidate all action queries. Only for high-volume background actions that already perform their own narrow invalidation.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description: "Deprecated and ignored. Kept for old call sites.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+This hook is intended to keep the UI in sync with database changes that happen outside of your own actions, like an agent write, a webhook, or a change made from another browser tab. It listens for changes over server-sent events, and falls back to polling when server-sent events are unavailable.
 
 ```ts
 import { useDbSync } from "@agent-native/core/client/hooks";
@@ -223,20 +420,6 @@ function App() {
 }
 ```
 
-### Options {#usedbsync-options}
-
-| Option             | Type               | Description                                                                                                                                                  |
-| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `queryClient`      | `QueryClient?`     | React-query client for cache invalidation                                                                                                                    |
-| `queryKeys`        | `string[]?`        | Deprecated and ignored. Kept for old call sites                                                                                                              |
-| `pollUrl`          | `string?`          | Poll endpoint URL. Default: `"/_agent-native/poll"`                                                                                                          |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`. Pass `false` to use polling only                                                                       |
-| `interval`         | `number?`          | Polling interval in ms. Default: `2000`                                                                                                                      |
-| `fallbackInterval` | `number?`          | Fallback polling interval when SSE is unavailable. Default: `60000`                                                                                          |
-| `pauseWhenHidden`  | `boolean?`         | Pause polling when the browser tab is hidden. Default: `false`. Hidden tabs keep SSE connected and poll no faster than every 10s while active, 60s once idle |
-| `ignoreSource`     | `string?`          | Per-tab request source to ignore so a tab does not refetch from its own writes                                                                               |
-| `onEvent`          | `(data) => void`   | Optional callback when SSE/polling receives a change event                                                                                                   |
-
 For normal CRUD, prefer `useActionQuery()` and `useActionMutation()`. Mutating actions emit `source: "action"`, so those hooks refetch right away. Changes from the agent, a webhook, or another tab arrive through `useDbSync()` instead, over SSE or the polling fallback. If a raw `useQuery()` call needs to sync on a custom key, see [Sync Internals](/docs/client-sync-internals). If you need to write to `application_state` directly, see [Advanced](/docs/client-advanced).
 
 ## What's next

From 992b26f90009d6a94410d58da1d00bce2ba98573 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 14:25:07 -0700
Subject: [PATCH 11/22] docs: fix review feedback on client docs and docs
 components

Corrects sendToAgentChat's context-visibility claim, the useAgentChatGenerating
prefill caveat, writeClientAppState(undefined) behavior, useDbSync's reversed
fallbackInterval semantics, a localhost link, and a 404ing video asset on the
live docs-components page. Adds focus management to the media lightbox and
disambiguates the draft Client nav group from the legacy Client page.
---
 .../core/docs/content/client-advanced.mdx     |  2 +-
 .../core/docs/content/client-agent-chat.mdx   | 22 ++++++-----
 packages/core/docs/content/client-data.mdx    |  3 +-
 .../core/docs/content/client-overview.mdx     |  1 +
 .../core/docs/content/docs-components.mdx     | 18 +--------
 .../app/components/blocks/media-layout.tsx    | 39 ++++++++++++++++++-
 packages/docs/app/components/docsNavItems.ts  |  2 +-
 packages/docs/app/i18n/ar-SA.ts               |  7 ++++
 packages/docs/app/i18n/de-DE.ts               |  7 ++++
 packages/docs/app/i18n/en-US.ts               |  1 +
 packages/docs/app/i18n/es-ES.ts               |  7 ++++
 packages/docs/app/i18n/fr-FR.ts               |  7 ++++
 packages/docs/app/i18n/hi-IN.ts               |  7 ++++
 packages/docs/app/i18n/ja-JP.ts               |  7 ++++
 packages/docs/app/i18n/ko-KR.ts               |  7 ++++
 packages/docs/app/i18n/pt-BR.ts               |  7 ++++
 packages/docs/app/i18n/zh-CN.ts               |  7 ++++
 packages/docs/app/i18n/zh-TW.ts               |  7 ++++
 18 files changed, 126 insertions(+), 32 deletions(-)

diff --git a/packages/core/docs/content/client-advanced.mdx b/packages/core/docs/content/client-advanced.mdx
index 6e8207f25d..17c09d7541 100644
--- a/packages/core/docs/content/client-advanced.mdx
+++ b/packages/core/docs/content/client-advanced.mdx
@@ -29,7 +29,7 @@ const selection = await readClientAppState("selection");
 
 ### writeClientAppState {#write-client-app-state}
 
-Write a value for a key. Unlike `setClientAppState` below, it always writes, even if you pass `null` or `undefined`.
+Write a value for a key. Unlike `setClientAppState` below, it always writes, even if you pass `null`. Passing `undefined` throws instead, since `undefined` isn't valid JSON. Use `setClientAppState(key, undefined)` or `deleteClientAppState()` to clear a key.
 
 ```ts
 import { writeClientAppState } from "@agent-native/core/client/hooks";
diff --git a/packages/core/docs/content/client-agent-chat.mdx b/packages/core/docs/content/client-agent-chat.mdx
index ab594d059e..11621e3943 100644
--- a/packages/core/docs/content/client-agent-chat.mdx
+++ b/packages/core/docs/content/client-agent-chat.mdx
@@ -38,7 +38,7 @@ The user experience is as follows:
 
 1. The user picks **Offer a refund**, which causes `sendDraftRequest()` to send the prompt and ticket context to the agent.
 
-1. The agent calls the `draft-ticket-reply` [action](http://localhost:3000/docs/actions), and the drafted reply appears in the reply composer.
+1. The agent calls the `draft-ticket-reply` [action](/docs/actions), and the drafted reply appears in the reply composer.
 
 ## askUserQuestion(opts) {#ask-user-question}
 
@@ -137,6 +137,8 @@ This React hook wraps `sendToAgentChat()` with loading state tracking.
 
 2. The second argument, `send()`, mirrors the `sendToAgentChat()` function.
 
+`isGenerating` only resets once a run actually starts and reports it has stopped. A `submit: false` call prefills a draft without starting a run, so `isGenerating` stays `true` forever after one. Use this hook only for `submit: true` sends; call `sendToAgentChat()` directly for prefill-only ones.
+
 Combining this with the `askUserQuestion()` example above completes the button's handler:
 
 <AnnotatedCode
@@ -182,11 +184,11 @@ Combining this with the `askUserQuestion()` example above completes the button's
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-Send a message to the agent chat via `postMessage`. This is the lower-level primitive `useAgentChatGenerating()` above wraps, useful when a UI interaction doesn't need loading-state tracking of its own. Pass `context` for hidden model context, and `submit: true` to send immediately or `submit: false` to prefill a draft the user reviews first.
+Send a message to the agent chat via `postMessage`. This is the lower-level primitive `useAgentChatGenerating()` above wraps, useful when a UI interaction doesn't need loading-state tracking of its own. Pass `context` for extra detail the message alone doesn't carry. It gets appended to the same visible message, wrapped in `<context>` tags. It is not hidden from the user. Pass `submit: true` to send immediately, or `submit: false` to prefill a draft the user reviews first.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
+// Auto-submit a prompt with appended context
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -203,13 +205,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| Option        | Type       | Description                                             |
-| ------------- | ---------- | ------------------------------------------------------- |
-| `message`     | `string`   | The visible prompt sent to the chat                     |
-| `context`     | `string?`  | Hidden context appended (not shown in chat UI)          |
-| `submit`      | `boolean?` | true = auto-submit, false = prefill only                |
-| `newTab`      | `boolean?` | Create a separate chat thread for this prompt           |
-| `openSidebar` | `boolean?` | Set false to submit/prefill without opening the sidebar |
+| Option        | Type       | Description                                                                                         |
+| ------------- | ---------- | --------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | The prompt sent to the chat. `context`, if set, is appended to this same visible message            |
+| `context`     | `string?`  | Extra detail appended to the visible message, wrapped in `<context>` tags. Not hidden from the user |
+| `submit`      | `boolean?` | true = auto-submit, false = prefill only                                                            |
+| `newTab`      | `boolean?` | Create a separate chat thread for this prompt                                                       |
+| `openSidebar` | `boolean?` | Set false to submit/prefill without opening the sidebar                                             |
 
 Running this from inside an MCP App embed, or backgrounding the run without opening the sidebar, are both covered in [Advanced](/docs/client-advanced#background-send).
 
diff --git a/packages/core/docs/content/client-data.mdx b/packages/core/docs/content/client-data.mdx
index 0ccd6b1663..4c6b82ca09 100644
--- a/packages/core/docs/content/client-data.mdx
+++ b/packages/core/docs/content/client-data.mdx
@@ -351,7 +351,8 @@ Every `useActionQuery()`, `useActionMutation()`, and `callAction()` request is b
           type: "number",
           optional: true,
           default: "60000",
-          description: "Fallback polling interval when SSE is unavailable.",
+          description:
+            "Poll interval while SSE is connected, as a backup in case an event is missed. A disconnected tab polls at the faster `interval` (or a fixed idle cadence) instead.",
         },
         {
           name: "pauseWhenHidden",
diff --git a/packages/core/docs/content/client-overview.mdx b/packages/core/docs/content/client-overview.mdx
index 392111b667..8578a3f831 100644
--- a/packages/core/docs/content/client-overview.mdx
+++ b/packages/core/docs/content/client-overview.mdx
@@ -129,6 +129,7 @@ import {
   AppProviders,
   createAgentNativeQueryClient,
 } from "@agent-native/core/client/hooks";
+import { useState } from "react";
 import { Outlet } from "react-router";
 import { i18nCatalog } from "./i18n";
 
diff --git a/packages/core/docs/content/docs-components.mdx b/packages/core/docs/content/docs-components.mdx
index 16c0452c4a..42599af7e7 100644
--- a/packages/core/docs/content/docs-components.mdx
+++ b/packages/core/docs/content/docs-components.mdx
@@ -275,17 +275,7 @@ For a plain full-width image with no paired text, omit `align` (or set it to `"f
 
 ## Video
 
-<Video
-  src="/videos/product-tour.mp4"
-  alt="A short screen recording of creating a new action from the CLI"
-  align="right"
-  width={320}
-  caption="Creating an action from the CLI."
->
-
-Same shape as `Image`, aligned the other way this time. The video sits on the right, and this text sits on the left. `src` must be a direct video file, mp4 or webm. Third-party embed links like YouTube or Loom aren't supported, since that would need an `<iframe>`, which the docs system doesn't allow for security reasons.
-
-</Video>
+No sample video ships in this repo, so this section shows syntax only rather than a live-rendered example. Swap `src` for a real `.mp4`/`.webm` file under `public/` to see it rendered.
 
 ```mdx
 <Video
@@ -309,12 +299,6 @@ Pass `loop` to restart the video from the beginning once it ends. It's independe
 
 The same full-width form applies here too, omit `align` and the children for a plain full-width video:
 
-<Video
-  src="/videos/product-tour.mp4"
-  alt="A full walkthrough recording of building an action end to end"
-  caption="Building an action end to end."
-/>
-
 ```mdx
 <Video
   src="/videos/product-tour.mp4"
diff --git a/packages/docs/app/components/blocks/media-layout.tsx b/packages/docs/app/components/blocks/media-layout.tsx
index edb352764d..2d79a0cec8 100644
--- a/packages/docs/app/components/blocks/media-layout.tsx
+++ b/packages/docs/app/components/blocks/media-layout.tsx
@@ -1,15 +1,23 @@
 import type { BlockRenderContext } from "@agent-native/core/blocks";
 import { IconArrowsMaximize, IconX } from "@tabler/icons-react";
-import { useEffect, useState, type ReactNode } from "react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
 
 import type { MediaAlign } from "./media-shared";
 
+const FOCUSABLE_SELECTOR =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
 /**
  * Fixed-backdrop popup for `expandable` media. Mirrors core's
  * `DiagramLightbox` contract (Escape to close, click-the-backdrop to close,
  * top-right close button, body scroll locked while open) rather than
  * importing it, since that lives in `@agent-native/core`'s public blocks
  * surface and would need a changeset for what's a docs-site-only need.
+ *
+ * Unlike that reference, this one also manages focus: moves focus into the
+ * dialog on open, traps Tab within it while open, and restores focus to
+ * whatever triggered it (the expand button) on close, per the standard
+ * WAI-ARIA dialog pattern.
  */
 function MediaLightbox({
   children,
@@ -18,20 +26,46 @@ function MediaLightbox({
   children: ReactNode;
   onClose: () => void;
 }) {
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const closeButtonRef = useRef<HTMLButtonElement>(null);
+
   useEffect(() => {
+    const previouslyFocused = document.activeElement as HTMLElement | null;
+    closeButtonRef.current?.focus();
+
     const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === "Escape") onClose();
+      if (event.key === "Escape") {
+        onClose();
+        return;
+      }
+      if (event.key !== "Tab" || !dialogRef.current) return;
+      const focusable = Array.from(
+        dialogRef.current.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+      );
+      if (focusable.length === 0) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
     };
+
     document.addEventListener("keydown", onKeyDown);
     document.body.style.overflow = "hidden";
     return () => {
       document.removeEventListener("keydown", onKeyDown);
       document.body.style.overflow = "";
+      previouslyFocused?.focus();
     };
   }, [onClose]);
 
   return (
     <div
+      ref={dialogRef}
       role="dialog"
       aria-modal="true"
       aria-label="Media preview"
@@ -45,6 +79,7 @@ function MediaLightbox({
         {children}
       </div>
       <button
+        ref={closeButtonRef}
         type="button"
         onClick={onClose}
         aria-label="Close preview"
diff --git a/packages/docs/app/components/docsNavItems.ts b/packages/docs/app/components/docsNavItems.ts
index 6e1497e9d8..70210b1272 100644
--- a/packages/docs/app/components/docsNavItems.ts
+++ b/packages/docs/app/components/docsNavItems.ts
@@ -119,7 +119,7 @@ const NAV_SECTION_CONFIG: NavSectionConfig[] = [
       { id: "client", labelKey: "client", slug: "client" },
       {
         id: "client-section",
-        labelKey: "client",
+        labelKey: "clientNext",
         draft: true,
         children: [
           {
diff --git a/packages/docs/app/i18n/ar-SA.ts b/packages/docs/app/i18n/ar-SA.ts
index b8a6f2f927..d0cdb8255b 100644
--- a/packages/docs/app/i18n/ar-SA.ts
+++ b/packages/docs/app/i18n/ar-SA.ts
@@ -1515,6 +1515,13 @@ const arSA = {
     serverPlugins: "الإضافات",
     serverRoutes: "المسارات",
     client: "Client",
+    clientNext: "Client (جديد)",
+    clientOverview: "نظرة عامة",
+    clientDataSync: "البيانات والمزامنة",
+    clientAgentChat: "محادثة الوكيل",
+    clientAdvanced: "متقدم",
+    clientSyncInternals: "آليات المزامنة الداخلية",
+    clientEntryPoints: "نقاط الدخول",
     routing: "Routing",
     actions: "الإجراءات",
     humanApproval: "موافقة بشرية",
diff --git a/packages/docs/app/i18n/de-DE.ts b/packages/docs/app/i18n/de-DE.ts
index b9ea875945..767702ba6c 100644
--- a/packages/docs/app/i18n/de-DE.ts
+++ b/packages/docs/app/i18n/de-DE.ts
@@ -1527,6 +1527,13 @@ const deDE = {
     serverPlugins: "Plugins",
     serverRoutes: "Routen",
     client: "Client",
+    clientNext: "Client (neu)",
+    clientOverview: "Überblick",
+    clientDataSync: "Daten & Synchronisierung",
+    clientAgentChat: "Agent-Chat",
+    clientAdvanced: "Fortgeschritten",
+    clientSyncInternals: "Sync-Interna",
+    clientEntryPoints: "Einstiegspunkte",
     routing: "Routing",
     actions: "Aktionen",
     humanApproval: "Menschliche Freigabe",
diff --git a/packages/docs/app/i18n/en-US.ts b/packages/docs/app/i18n/en-US.ts
index 07e43f9503..2a77b6b21d 100644
--- a/packages/docs/app/i18n/en-US.ts
+++ b/packages/docs/app/i18n/en-US.ts
@@ -1517,6 +1517,7 @@ const enUS = {
     serverPlugins: "Plugins",
     serverRoutes: "Routes",
     client: "Client",
+    clientNext: "Client (new)",
     clientOverview: "Overview",
     clientDataSync: "Data & Sync",
     clientAgentChat: "Agent Chat",
diff --git a/packages/docs/app/i18n/es-ES.ts b/packages/docs/app/i18n/es-ES.ts
index 291b3c801c..535118ef69 100644
--- a/packages/docs/app/i18n/es-ES.ts
+++ b/packages/docs/app/i18n/es-ES.ts
@@ -1527,6 +1527,13 @@ const esES = {
     serverPlugins: "Plugins",
     serverRoutes: "Rutas",
     client: "Cliente",
+    clientNext: "Cliente (nuevo)",
+    clientOverview: "Resumen",
+    clientDataSync: "Datos y sincronización",
+    clientAgentChat: "Chat del Agent",
+    clientAdvanced: "Avanzado",
+    clientSyncInternals: "Sincronización interna",
+    clientEntryPoints: "Puntos de entrada",
     routing: "Rutas",
     actions: "Acciones",
     humanApproval: "Aprobación humana",
diff --git a/packages/docs/app/i18n/fr-FR.ts b/packages/docs/app/i18n/fr-FR.ts
index baa26ede31..10895e463c 100644
--- a/packages/docs/app/i18n/fr-FR.ts
+++ b/packages/docs/app/i18n/fr-FR.ts
@@ -1528,6 +1528,13 @@ const frFR = {
     serverPlugins: "Plugins",
     serverRoutes: "Routes",
     client: "Client",
+    clientNext: "Client (nouveau)",
+    clientOverview: "Vue d’ensemble",
+    clientDataSync: "Données et synchronisation",
+    clientAgentChat: "Chat de l’Agent",
+    clientAdvanced: "Avancé",
+    clientSyncInternals: "Synchronisation interne",
+    clientEntryPoints: "Points d'entrée",
     routing: "Routage",
     actions: "Opérations",
     humanApproval: "Validation humaine",
diff --git a/packages/docs/app/i18n/hi-IN.ts b/packages/docs/app/i18n/hi-IN.ts
index 71c7ab361c..4d2339eb9b 100644
--- a/packages/docs/app/i18n/hi-IN.ts
+++ b/packages/docs/app/i18n/hi-IN.ts
@@ -1517,6 +1517,13 @@ const hiIN = {
     serverPlugins: "प्लगइन्स",
     serverRoutes: "रूट्स",
     client: "Client",
+    clientNext: "Client (नया)",
+    clientOverview: "अवलोकन",
+    clientDataSync: "डेटा और सिंक",
+    clientAgentChat: "एजेंट चैट",
+    clientAdvanced: "उन्नत",
+    clientSyncInternals: "सिंक इंटरनल्स",
+    clientEntryPoints: "एंट्री पॉइंट्स",
     routing: "Routing",
     actions: "क्रियाएँ",
     humanApproval: "मानवीय अनुमोदन",
diff --git a/packages/docs/app/i18n/ja-JP.ts b/packages/docs/app/i18n/ja-JP.ts
index febd309031..c03b9e92a5 100644
--- a/packages/docs/app/i18n/ja-JP.ts
+++ b/packages/docs/app/i18n/ja-JP.ts
@@ -1524,6 +1524,13 @@ const jaJP = {
     serverPlugins: "プラグイン",
     serverRoutes: "ルート",
     client: "クライアント",
+    clientNext: "クライアント（新）",
+    clientOverview: "概要",
+    clientDataSync: "データと同期",
+    clientAgentChat: "Agent チャット",
+    clientAdvanced: "高度",
+    clientSyncInternals: "同期の内部",
+    clientEntryPoints: "エントリーポイント",
     routing: "ルーティング",
     actions: "アクション",
     humanApproval: "人による承認",
diff --git a/packages/docs/app/i18n/ko-KR.ts b/packages/docs/app/i18n/ko-KR.ts
index 11f65ee4c0..39a2f62281 100644
--- a/packages/docs/app/i18n/ko-KR.ts
+++ b/packages/docs/app/i18n/ko-KR.ts
@@ -1520,6 +1520,13 @@ const koKR = {
     serverPlugins: "플러그인",
     serverRoutes: "라우트",
     client: "클라이언트",
+    clientNext: "클라이언트 (신규)",
+    clientOverview: "개요",
+    clientDataSync: "데이터 및 동기화",
+    clientAgentChat: "Agent 채팅",
+    clientAdvanced: "고급",
+    clientSyncInternals: "동기화 내부",
+    clientEntryPoints: "엔트리 포인트",
     routing: "라우팅",
     actions: "작업",
     humanApproval: "사람 승인",
diff --git a/packages/docs/app/i18n/pt-BR.ts b/packages/docs/app/i18n/pt-BR.ts
index 7fe9f2c6bd..44459c133b 100644
--- a/packages/docs/app/i18n/pt-BR.ts
+++ b/packages/docs/app/i18n/pt-BR.ts
@@ -1523,6 +1523,13 @@ const ptBR = {
     serverPlugins: "Plugins",
     serverRoutes: "Rotas",
     client: "Cliente",
+    clientNext: "Cliente (novo)",
+    clientOverview: "Visão geral",
+    clientDataSync: "Dados e sincronização",
+    clientAgentChat: "Chat do Agent",
+    clientAdvanced: "Avançado",
+    clientSyncInternals: "Sincronização interna",
+    clientEntryPoints: "Pontos de entrada",
     routing: "Roteamento",
     actions: "Ações",
     humanApproval: "Aprovação humana",
diff --git a/packages/docs/app/i18n/zh-CN.ts b/packages/docs/app/i18n/zh-CN.ts
index d3d5153dfa..01bca76cbd 100644
--- a/packages/docs/app/i18n/zh-CN.ts
+++ b/packages/docs/app/i18n/zh-CN.ts
@@ -1499,6 +1499,13 @@ const zhCN = {
     serverPlugins: "插件",
     serverRoutes: "路由",
     client: "客户端",
+    clientNext: "客户端（新）",
+    clientOverview: "概览",
+    clientDataSync: "数据与同步",
+    clientAgentChat: "Agent 聊天",
+    clientAdvanced: "高级",
+    clientSyncInternals: "同步内部机制",
+    clientEntryPoints: "入口点",
     routing: "路由",
     actions: "行动",
     humanApproval: "人工审批",
diff --git a/packages/docs/app/i18n/zh-TW.ts b/packages/docs/app/i18n/zh-TW.ts
index 8d9c563053..e70f9914ce 100644
--- a/packages/docs/app/i18n/zh-TW.ts
+++ b/packages/docs/app/i18n/zh-TW.ts
@@ -1497,6 +1497,13 @@ const messages = {
     serverPlugins: "外掛",
     serverRoutes: "路由",
     client: "用戶端",
+    clientNext: "用戶端（新）",
+    clientOverview: "總覽",
+    clientDataSync: "資料與同步",
+    clientAgentChat: "Agent 聊天",
+    clientAdvanced: "進階",
+    clientSyncInternals: "同步內部機制",
+    clientEntryPoints: "入口點",
     routing: "路由",
     actions: "行動",
     humanApproval: "人工核准",

From 509cd86e474342047a9ab696f1727dfc915a9641 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 15:36:51 -0700
Subject: [PATCH 12/22] docs: un-draft Client section, remove legacy pages,
 translate into all locales

Removes the legacy monolithic client.mdx and standalone routing.mdx now that
their content lives in the un-drafted Client section (Overview, Data & Sync,
Agent Chat, Routing, Advanced, Sync Internals, Entry Points). Adds 301
redirects for both old slugs, drops the now-redundant nav entries, fixes every
dangling /docs/client and /docs/routing link across English and all 10
locales, and translates the 7 new Client pages into ar-SA, de-DE, es-ES,
fr-FR, hi-IN, ja-JP, ko-KR, pt-BR, zh-CN, and zh-TW.
---
 .../core/docs/content/client-advanced.mdx     |   1 -
 .../core/docs/content/client-agent-chat.mdx   |   1 -
 packages/core/docs/content/client-data.mdx    |   1 -
 .../core/docs/content/client-entry-points.mdx |   5 +-
 .../core/docs/content/client-overview.mdx     |   5 +-
 packages/core/docs/content/client-routing.mdx |   1 -
 .../docs/content/client-sync-internals.mdx    |   1 -
 packages/core/docs/content/client.mdx         | 486 ------------------
 .../core/docs/content/context-awareness.mdx   |   2 +-
 packages/core/docs/content/drop-in-agent.mdx  |   2 +-
 .../docs/content/internationalization.mdx     |   2 +-
 .../content/locales/ar-SA/client-advanced.mdx | 192 +++++++
 .../locales/ar-SA/client-agent-chat.mdx       | 312 +++++++++++
 .../content/locales/ar-SA/client-data.mdx     | 432 ++++++++++++++++
 .../locales/ar-SA/client-entry-points.mdx     |  27 +
 .../content/locales/ar-SA/client-overview.mdx | 206 ++++++++
 .../content/locales/ar-SA/client-routing.mdx  | 121 +++++
 .../locales/ar-SA/client-sync-internals.mdx   | 124 +++++
 .../docs/content/locales/ar-SA/client.mdx     | 471 -----------------
 .../content/locales/ar-SA/drop-in-agent.mdx   |   2 +-
 .../content/locales/ar-SA/notifications.mdx   |   2 +-
 .../docs/content/locales/ar-SA/progress.mdx   |   4 +-
 .../locales/ar-SA/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/ar-SA/routing.mdx    | 118 -----
 .../content/locales/de-DE/client-advanced.mdx | 191 +++++++
 .../locales/de-DE/client-agent-chat.mdx       | 315 ++++++++++++
 .../content/locales/de-DE/client-data.mdx     | 435 ++++++++++++++++
 .../locales/de-DE/client-entry-points.mdx     |  27 +
 .../content/locales/de-DE/client-overview.mdx | 208 ++++++++
 .../content/locales/de-DE/client-routing.mdx  | 121 +++++
 .../locales/de-DE/client-sync-internals.mdx   | 127 +++++
 .../docs/content/locales/de-DE/client.mdx     | 470 -----------------
 .../content/locales/de-DE/drop-in-agent.mdx   |   2 +-
 .../content/locales/de-DE/notifications.mdx   |   2 +-
 .../docs/content/locales/de-DE/progress.mdx   |   4 +-
 .../locales/de-DE/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/de-DE/routing.mdx    | 118 -----
 .../content/locales/es-ES/client-advanced.mdx | 193 +++++++
 .../locales/es-ES/client-agent-chat.mdx       | 317 ++++++++++++
 .../content/locales/es-ES/client-data.mdx     | 436 ++++++++++++++++
 .../locales/es-ES/client-entry-points.mdx     |  28 +
 .../content/locales/es-ES/client-overview.mdx | 206 ++++++++
 .../content/locales/es-ES/client-routing.mdx  | 122 +++++
 .../locales/es-ES/client-sync-internals.mdx   | 128 +++++
 .../docs/content/locales/es-ES/client.mdx     | 470 -----------------
 .../content/locales/es-ES/drop-in-agent.mdx   |   2 +-
 .../content/locales/es-ES/notifications.mdx   |   2 +-
 .../docs/content/locales/es-ES/progress.mdx   |   4 +-
 .../locales/es-ES/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/es-ES/routing.mdx    | 118 -----
 .../content/locales/fr-FR/client-advanced.mdx | 195 +++++++
 .../locales/fr-FR/client-agent-chat.mdx       | 317 ++++++++++++
 .../content/locales/fr-FR/client-data.mdx     | 436 ++++++++++++++++
 .../locales/fr-FR/client-entry-points.mdx     |  27 +
 .../content/locales/fr-FR/client-overview.mdx | 205 ++++++++
 .../content/locales/fr-FR/client-routing.mdx  | 121 +++++
 .../locales/fr-FR/client-sync-internals.mdx   | 127 +++++
 .../docs/content/locales/fr-FR/client.mdx     | 472 -----------------
 .../content/locales/fr-FR/drop-in-agent.mdx   |   2 +-
 .../content/locales/fr-FR/notifications.mdx   |   2 +-
 .../docs/content/locales/fr-FR/progress.mdx   |   4 +-
 .../locales/fr-FR/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/fr-FR/routing.mdx    | 118 -----
 .../content/locales/hi-IN/client-advanced.mdx | 192 +++++++
 .../locales/hi-IN/client-agent-chat.mdx       | 314 +++++++++++
 .../content/locales/hi-IN/client-data.mdx     | 435 ++++++++++++++++
 .../locales/hi-IN/client-entry-points.mdx     |  27 +
 .../content/locales/hi-IN/client-overview.mdx | 205 ++++++++
 .../content/locales/hi-IN/client-routing.mdx  | 121 +++++
 .../locales/hi-IN/client-sync-internals.mdx   | 124 +++++
 .../docs/content/locales/hi-IN/client.mdx     | 470 -----------------
 .../content/locales/hi-IN/drop-in-agent.mdx   |   2 +-
 .../content/locales/hi-IN/notifications.mdx   |   2 +-
 .../docs/content/locales/hi-IN/progress.mdx   |   4 +-
 .../locales/hi-IN/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/hi-IN/routing.mdx    | 118 -----
 .../content/locales/ja-JP/client-advanced.mdx | 178 +++++++
 .../locales/ja-JP/client-agent-chat.mdx       | 312 +++++++++++
 .../content/locales/ja-JP/client-data.mdx     | 435 ++++++++++++++++
 .../locales/ja-JP/client-entry-points.mdx     |  28 +
 .../content/locales/ja-JP/client-overview.mdx | 206 ++++++++
 .../content/locales/ja-JP/client-routing.mdx  | 122 +++++
 .../locales/ja-JP/client-sync-internals.mdx   | 125 +++++
 .../docs/content/locales/ja-JP/client.mdx     | 470 -----------------
 .../content/locales/ja-JP/drop-in-agent.mdx   |   2 +-
 .../content/locales/ja-JP/notifications.mdx   |   2 +-
 .../docs/content/locales/ja-JP/progress.mdx   |   4 +-
 .../locales/ja-JP/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/ja-JP/routing.mdx    | 118 -----
 .../content/locales/ko-KR/client-advanced.mdx | 210 ++++++++
 .../locales/ko-KR/client-agent-chat.mdx       | 315 ++++++++++++
 .../content/locales/ko-KR/client-data.mdx     | 434 ++++++++++++++++
 .../locales/ko-KR/client-entry-points.mdx     |  27 +
 .../content/locales/ko-KR/client-overview.mdx | 206 ++++++++
 .../content/locales/ko-KR/client-routing.mdx  | 121 +++++
 .../locales/ko-KR/client-sync-internals.mdx   | 133 +++++
 .../docs/content/locales/ko-KR/client.mdx     | 470 -----------------
 .../content/locales/ko-KR/drop-in-agent.mdx   |   2 +-
 .../content/locales/ko-KR/notifications.mdx   |   2 +-
 .../docs/content/locales/ko-KR/progress.mdx   |   4 +-
 .../locales/ko-KR/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/ko-KR/routing.mdx    | 118 -----
 .../content/locales/pt-BR/client-advanced.mdx | 192 +++++++
 .../locales/pt-BR/client-agent-chat.mdx       | 315 ++++++++++++
 .../content/locales/pt-BR/client-data.mdx     | 434 ++++++++++++++++
 .../locales/pt-BR/client-entry-points.mdx     |  27 +
 .../content/locales/pt-BR/client-overview.mdx | 206 ++++++++
 .../content/locales/pt-BR/client-routing.mdx  | 121 +++++
 .../locales/pt-BR/client-sync-internals.mdx   | 127 +++++
 .../docs/content/locales/pt-BR/client.mdx     | 472 -----------------
 .../content/locales/pt-BR/drop-in-agent.mdx   |   2 +-
 .../content/locales/pt-BR/notifications.mdx   |   2 +-
 .../docs/content/locales/pt-BR/progress.mdx   |   4 +-
 .../locales/pt-BR/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/pt-BR/routing.mdx    | 118 -----
 .../content/locales/zh-CN/client-advanced.mdx | 177 +++++++
 .../locales/zh-CN/client-agent-chat.mdx       | 310 +++++++++++
 .../content/locales/zh-CN/client-data.mdx     | 429 ++++++++++++++++
 .../locales/zh-CN/client-entry-points.mdx     |  27 +
 .../content/locales/zh-CN/client-overview.mdx | 206 ++++++++
 .../content/locales/zh-CN/client-routing.mdx  | 121 +++++
 .../locales/zh-CN/client-sync-internals.mdx   | 123 +++++
 .../docs/content/locales/zh-CN/client.mdx     | 470 -----------------
 .../content/locales/zh-CN/drop-in-agent.mdx   |   2 +-
 .../content/locales/zh-CN/notifications.mdx   |   2 +-
 .../docs/content/locales/zh-CN/progress.mdx   |   4 +-
 .../locales/zh-CN/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/zh-CN/routing.mdx    | 116 -----
 .../content/locales/zh-TW/client-advanced.mdx | 192 +++++++
 .../locales/zh-TW/client-agent-chat.mdx       | 310 +++++++++++
 .../content/locales/zh-TW/client-data.mdx     | 429 ++++++++++++++++
 .../locales/zh-TW/client-entry-points.mdx     |  27 +
 .../content/locales/zh-TW/client-overview.mdx | 206 ++++++++
 .../content/locales/zh-TW/client-routing.mdx  | 121 +++++
 .../locales/zh-TW/client-sync-internals.mdx   | 123 +++++
 .../docs/content/locales/zh-TW/client.mdx     | 470 -----------------
 .../content/locales/zh-TW/drop-in-agent.mdx   |   2 +-
 .../content/locales/zh-TW/notifications.mdx   |   2 +-
 .../docs/content/locales/zh-TW/progress.mdx   |   4 +-
 .../locales/zh-TW/real-time-collaboration.mdx |   4 +-
 .../docs/content/locales/zh-TW/routing.mdx    | 116 -----
 packages/core/docs/content/notifications.mdx  |   2 +-
 packages/core/docs/content/progress.mdx       |   4 +-
 .../docs/content/real-time-collaboration.mdx  |   4 +-
 packages/core/docs/content/routing.mdx        | 117 -----
 .../docs/content/template-chat-developers.mdx |   2 +-
 .../content/toolkit-command-navigation.mdx    |   2 +-
 packages/docs/app/components/docsNavItems.ts  |  12 +-
 packages/docs/app/i18n/ar-SA.ts               |   1 -
 packages/docs/app/i18n/de-DE.ts               |   1 -
 packages/docs/app/i18n/en-US.ts               |   1 -
 packages/docs/app/i18n/es-ES.ts               |   1 -
 packages/docs/app/i18n/fr-FR.ts               |   1 -
 packages/docs/app/i18n/hi-IN.ts               |   1 -
 packages/docs/app/i18n/ja-JP.ts               |   1 -
 packages/docs/app/i18n/ko-KR.ts               |   1 -
 packages/docs/app/i18n/pt-BR.ts               |   1 -
 packages/docs/app/i18n/zh-CN.ts               |   1 -
 packages/docs/app/i18n/zh-TW.ts               |   1 -
 .../docs/app/routes/docs.$locale.$slug.tsx    |   5 +
 packages/docs/app/routes/docs.$slug.tsx       |   5 +
 161 files changed, 14274 insertions(+), 6587 deletions(-)
 delete mode 100644 packages/core/docs/content/client.mdx
 create mode 100644 packages/core/docs/content/locales/ar-SA/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/ar-SA/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/ar-SA/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/ar-SA/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/ar-SA/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/ar-SA/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/ar-SA/client.mdx
 delete mode 100644 packages/core/docs/content/locales/ar-SA/routing.mdx
 create mode 100644 packages/core/docs/content/locales/de-DE/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/de-DE/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/de-DE/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/de-DE/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/de-DE/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/de-DE/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/de-DE/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/de-DE/client.mdx
 delete mode 100644 packages/core/docs/content/locales/de-DE/routing.mdx
 create mode 100644 packages/core/docs/content/locales/es-ES/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/es-ES/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/es-ES/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/es-ES/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/es-ES/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/es-ES/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/es-ES/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/es-ES/client.mdx
 delete mode 100644 packages/core/docs/content/locales/es-ES/routing.mdx
 create mode 100644 packages/core/docs/content/locales/fr-FR/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/fr-FR/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/fr-FR/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/fr-FR/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/fr-FR/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/fr-FR/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/fr-FR/client.mdx
 delete mode 100644 packages/core/docs/content/locales/fr-FR/routing.mdx
 create mode 100644 packages/core/docs/content/locales/hi-IN/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/hi-IN/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/hi-IN/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/hi-IN/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/hi-IN/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/hi-IN/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/hi-IN/client.mdx
 delete mode 100644 packages/core/docs/content/locales/hi-IN/routing.mdx
 create mode 100644 packages/core/docs/content/locales/ja-JP/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/ja-JP/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/ja-JP/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/ja-JP/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/ja-JP/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/ja-JP/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/ja-JP/client.mdx
 delete mode 100644 packages/core/docs/content/locales/ja-JP/routing.mdx
 create mode 100644 packages/core/docs/content/locales/ko-KR/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/ko-KR/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/ko-KR/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/ko-KR/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/ko-KR/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/ko-KR/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/ko-KR/client.mdx
 delete mode 100644 packages/core/docs/content/locales/ko-KR/routing.mdx
 create mode 100644 packages/core/docs/content/locales/pt-BR/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/pt-BR/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/pt-BR/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/pt-BR/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/pt-BR/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/pt-BR/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/pt-BR/client.mdx
 delete mode 100644 packages/core/docs/content/locales/pt-BR/routing.mdx
 create mode 100644 packages/core/docs/content/locales/zh-CN/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/zh-CN/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/zh-CN/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/zh-CN/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/zh-CN/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/zh-CN/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/zh-CN/client.mdx
 delete mode 100644 packages/core/docs/content/locales/zh-CN/routing.mdx
 create mode 100644 packages/core/docs/content/locales/zh-TW/client-advanced.mdx
 create mode 100644 packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx
 create mode 100644 packages/core/docs/content/locales/zh-TW/client-data.mdx
 create mode 100644 packages/core/docs/content/locales/zh-TW/client-entry-points.mdx
 create mode 100644 packages/core/docs/content/locales/zh-TW/client-overview.mdx
 create mode 100644 packages/core/docs/content/locales/zh-TW/client-routing.mdx
 create mode 100644 packages/core/docs/content/locales/zh-TW/client-sync-internals.mdx
 delete mode 100644 packages/core/docs/content/locales/zh-TW/client.mdx
 delete mode 100644 packages/core/docs/content/locales/zh-TW/routing.mdx
 delete mode 100644 packages/core/docs/content/routing.mdx

diff --git a/packages/core/docs/content/client-advanced.mdx b/packages/core/docs/content/client-advanced.mdx
index 17c09d7541..0d846336c6 100644
--- a/packages/core/docs/content/client-advanced.mdx
+++ b/packages/core/docs/content/client-advanced.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Advanced"
 description: "Lower-level app/ primitives and escape hatches: direct application-state access, background chat sends, custom suggestion chips, and the MCP App host bridge."
-draft: true
 ---
 
 # Advanced
diff --git a/packages/core/docs/content/client-agent-chat.mdx b/packages/core/docs/content/client-agent-chat.mdx
index 11621e3943..265a16187f 100644
--- a/packages/core/docs/content/client-agent-chat.mdx
+++ b/packages/core/docs/content/client-agent-chat.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Agent Chat"
 description: "Client-side entry points into agent chat: sendToAgentChat, openAgentSettings, askUserQuestion, dynamic suggestions, useAgentChatGenerating, and staged agent chat context state."
-draft: true
 ---
 
 # Agent Chat
diff --git a/packages/core/docs/content/client-data.mdx b/packages/core/docs/content/client-data.mdx
index 4c6b82ca09..0b753c3133 100644
--- a/packages/core/docs/content/client-data.mdx
+++ b/packages/core/docs/content/client-data.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Data & Sync"
 description: "The action hooks app/ uses to read, write, and stay live-synced with the same actions the agent calls."
-draft: true
 ---
 
 # Data & Sync
diff --git a/packages/core/docs/content/client-entry-points.mdx b/packages/core/docs/content/client-entry-points.mdx
index 051b35a4d7..2c09986e59 100644
--- a/packages/core/docs/content/client-entry-points.mdx
+++ b/packages/core/docs/content/client-entry-points.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Entry Points"
 description: "app/entry.client.tsx and app/entry.server.tsx: the thin hydration and SSR bootstrap wrappers, and when to customize streaming behavior."
-draft: true
 ---
 
 # Entry Points
@@ -19,10 +18,10 @@ export default createDocumentRequestHandler(ServerRouter);
 export { streamTimeout };
 ```
 
-Reach for these only for advanced SSR customization, for example changing streaming behavior. Ordinary pages, layout, and data don't need changes here. See [Routing](/docs/routing) for adding pages instead.
+Reach for these only for advanced SSR customization, for example changing streaming behavior. Ordinary pages, layout, and data don't need changes here. See [Routing](/docs/client-routing) for adding pages instead.
 
 ## What's next
 
 - [**Overview**](/docs/client-overview) — where these files sit in `app/`
-- [**Routing**](/docs/routing) — adding pages, the normal way to extend `app/`
+- [**Routing**](/docs/client-routing) — adding pages, the normal way to extend `app/`
 - [**Advanced**](/docs/client-advanced) — the other lower-level client primitives and escape hatches
diff --git a/packages/core/docs/content/client-overview.mdx b/packages/core/docs/content/client-overview.mdx
index 8578a3f831..e6e071210f 100644
--- a/packages/core/docs/content/client-overview.mdx
+++ b/packages/core/docs/content/client-overview.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Overview"
 description: "The app/ and public/ directories: where you build the display of an agent-native app, and the browser APIs it uses to stay in sync with the agent."
-draft: true
 ---
 
 # Overview
@@ -111,7 +110,7 @@ This page covers the directories you build in and the pieces of the browser runt
 | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | **`app/root.tsx`**                                  | The HTML shell and provider stack — see [The Browser Shell](#app-shell) below                                     |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration and SSR bootstrap — see [Entry Points](/docs/client-entry-points)                                       |
-| **`app/routes.ts` + `app/routes/`**                 | File-based pages and navigation — see [Routing](/docs/routing)                                                    |
+| **`app/routes.ts` + `app/routes/`**                 | File-based pages and navigation — see [Routing](/docs/client-routing)                                             |
 | **`app/components/`**                               | Your UI: shadcn-style primitives plus app-specific components — see [shadcn/ui](/docs/shadcn-ui)                  |
 | **`app/hooks/`**                                    | Data, sync, and agent-chat hooks — see [Data & Sync](/docs/client-data) and [Agent Chat](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | Shared client utilities (app config, tab id, `cn`) — see [Utilities](#utilities) below                            |
@@ -201,7 +200,7 @@ import { cn } from "@agent-native/toolkit/utils";
 - [**Advanced**](/docs/client-advanced) — application state, background chat sends, and the MCP App host bridge
 - [**Sync Internals**](/docs/client-sync-internals) — `useChangeVersion` for syncing a raw `useQuery`
 - [**Entry Points**](/docs/client-entry-points) — SSR bootstrap customization
-- [**Routing**](/docs/routing) — file-based pages, dynamic params, and navigation
+- [**Routing**](/docs/client-routing) — file-based pages, dynamic params, and navigation
 - [**Actions**](/docs/actions) — the `defineAction` surface behind every data hook
 - [**Custom Design Systems**](/docs/custom-design-system) — swapping in your own component library via `app/design-system.ts`
 - [**Authentication**](/docs/authentication) — the session checks `AppProviders` runs on private paths
diff --git a/packages/core/docs/content/client-routing.mdx b/packages/core/docs/content/client-routing.mdx
index 21379d84a3..051021faa8 100644
--- a/packages/core/docs/content/client-routing.mdx
+++ b/packages/core/docs/content/client-routing.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Routing"
 description: "File-based routing for agent-native apps with React Router v8: pages, dynamic params, and navigation."
-draft: true
 ---
 
 # Routing
diff --git a/packages/core/docs/content/client-sync-internals.mdx b/packages/core/docs/content/client-sync-internals.mdx
index 654e4d9ff3..14549f6a3b 100644
--- a/packages/core/docs/content/client-sync-internals.mdx
+++ b/packages/core/docs/content/client-sync-internals.mdx
@@ -1,7 +1,6 @@
 ---
 title: "Sync Internals"
 description: "The change-version mechanism behind useDbSync: useChangeVersion/useChangeVersions for syncing a raw useQuery, and the two latency paths a refetch can take."
-draft: true
 ---
 
 # Sync Internals
diff --git a/packages/core/docs/content/client.mdx b/packages/core/docs/content/client.mdx
deleted file mode 100644
index efe2be414d..0000000000
--- a/packages/core/docs/content/client.mdx
+++ /dev/null
@@ -1,486 +0,0 @@
----
-title: "Client"
-description: "React hooks and utilities for agent-native apps: sendToAgentChat, optional agent chat context state, useDbSync, useAgentChatGenerating, and cn."
----
-
-# Client
-
-`@agent-native/core` provides React hooks and utilities for the browser-side of agent-native apps.
-
-These client/React APIs are exported from both `@agent-native/core` and `@agent-native/core/client`. Import them from `@agent-native/core/client` (the browser entry) for clarity and correct bundling, since the bare `@agent-native/core` root resolves to the Node build by default.
-
-For file-based routing — adding pages, dynamic params, and navigation — see [Routing](/docs/routing).
-
-On this page: [data hooks](#fetching-mutating), [sendToAgentChat](#sendtoagentchat),
-[agent chat context state](#agent-chat-context-state),
-[openAgentSettings](#openagentsettings), [askUserQuestion](#ask-user-question),
-[MCP App host bridge](#mcp-app-host-bridge),
-[dynamic suggestions](#dynamic-suggestions),
-[useAgentChatGenerating](#useagentchatgenerating), [useDbSync](#usedbsync),
-[change versions](#use-change-version), and [cn](#cn).
-
-## Fetching and Mutating Data {#fetching-mutating}
-
-The primary way to read and write app data from the browser is through the action hooks. Never hand-write `fetch` calls to `/_agent-native/*` routes — use the named helpers instead (see [Actions](/docs/actions)).
-
-<Diagram id="doc-block-1agk0cd" title="The browser data loop" summary={"Hooks read and write through actions; useDbSync watches the database so agent and background writes refetch the same caches automatically."}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>SQL database</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(opts) {#sendtoagentchat}
-
-Send a message to the agent chat via postMessage — the common way to delegate an AI task from a UI interaction. Pass `context` for hidden model context and `submit: true` to send immediately, or `submit: false` to prefill a draft the user reviews first.
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-Inside an MCP App embed created with `embedApp()`, auto-submitted messages
-(`submit` omitted or `true`) are forwarded to the MCP App host bridge, which
-asks the containing host to add hidden context and send the visible user turn.
-`context` stays model-visible without being posted as user-facing chat.
-`submit: false` keeps the local prefill/review behavior because MCP Apps do not
-define a standard draft-prefill API. Internally this is the submitted-chat path
-sometimes surfaced as `agentNative.submitChat`; app code should call
-`sendToAgentChat()` rather than posting that event directly.
-
-### Silent background sends {#background-send}
-
-Use `background: true` when a UI action should kick off real agent work without
-opening or focusing the sidebar. This still creates a normal chat thread/run,
-uses the agent's tools/actions/context, and keeps the work observable through
-the runs tray; it is not a raw one-shot model call.
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` is intended to be paired with `newTab` so the hidden work does not
-overwrite the user's active conversation. Use the returned `tabId` if the UI
-needs to correlate follow-up status or deep-link into the run later.
-
-### AgentChatMessage {#agentchatmessage}
-
-| Option                | Type        | Description                                                                |
-| --------------------- | ----------- | -------------------------------------------------------------------------- |
-| `message`             | `string`    | The visible prompt sent to the chat                                        |
-| `context`             | `string?`   | Hidden context appended (not shown in chat UI)                             |
-| `submit`              | `boolean?`  | true = auto-submit, false = prefill only                                   |
-| `newTab`              | `boolean?`  | Create a separate chat thread for this prompt                              |
-| `background`          | `boolean?`  | With `newTab`, run without focusing the tab and show the run in `RunsTray` |
-| `openSidebar`         | `boolean?`  | Set false to submit/prefill without opening the sidebar                    |
-| `projectSlug`         | `string?`   | Optional project slug for structured context                               |
-| `preset`              | `string?`   | Optional preset name for downstream consumers                              |
-| `referenceImagePaths` | `string[]?` | Optional reference image paths                                             |
-
-## Agent Chat Context State (Advanced) {#agent-chat-context-state}
-
-The context-state APIs are optional plumbing for UI that needs two-way sync with
-staged context chips: rendering the current staged items outside the composer,
-reflecting whether an item is already attached, or providing explicit
-remove/clear controls.
-
-Do not reach for these helpers for simple "send this to the agent" or
-"prefill this draft for review" flows. Use `sendToAgentChat()` with `context`
-and `submit` for those.
-
-| API                               | Use when                                                               |
-| --------------------------------- | ---------------------------------------------------------------------- |
-| `useAgentChatContext()`           | A React component needs the live staged context list                   |
-| `setAgentChatContextItem(item)`   | Imperative code should stage or replace one keyed context item         |
-| `listAgentChatContext()`          | Non-React code needs a one-time snapshot of staged context             |
-| `removeAgentChatContextItem(key)` | UI should remove one staged context item by its stable `key`           |
-| `clearAgentChatContext()`         | UI should clear all staged context, such as after a view or mode reset |
-| `refreshAgentChatContext()`       | Imperative code should re-read the latest persisted context snapshot   |
-
-`useAgentChatContext()` returns `{ items, set, remove, clear, refresh }`.
-
-## openAgentSettings(section?) {#openagentsettings}
-
-Use `openAgentSettings()` when an app settings page or setup card should open
-the agent sidebar's Settings tab. Pass a section id such as `"llm"`, `"secrets"`,
-`"automations"`, `"voice"`, or `"limits"` to open a specific section.
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-Prefer this helper over dispatching `agent-panel:open-settings` directly.
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` is for imperative code that only needs to inspect the
-current staged items once. `clearAgentChatContext()` is intentionally broad; use
-`removeAgentChatContextItem(key)` when only one selection changed.
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| Option        | Type       | Description                                            |
-| ------------- | ---------- | ------------------------------------------------------ |
-| `key`         | `string`   | Stable identifier used to replace an existing nugget   |
-| `title`       | `string`   | Short label shown in the composer chip                 |
-| `context`     | `string`   | Hidden context included with the next submitted prompt |
-| `openSidebar` | `boolean?` | Defaults to true; pass false to stage context silently |
-
-## askUserQuestion(opts) {#ask-user-question}
-
-Ask the user a multiple-choice question from app code, render it inline in the
-agent panel, and **await their answer**. It's the client-side twin of the
-agent's built-in `ask-question` tool: it writes a `GuidedQuestionPayload` to the
-`"guided-questions"` application-state key (where the mounted
-`GuidedQuestionFlow` renders it) and reveals the agent panel so the question is
-visible. Unlike the agent tool — whose answer flows back to the agent —
-`askUserQuestion()` **resolves with the answer to the caller**, so the UI can
-branch on it.
-
-Use it when the UI needs exactly one small decision (2–4 options) before it
-kicks off agent work — instead of building a custom modal. Reach for the
-composer for freeform detail, and a form/popover for multi-field input.
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-Each option is `{ label, value?, description?, preview?, recommended? }`; `value`
-defaults to `label`, and `preview` renders a small mockup/code snippet under the
-option. The promise resolves with the selected `value` (or `value[]` when
-`allowMultiple`), the free-text string when the user picks "Other", or `null`
-if they skip — it stays pending until the user answers. Requires the agent panel
-to be mounted (it is in every template).
-
-The agent reaches the same UI through its `ask-question` tool: prefer letting the
-agent ask when _it_ hits a genuine fork it can't resolve from context; use
-`askUserQuestion()` when the _UI_ needs to gate an action on a choice.
-
-## MCP App Host Bridge {#mcp-app-host-bridge}
-
-Routes embedded as MCP Apps should be URL-first: load the current artifact from
-path/query params, render the real React route or a focused shared component,
-and use the host bridge only for host-owned behavior. `@agent-native/core/client`
-exports the helpers embedded routes call:
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()` reads the latest pushed host context snapshot;
-`useMcpAppHostContext()` subscribes React components to changes. The request
-helpers (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
-`updateMcpAppModelContext`) return `false` outside an embedded MCP App frame, or
-`Promise<boolean>` inside a frame. `sendToAgentChat()` uses the same bridge for
-auto-submitted prompts from embedded routes.
-
-The bridge itself — the `ui/*` JSON-RPC messages, the `agentNative.mcpHost.*`
-wrapper relay, transplant vs. controlled-frame rendering, host context, and
-display-mode requests — is owned by
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## Dynamic Suggestions {#dynamic-suggestions}
-
-`<AgentSidebar>`, `<AgentPanel>`, and `<AssistantChat>` merge static `suggestions` with context-aware suggestions by default. The framework reads `navigation`, `selection`, `pending-selection-context`, and the current URL from application state while an empty chat is visible, then offers prompt chips that match the current screen.
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-Set `dynamicSuggestions={false}` to keep only static chips. Pass `getSuggestions` when an app wants deterministic domain-specific chips from the same application-state context.
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-React hook that wraps sendToAgentChat with loading state tracking:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-`isGenerating` turns true when you call `send()` and automatically resets to false when the agent finishes generating.
-
-## useDbSync(options?) {#usedbsync}
-
-React hook (formerly `useFileWatcher`) that listens for database changes over SSE, falls back to polling, and invalidates the framework query caches that keep the UI aligned with agent writes:
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### Options {#usedbsync-options}
-
-| Option             | Type               | Description                                                                                                                                                   |
-| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | React-query client for cache invalidation                                                                                                                     |
-| `queryKeys`        | `string[]?`        | Deprecated and ignored; kept for old call sites                                                                                                               |
-| `pollUrl`          | `string?`          | Poll endpoint URL. Default: `"/_agent-native/poll"`                                                                                                           |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                                                                        |
-| `interval`         | `number?`          | Polling interval in ms. Default: `2000`                                                                                                                       |
-| `fallbackInterval` | `number?`          | Fallback polling interval when SSE is unavailable. Default: `60000`                                                                                           |
-| `pauseWhenHidden`  | `boolean?`         | Pause polling when the browser tab is hidden. Default: `false` — hidden tabs keep SSE connected and poll no faster than every 10s while active, 60s once idle |
-| `ignoreSource`     | `string?`          | Per-tab request source to ignore so a tab does not refetch from its own writes                                                                                |
-| `onEvent`          | `(data) => void`   | Optional callback when SSE/polling receives a change event                                                                                                    |
-
-For normal CRUD, prefer `useActionQuery` and `useActionMutation`; mutating actions emit `source: "action"` and those hooks refetch automatically.
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-The framework uses change versions to sync React Query caches with changes made by background agents, cron jobs, or other users.
-
-When any server-side database mutation occurs, the server records a change event with a specific `source` key. The client's `useDbSync` listener receives these events and bumps the local change version counter for that source. By folding the version counter into your React Query keys, queries automatically refetch whenever the backend notifies the client of new activity.
-
-- **`useChangeVersion(source: string): number`** — returns a counter that increments whenever the specified `source` is mutated.
-- **`useChangeVersions(sources: readonly string[]): number`** — returns the sum of version counters for multiple sources.
-
-### Example: Syncing a raw query with the database
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### Latency Models & Invalidation Behavior
-
-- **UI-Initiated mutations:** When you execute an action from the UI using `useActionMutation`, the mutation immediately fires a local event with `source: "action"` on success. This triggers an **instant, optimistic refetch** of all query keys depending on that action, avoiding visual delay.
-- **Background or Agent Mutations:** When the AI agent, a webhook, or a background worker mutates data, the update is broadcast to the client. The client's `useDbSync` captures this either instantly over SSE (Server-Sent Events) or falls back to the **2-second polling tick**. The query key version then bumps, triggering a background refetch.
-
-<Diagram id="doc-block-pcrqt5" title="Two paths to a refetch" summary={"A local mutation invalidates its own caches instantly; a remote write reaches this tab over SSE, or the polling tick as a fallback."}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">This tab</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">Agent · webhook · other tab</span
-      ><strong>Remote write</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...inputs) {#cn}
-
-Utility for merging class names (clsx + tailwind-merge):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
-
-## What's next
-
-- [**Actions**](/docs/actions) — the `defineAction` surface behind every hook on this page
-- [**Routing**](/docs/routing) — file-based pages, dynamic params, and navigation
-- [**Real-Time Sync**](/docs/key-concepts#polling-sync) — how `useDbSync` and change versions keep the UI current
-- [**Context Awareness**](/docs/context-awareness) — the `navigation`/`selection` state dynamic suggestions read
-- [**Generative UI**](/docs/generative-ui) — building richer inline chat controls beyond `askUserQuestion`
diff --git a/packages/core/docs/content/context-awareness.mdx b/packages/core/docs/content/context-awareness.mdx
index 7a54b49c92..b7bf778c22 100644
--- a/packages/core/docs/content/context-awareness.mdx
+++ b/packages/core/docs/content/context-awareness.mdx
@@ -486,5 +486,5 @@ How it works:
 - [**Agent Mentions**](/docs/agent-mentions) — `@`-mention files and agents into a turn instead of relying on ambient context
 - [**Drop-in Agent**](/docs/drop-in-agent) — mount the panel that reads and writes this state
 - [**Real-Time Collaboration**](/docs/real-time-collaboration) — keep app state in sync when the agent and users edit together
-- [**Client Methods**](/docs/client) — the full `application-state` and client helper reference
+- [**Application State**](/docs/client-advanced#application-state) — the full `application-state` and client helper reference
 - [**Toolkit piece: Context & Knowledge**](/docs/toolkit-context-knowledge) — the Context X-Ray presentation built on this state
diff --git a/packages/core/docs/content/drop-in-agent.mdx b/packages/core/docs/content/drop-in-agent.mdx
index be52e67357..211d71f629 100644
--- a/packages/core/docs/content/drop-in-agent.mdx
+++ b/packages/core/docs/content/drop-in-agent.mdx
@@ -231,7 +231,7 @@ tracking. It simply does not steal focus from the user's current sidebar state.
 
 When the same route is embedded as an MCP App, submitted
 `sendToAgentChat()` calls are forwarded to the host chat where supported; see
-[Client](/docs/client#sendtoagentchat) for the MCP App bridge behavior.
+[Agent Chat](/docs/client-agent-chat#sendtoagentchat) for the MCP App bridge behavior.
 
 If you want a loading state, use the `useSendToAgentChat()` hook — it returns both `send` and `isGenerating`:
 
diff --git a/packages/core/docs/content/internationalization.mdx b/packages/core/docs/content/internationalization.mdx
index 6c42d238de..77ac4340fa 100644
--- a/packages/core/docs/content/internationalization.mdx
+++ b/packages/core/docs/content/internationalization.mdx
@@ -148,6 +148,6 @@ names.
 
 ## What's next
 
-- [**Client**](/docs/client) — the `AppProviders` wrapper and other browser hooks i18n builds on
+- [**Overview**](/docs/client-overview#app-shell) — the `AppProviders` wrapper and other browser hooks i18n builds on
 - [**Toolkit: Settings**](/docs/toolkit-settings) — put `<LanguagePicker>` on the standard settings page
 - [**Getting Started**](/docs/getting-started) — build your first app on a template that already ships localized catalogs
diff --git a/packages/core/docs/content/locales/ar-SA/client-advanced.mdx b/packages/core/docs/content/locales/ar-SA/client-advanced.mdx
new file mode 100644
index 0000000000..46c3928dc4
--- /dev/null
+++ b/packages/core/docs/content/locales/ar-SA/client-advanced.mdx
@@ -0,0 +1,192 @@
+---
+title: "متقدم"
+description: "بدائيات (primitives) app/ ذات المستوى الأدنى ومخارج الطوارئ: الوصول المباشر إلى حالة التطبيق، الإرسال في الخلفية للمحادثة، شرائح الاقتراحات المخصصة، وجسر استضافة MCP App."
+---
+
+# متقدم
+
+تغطي نظرة عامة، والبيانات والمزامنة، ومحادثة الوكيل، والتوجيه الحالة النموذجية: الخطافات والأدوات المساعدة التي تحتاجها معظم الصفحات. تغطي هذه الصفحة البدائيات ذات المستوى الأدنى ومخارج الطوارئ الأضيق الموجودة تحتها. لا تلمس معظم التطبيقات هذه مباشرة أبدًا. استخدم واحدة منها عندما تبني شيئًا أكثر تخصيصًا من الخطافات الافتراضية التي تدعمها، مثل مزامنة تحديد مخصصة أو MCP App مضمّن. لمزامنة `useQuery` خام بمفتاح مصنوع يدويًا، راجع [آليات المزامنة الداخلية](/docs/client-sync-internals) بدلًا من ذلك.
+
+## حالة التطبيق {#application-state}
+
+`application_state` هو مخزن مفتاح/قيمة مدعوم بـ SQL يقرأه الوكيل لمعرفة ما تنظر إليه واجهة المستخدم حاليًا، بما في ذلك التنقل، والتحديد، وسياق الكائن المُركَّز عليه الآخر (راجع [الوعي بالسياق](/docs/context-awareness)). يُغلِّف `useAgentRouteState` و`useSemanticNavigationState` (المُغطّيان أيضًا في الوعي بالسياق) هذه البدائيات بالفعل لحالة التنقل الشائعة. استخدم البدائيات أدناه مباشرة عندما تكون تُزامن شيئًا لا تغطيه، مثل تحديد مخصص، أو الكتابة من خارج عرض مكون.
+
+### readClientAppState {#read-client-app-state}
+
+اقرأ القيمة الحالية لمفتاح. يُحل إلى آخر ما تمت كتابته لهذا المفتاح، أو `null` إذا لم تتم كتابة المفتاح مطلقًا.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+اكتب قيمة لمفتاح. على عكس `setClientAppState` أدناه، تكتب دائمًا، حتى إذا مررت `null`. تمرير `undefined` يرمي خطأ بدلًا من ذلك، لأن `undefined` ليس JSON صالحًا. استخدم `setClientAppState(key, undefined)` أو `deleteClientAppState()` لمسح مفتاح.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+الغلاف المناسب الذي يجب أن تستخدمه معظم كود واجهة المستخدم: يكتب القيمة، أو يحذف المفتاح عندما تمرر `null`/`undefined`. استخدم هذا بدلاً من `writeClientAppState` إلا إذا كان موقع الاستدعاء يحتاج فعليًا إلى "الكتابة دائمًا، عدم الحذف مطلقًا".
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+احذف مفتاحًا بالكامل.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+اقرأ عدة مفاتيح في طلب واحد. تُعيد `{ values, missing }`. تحتفظ `values` بإدخال لكل مفتاح يملك الخادم صفًا له، بما في ذلك مفتاح تمت كتابته صريحًا كـ `null`. تسرد `missing` المفاتيح التي لم تتم كتابتها مطلقًا. هذه هي الطريقة التي يبقى بها "لم تتم الكتابة مطلقًا" قابلًا للتمييز عن "مكتوب كـ null".
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+يتم تجميع الطلبات التي تتجاوز 100 مفتاح تلقائيًا في مجموعات. يُبنى `readClientAppState()` نفسها على هذا: تُدمَج الاستدعاءات الصادرة في نفس اللحظة (tick) في طلب مُجمَّع واحد خلف الكواليس، لذا يكلف استدعاءها عدة مرات في تمريرة عرض واحدة رحلة ذهاب وعودة واحدة، لا رحلة لكل استدعاء.
+
+### الخيارات {#application-state-options}
+
+يُقبَل `signal` من قِبل جميع الدوال الخمس أعلاه، لإلغاء استدعاء قيد التنفيذ. ينطبق `requestSource` و`keepalive` فقط على دوال الكتابة الثلاث، لأنهما لا يعنيان شيئًا بالنسبة للقراءة.
+
+| الخيار          | النوع          | ينطبق على                                                          | الوصف                                                                                                   |
+| --------------- | -------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`، `setClientAppState`، `deleteClientAppState` | يُضيف علامة على الكتابة بمعرِّف حتى يتمكن `useDbSync({ ignoreSource })` المطابق من تخطي إعادة الجلب لها |
+| `keepalive`     | `boolean?`     | `writeClientAppState`، `setClientAppState`، `deleteClientAppState` | يسمح للطلب بالاستمرار بعد تفريغ الصفحة (unload). استخدمه لكتابات التنظيف مثل مسح التحديد                |
+| `signal`        | `AbortSignal?` | جميع الدوال الخمس                                                  | يلغي الطلب                                                                                              |
+
+### سلوك الفشل {#failure-behavior}
+
+ترمي جميع الدوال الخمس خطأ عند فشل الطلب، أو استجابة غير 2xx، أو نص لا يمكن تحليله. يحمل `Error` المرمي خاصية `.status` عندما يستجيب الخادم، لذا يمكن للمستدعي التفريع بناءً على حالة HTTP إذا لزم الأمر. غلِّف الاستدعاء بـ `try`/`catch`، أو دعه ينتشر إلى حدود خطأ، تمامًا مثل أي استدعاء شبكة آخر.
+
+### ما هو TAB_ID {#tab-id}
+
+يُضبَط `requestSource` بشكل شائع على `TAB_ID`، وهو ثابت عادي يُصدِّره كل قالب من `app/lib/tab-id.ts`: سلسلة عشوائية قصيرة تبقى نفسها طوال عمر علامة تبويب وتختلف بين علامات التبويب. إقران `requestSource: TAB_ID` على كتابة مع `useDbSync({ ignoreSource: TAB_ID })` على جانب القراءة هو كيف تتجنب علامة التبويب إعادة جلب كتابتها الخاصة بينما تظل تتفاعل مع كل الآخرين. راجع [الوعي بالسياق](/docs/context-awareness#jitter-prevention) للحصول على الشرح الكامل.
+
+## sendToAgentChat: الإرسال في الخلفية {#background-send}
+
+استخدم `background: true` عندما ينبغي لإجراء واجهة مستخدم أن يبدأ عمل وكيل حقيقي دون
+فتح أو تركيز الشريط الجانبي. لا يزال هذا يُنشئ سلسلة محادثة/تشغيل عادية،
+ويستخدم أدوات/actions/سياق الوكيل، ويحافظ على إمكانية ملاحظة العمل من خلال
+علبة التشغيل. إنه ليس استدعاء نموذج فوري خام لمرة واحدة.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+يُقصد إقران `background` مع `newTab` حتى لا يُغطّي العمل المخفي
+محادثة المستخدم النشطة. استخدم `tabId` المُعاد إذا كانت واجهة المستخدم تحتاج إلى
+ربط حالة المتابعة أو الربط العميق بالتشغيل لاحقًا.
+
+توجد بعض خيارات `AgentChatMessage` الإضافية بعيدًا عن الخيارات المُغطّاة في [محادثة الوكيل](/docs/client-agent-chat#agentchatmessage)، معظمها لحالات التضمين أو التكامل اللاحق:
+
+| الخيار                | النوع       | الوصف                                                                 |
+| --------------------- | ----------- | --------------------------------------------------------------------- |
+| `background`          | `boolean?`  | مع `newTab`، يعمل دون تركيز علامة التبويب ويعرض التشغيل في `RunsTray` |
+| `projectSlug`         | `string?`   | ارتباط ثابت اختياري للمشروع لسياق منظّم                               |
+| `preset`              | `string?`   | اسم إعداد مسبق اختياري للمستهلكين اللاحقين                            |
+| `referenceImagePaths` | `string[]?` | مسارات صور مرجعية اختيارية                                            |
+
+## جسر استضافة MCP App {#mcp-app-host-bridge}
+
+ينبغي أن تكون المسارات المُضمَّنة كتطبيقات MCP أولوية عنوان URL: تحميل العنصر الحالي من
+معلمات المسار/الاستعلام، وعرض مسار React الحقيقي أو مكون مشترك مُركَّز، واستخدام
+الجسر المضيف فقط للسلوك المملوك للمضيف. يُصدِّر `@agent-native/core/client`
+الأدوات المساعدة التي تستدعيها المسارات المُضمَّنة:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+يقرأ `getMcpAppHostContext()` أحدث لقطة سياق مضيف مدفوعة.
+يشترك `useMcpAppHostContext()` مكونات React في التغييرات. تُعيد أدوات الطلب
+المساعدة (`openMcpAppHostLink`، `requestMcpAppDisplayMode`،
+`updateMcpAppModelContext`) `false` خارج إطار MCP App مُضمَّن، أو
+`Promise<boolean>` داخل إطار.
+
+يستخدم `sendToAgentChat()` (راجع [محادثة الوكيل](/docs/client-agent-chat#sendtoagentchat)) نفس الجسر للمطالبات المُرسَلة تلقائيًا من المسارات المُضمَّنة. داخل تضمين MCP App تم إنشاؤه بـ `embedApp()`، يتم توجيه الرسائل المُرسَلة تلقائيًا (حُذف `submit` أو `true`) إلى الجسر، الذي يطلب من المضيف المحتوي إضافة سياق مخفي وإرسال الدور المرئي للمستخدم. يبقى `context` مرئيًا للنموذج دون أن يُنشَر كمحادثة مواجهة للمستخدم. يحتفظ `submit: false` بسلوك التعبئة/المراجعة المسبقة المحلي لأن تطبيقات MCP لا تُعرِّف واجهة برمجة قياسية لتعبئة المسودة مسبقًا. داخليًا هذا هو مسار المحادثة المُرسَلة الذي يظهر أحيانًا كـ `agentNative.submitChat`. يجب أن يستمر كود التطبيق في استدعاء `sendToAgentChat()` بدلًا من نشر ذلك الحدث مباشرة.
+
+الجسر نفسه، ورسائل `ui/*` JSON-RPC، وترحيل الغلاف (wrapper relay) `agentNative.mcpHost.*`،
+والزرع (transplant) مقابل عرض الإطار المتحكم فيه، وسياق المضيف، و
+طلبات وضع العرض، مملوك لـ
+[الوكلاء الخارجيون](/docs/external-agents#mcp-app-bridge). راجع [تطبيقات MCP](/docs/mcp-apps) للتعرف على البروتوكول الكامل.
+
+## شرائح الاقتراحات المخصصة {#custom-suggestions}
+
+تدمج `dynamicSuggestions` الخاصة بـ `<AgentSidebar>` (راجع [محادثة الوكيل](/docs/client-agent-chat#dynamic-suggestions)) بالفعل `suggestions` الثابتة مع الاستدلال المدرك للسياق الخاص بإطار العمل. مرر `getSuggestions` بدلًا من ذلك عندما يريد تطبيق شرائح حتمية خاصة بالمجال محسوبة من نفس سياق `application_state` بدلًا من استدلال إطار العمل الافتراضي.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+تستقبل `getSuggestions` نفس لقطة `navigation`/`selection`/`pending-selection-context` التي يقرأها الاستدلال المدمج، لذا يمكن لتنفيذ مخصص أن يتفاعل مع الحالة نفسها التي يتفاعل معها الاستدلال الافتراضي بالضبط، فقط بقواعد خاصة بالتطبيق بدلًا من قواعد عامة.
+
+## ما هي الخطوة التالية
+
+- [**نظرة عامة**](/docs/client-overview) — تخطيط دليلَي `app/` و`public/` الذي تعيش فيه هذه البدائيات
+- [**البيانات والمزامنة**](/docs/client-data) — خطافات actions الافتراضية و`useDbSync` التي ينبغي أن تستخدمها معظم الصفحات بدلًا من ذلك
+- [**آليات المزامنة الداخلية**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` والمساران اللذان يمكن أن تسلكهما إعادة الجلب
+- [**محادثة الوكيل**](/docs/client-agent-chat) — الأدوات المساعدة الافتراضية `sendToAgentChat`/`askUserQuestion` التي ينبغي أن تستخدمها معظم واجهات المستخدم بدلًا من ذلك، وواجهات برمجة حالة سياق محادثة الوكيل المرحلية
+- [**نقاط الدخول**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` وتخصيص بث SSR
+- [**الوعي بالسياق**](/docs/context-awareness) — دلالات `navigation`/`selection` المبنية على `application_state`، وشرح `TAB_ID`/منع الاهتزاز
+- [**واجهة المستخدم التوليدية**](/docs/generative-ui) — عناصر تحكم أكثر ثراءً مضمّنة في المحادثة تتجاوز `askUserQuestion`
+- [**الوكلاء الخارجيون**](/docs/external-agents#mcp-app-bridge) — آليات جسر استضافة MCP App الكاملة
diff --git a/packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx b/packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx
new file mode 100644
index 0000000000..6e0f864b5f
--- /dev/null
+++ b/packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx
@@ -0,0 +1,312 @@
+---
+title: "محادثة الوكيل"
+description: "نقاط الدخول من جانب العميل إلى محادثة الوكيل: sendToAgentChat، وopenAgentSettings، وaskUserQuestion، والاقتراحات الديناميكية، وuseAgentChatGenerating، وحالة سياق محادثة الوكيل المرحلية."
+---
+
+# محادثة الوكيل
+
+يمكن لعميل تطبيقك التحدث إلى الوكيل من خلال مجموعة صغيرة من الأدوات المساعدة الخاصة بالعميل. تغطي هذه الأدوات إرسال مطالبة، وتهيئة سياق مخفي، وسؤال المستخدم سؤالاً معطِّلاً (blocking)، وفتح لوحة الوكيل.
+
+في المثال أدناه، يطلب زر **صياغة رد** من الوكيل أن يسأل المستخدم سؤالاً. بعد أن يجيب المستخدم، يشرع الوكيل في صياغة رد يأخذ في الحسبان سياق الصفحة الحالية ورد المستخدم.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="لقطة شاشة تطبيق Dispatch تعرض الشريط الجانبي لتاريخ التشغيل"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="الشريط الجانبي لتاريخ التشغيل في Dispatch."
+/>
+
+## كيف يعمل
+
+باستخدام أساليب الأدوات المساعدة الخاصة بالعميل التي توفرها Agent-Native، يمكن لواجهة المستخدم أن تطلب من الوكيل التفاعل مع المستخدم بطرق متنوعة. يوضح الرسم البياني أدناه كيف يمكن للمستخدم النقر على زر "صياغة رد"، الذي يطلب من الوكيل بعد ذلك التفاعل مع المستخدم قبل إنشاء رد.
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="رسم بياني تسلسلي بعنوان 'من يملك كل خطوة'، يعرض ثلاثة خطوط حياة: كود التطبيق، وواجهة المستخدم، والوكيل. ينقر المستخدم على 'صياغة رد'، مما يُشغّل askUserQuestion(). ملاحظة توضح أن هذا يُعرَض بشكل مضمّن في لوحة الوكيل. يرد المستخدم، ثم يتم استدعاء sendDraftRequest() على الوكيل، الذي يستدعي draft-ticket-reply ويُعيد ردًا مُصاغًا إلى مؤلف واجهة المستخدم."
+  align="full"
+  width={600}
+  caption="رسم بياني تسلسلي يوضح تدفق زر 'صياغة رد'."
+/>
+
+تجربة المستخدم هي كما يلي:
+
+1. ينقر المستخدم على زر **صياغة رد**، الذي يُشغّل استدعاء دالة `askUserQuestion()`. تتم الإجابة على السؤال بشكل مضمّن في لوحة الوكيل.
+
+1. يختار المستخدم **تقديم استرداد**، الذي يُشغّل `sendDraftRequest()` لإرسال المطالبة وسياق التذكرة إلى الوكيل.
+
+1. يستدعي الوكيل [action](/docs/actions) الخاص بـ `draft-ticket-reply`، ويظهر الرد المُصاغ في مؤلف الرد.
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "السؤال، وخياراته، وكيف ينبغي أن يتصرف.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description: "السؤال الكامل. واضح، ومحدد، ينتهي بعلامة استفهام.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'شريحة/عنوان قصير جدًا، حوالي 12 حرفًا، مثل `"Response"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "خياران إلى أربعة خيارات متمايزة. كل واحد هو `{ label, value?, description?, preview?, recommended? }`. القيمة الافتراضية لـ `value` هي `label`.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description: 'يضيف خيار نص حر "أخرى" يمكن للممثل الكتابة فيه.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "اختيار متعدد بدلاً من اختيار واحد.",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description: "مفتاح حالة التطبيق الذي تستطلعه لوحة الوكيل.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'القيمة `value` المختارة (أو `value[]` عند `allowMultiple`)، أو نص "أخرى" الذي كتبه الممثل، أو `null` إذا تخطى السؤال. تبقى معلَّقة حتى يجيب. تتطلب أن تكون لوحة الوكيل مُثبَّتة، وهي مُثبَّتة في كل قالب.',
+  }}
+/>
+
+تسأل هذه الدالة المستخدم سؤالاً متعدد الاختيارات من كود التطبيق، وتعرضه بشكل مضمّن في لوحة الوكيل، وتنتظر إجابته. استخدمها عندما تحتاج واجهة المستخدم إلى قرار صغير واحد بخيارين إلى أربعة خيارات قبل بدء عمل الوكيل، بدلاً من بناء نافذة منبثقة مخصصة.
+
+في المثال أدناه، يسأل زر "صياغة رد" في صفحة تذكرة الممثل عن كيفية رغبته في الرد قبل إرسال أي شيء إلى الوكيل:
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "زوج (tuple) بشكل `[isGenerating, send]`. تكون `isGenerating` هي `true` من لحظة استدعاء `send()` حتى يُعلن تشغيل محادثة الوكيل أنه توقف. لدى `send(opts)` نفس توقيع `sendToAgentChat()`، وتُعيد معرف علامة التبويب (tab id) التي أرسلت إليها.",
+  }}
+/>
+
+يُغلّف خطاف React هذا دالة `sendToAgentChat()` بتتبع حالة التحميل.
+
+1. المعامل الأول، `isGenerating`، يتحول إلى true عند استدعائه، ثم يُعاد ضبطه إلى false عندما ينتهي الوكيل من الإنشاء.
+
+2. المعامل الثاني، `send()`، يُطابق دالة `sendToAgentChat()`.
+
+لا يُعاد ضبط `isGenerating` إلا بعد أن يبدأ التشغيل فعليًا ويُعلن أنه توقف. يقوم استدعاء بـ `submit: false` بتعبئة مسودة مسبقًا دون بدء تشغيل، لذا تبقى `isGenerating` صحيحة (`true`) إلى الأبد بعد ذلك. استخدم هذا الخطاف فقط لعمليات الإرسال بـ `submit: true`؛ استدعِ `sendToAgentChat()` مباشرة لعمليات التعبئة المسبقة فقط.
+
+يكمل دمج هذا مع مثال `askUserQuestion()` أعلاه معالج الزر:
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="إكمال معالج صياغة الرد"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "حالة التحميل + الإرسال، معًا",
+      note: "تُعيد `useAgentChatGenerating()` نفس شكل الزوج الذي يُعيده استدعاء `sendToAgentChat()` الخام، ولكنها تضيف `isDrafting` حتى يتمكن الزر من تعطيل نفسه بينما الطلب قيد التنفيذ.",
+    },
+    {
+      lines: "10-17",
+      label: "إعادة استخدام خطوة السؤال",
+      note: "هذا هو استدعاء `askUserQuestion()` نفسه من القسم أعلاه، الآن داخل معالج الزر نفسه.",
+    },
+    {
+      lines: "18",
+      label: "حدد النوع قبل استخدام الإجابة",
+      note: "يسمح نوع الإرجاع دائمًا بـ `string[]` من `allowMultiple`، لذا يكون هذا الفحص مطلوبًا حتى مع أن هذا الاستدعاء لا يضبطه أبدًا.",
+    },
+    {
+      lines: "20-25",
+      label: "حوّل الاختيار إلى جملة",
+      note: "يُحوّل القيمة المختارة، أو النص الذي كتبه الممثل بنفسه، إلى العبارة التي تقرأها المطالبة أدناه بشكل طبيعي.",
+    },
+    {
+      lines: "27-32",
+      label: "حدد الاسم action والنية",
+      note: "تخبر الرسالة الوكيل بالضبط بأي action يستدعي (`draft-ticket-reply`) وتُذكّره بعدم إرسال الرد مباشرة. يضمن `openSidebar: true` أن يكون الرد المُصاغ مرئيًا حتى إذا كان الشريط الجانبي مغلقًا.",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting يقود الزر",
+      note: "معطَّل ومُعاد تسميته فقط بينما `sendDraftRequest()` قيد التنفيذ. يبقى الزر قابلاً للنقر بينما ينتظر `askUserQuestion()` رد الممثل، لأن ذلك يحدث قبل استدعاء `sendDraftRequest()` أبدًا.",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+أرسل رسالة إلى محادثة الوكيل عبر `postMessage`. هذا هو البدائي (primitive) ذو المستوى الأدنى الذي تُغلّفه `useAgentChatGenerating()` أعلاه، وهو مفيد عندما لا يحتاج تفاعل واجهة المستخدم إلى تتبع حالة تحميل خاص به. مرر `context` لتفصيل إضافي لا تحمله الرسالة بمفردها. يُلحَق بنفس الرسالة المرئية، مُغلَّفًا بوسوم `<context>`. إنه ليس مخفيًا عن المستخدم. مرر `submit: true` للإرسال فورًا، أو `submit: false` لتعبئة مسودة يراجعها المستخدم أولًا.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| الخيار        | النوع      | الوصف                                                                                 |
+| ------------- | ---------- | ------------------------------------------------------------------------------------- |
+| `message`     | `string`   | المطالبة المُرسلة إلى المحادثة. يُلحَق `context`، إن وُجد، بهذه الرسالة المرئية نفسها |
+| `context`     | `string?`  | تفصيل إضافي يُلحَق بالرسالة المرئية، مُغلَّف بوسوم `<context>`. غير مخفي عن المستخدم  |
+| `submit`      | `boolean?` | true = إرسال تلقائي، false = تعبئة مسبقة فقط                                          |
+| `newTab`      | `boolean?` | إنشاء سلسلة محادثة منفصلة لهذه المطالبة                                               |
+| `openSidebar` | `boolean?` | اضبطه على false للإرسال/التعبئة المسبقة دون فتح الشريط الجانبي                        |
+
+تشغيل هذا من داخل تضمين MCP App، أو تشغيل العمل في الخلفية دون فتح الشريط الجانبي، مُغطّى كلاهما في [متقدم](/docs/client-advanced#background-send).
+
+## الاقتراحات الديناميكية {#dynamic-suggestions}
+
+قبل بدء محادثة، تعرض `<AgentSidebar>`، و`<AgentPanel>`، و`<AssistantChat>` شرائح مطالبات على المحادثة الفارغة. لا تكون هذه افتراضيًا مجرد قائمة `suggestions` الثابتة الخاصة بك فقط: يقرأ إطار العمل `navigation`، و`selection`، و`pending-selection-context`، وعنوان URL الحالي من حالة التطبيق، ويدمج شرائح تطابق ما هو معروض فعليًا على الشاشة.
+
+يقوم بذلك من خلال فحصين. إذا كان هناك شيء محدد، يضيف شرائح عامة مثل "تلخيص هذا التحديد". بشكل منفصل، ينظر إلى `navigation` بحثًا عن أسماء حقول شائعة تستخدمها التطبيقات الحالية، مثل `threadId`/`emailId` لسلسلة بريد إلكتروني أو `dashboardId`/`chartId` لمخطط، ويضيف شرائح مصممة خصيصًا لهذا النوع من الشاشة، مثل "صياغة رد" لسلسلة رسائل أو "البحث عن حالات شاذة في هذه البيانات" لمخطط. أي ما يخرج به يتم دمجه مع `suggestions` الثابتة الخاصة بك، وإزالة التكرار، والتقييد عند `max`.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+إذا كانت الشاشة الحالية لا تطابق أي شيء يتعرف عليه الاستدلال (heuristic) ولم يكن هناك شيء محدد، فإنها لا تضيف أي شرائح، وتعود المحادثة الفارغة إلى `suggestions` الثابتة الخاصة بك فقط. اضبط `dynamicSuggestions={false}` للاحتفاظ بالشرائح الثابتة فقط. إذا كان شكل التنقل في تطبيقك لا يطابق الاستدلال المدمج، أو كنت تريد شرائح حتمية خاصة بالتطبيق بالكامل، راجع [متقدم](/docs/client-advanced#custom-suggestions).
+
+## openAgentSettings(section?) {#openagentsettings}
+
+استخدم `openAgentSettings()` عندما ينبغي أن تفتح صفحة إعدادات التطبيق أو بطاقة الإعداد
+علامة تبويب الإعدادات في الشريط الجانبي للوكيل. مرر معرف قسم مثل `"llm"`، أو `"secrets"`،
+أو `"automations"`، أو `"voice"`، أو `"limits"` لفتح قسم معين.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+يُفضَّل هذا المساعد على إرسال `agent-panel:open-settings` مباشرة.
+
+## حالة سياق محادثة الوكيل {#agent-chat-context-state}
+
+واجهات برمجة حالة السياق هي أدوات ربط اختيارية لواجهة المستخدم التي تحتاج إلى مزامنة ثنائية الاتجاه مع شرائح السياق المرحلية: عرض العناصر المرحلية الحالية خارج المؤلف، أو إظهار ما إذا كان عنصر ما مرفقًا بالفعل، أو توفير عناصر تحكم صريحة للإزالة/المسح.
+
+لا تتجه إلى هذه الأدوات المساعدة لتدفقات "أرسل هذا إلى الوكيل" أو "عبّئ هذه المسودة مسبقًا للمراجعة" البسيطة. استخدم [`sendToAgentChat()`](#sendtoagentchat) مع `context` و`submit` لتلك الحالات.
+
+| API                               | استخدم عندما                                                                  |
+| --------------------------------- | ----------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | يحتاج مكون React إلى قائمة السياق المرحلية المباشرة                           |
+| `setAgentChatContextItem(item)`   | يجب أن يُهيّئ الكود الحتمي أو يستبدل عنصر سياق مفتاحي واحد                    |
+| `listAgentChatContext()`          | يحتاج الكود غير الخاص بـ React إلى لقطة لمرة واحدة للسياق المرحلي             |
+| `removeAgentChatContextItem(key)` | يجب أن تُزيل واجهة المستخدم عنصر سياق مرحلي واحد بواسطة `key` الثابت الخاص به |
+| `clearAgentChatContext()`         | يجب أن تمسح واجهة المستخدم كل السياق المرحلي، مثل بعد إعادة ضبط عرض أو وضع    |
+| `refreshAgentChatContext()`       | يجب أن يُعيد الكود الحتمي قراءة أحدث لقطة سياق مستمرة                         |
+
+تُعيد `useAgentChatContext()` `{ items, set, remove, clear, refresh }`.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` مخصصة للكود الحتمي الذي يحتاج فقط إلى فحص العناصر المرحلية الحالية مرة واحدة. `clearAgentChatContext()` واسعة عمدًا. استخدم `removeAgentChatContextItem(key)` عندما يتغير اختيار واحد فقط.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| الخيار        | النوع      | الوصف                                           |
+| ------------- | ---------- | ----------------------------------------------- |
+| `key`         | `string`   | معرِّف ثابت يُستخدم لاستبدال عنصر موجود         |
+| `title`       | `string`   | تسمية قصيرة تظهر في شريحة المؤلف                |
+| `context`     | `string`   | سياق مخفي يُضمَّن مع المطالبة التالية المُرسَلة |
+| `openSidebar` | `boolean?` | الافتراضي true. مرر false لتهيئة السياق بصمت    |
+
+## ما هي الخطوة التالية
+
+- [**نظرة عامة**](/docs/client-overview) — أين تتناسب هذه الأدوات المساعدة في `app/`
+- [**البيانات والمزامنة**](/docs/client-data) — خطافات actions و`useDbSync` التي تحافظ على تحديث واجهة المستخدم نفسها
+- [**وكيل الدخول**](/docs/drop-in-agent) — تثبيت `<AgentSidebar>`/`<AgentPanel>` حتى يكون لهذه الأدوات المساعدة مكان تُعرض فيه
+- [**متقدم**](/docs/client-advanced) — الإرسال في الخلفية، شرائح الاقتراحات المخصصة، وجسر استضافة MCP App
+- [**واجهة المستخدم التوليدية**](/docs/generative-ui) — بناء عناصر تحكم أكثر ثراءً مضمّنة في المحادثة تتجاوز `askUserQuestion`
diff --git a/packages/core/docs/content/locales/ar-SA/client-data.mdx b/packages/core/docs/content/locales/ar-SA/client-data.mdx
new file mode 100644
index 0000000000..a2447a98cc
--- /dev/null
+++ b/packages/core/docs/content/locales/ar-SA/client-data.mdx
@@ -0,0 +1,432 @@
+---
+title: "البيانات والمزامنة"
+description: "خطافات actions التي يستخدمها app/ للقراءة والكتابة والبقاء متزامنًا مباشرة مع نفس actions التي يستدعيها الوكيل."
+---
+
+# البيانات والمزامنة
+
+الطريقة الأساسية لقراءة بيانات التطبيق وكتابتها من تطبيق العميل هي من خلال خطافات [action](/docs/actions). من خلال تضمين الطلبات في actions، يمكن لعميلك ووكيلك التفاعل مع تطبيقك بالطريقة نفسها.
+
+في المثال أدناه، يتم تعيين تذكرة للمستخدم الحالي يدويًا من خلال قائمة منسدلة، ثم من خلال وكيل المحادثة. يصل كل من واجهة المستخدم والوكيل إلى نفس action.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="مثال على أن إجراء واجهة المستخدم وإجراء الوكيل يحققان نفس النتيجة."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="مثال على أن إجراء واجهة المستخدم وإجراء الوكيل يحققان نفس النتيجة."
+/>
+
+## جلب البيانات وتغييرها {#fetching-mutating}
+
+يبني التطبيق النموذجي طبقة API خاصة به ويستدعيها بطلبات `fetch` مكتوبة يدويًا. يتجاوز تطبيق الوكيل الأصلي هذه الطبقة: يستدعي `app/` نفس actions التي يمتلكها الوكيل بالفعل كأدوات، من خلال الخطافات أدناه.
+
+<Diagram id="doc-block-client-data-fm-1" title="fetch نموذجي مقابل خطاف action" summary="يستدعي المكون النموذجي مسارًا لا يمكن الوصول إليه إلا هو. يستدعي مكون الوكيل الأصلي action يمكن للوكيل استدعاؤه أيضًا.">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">نموذجي</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>مسار API الخاص بك</strong>
+      <small class="diagram-muted">فقط الواجهة الأمامية يمكنها استدعاءه</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>قاعدة البيانات</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">مقابل</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead action</span>
+      <small class="diagram-muted">أيضًا أداة وكيل</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>قاعدة بيانات SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### خطافات Action {#action-hooks}
+
+هناك خطافا action من الأرجح أن تستخدمهما: `useActionQuery()` و`useActionMutation()`. يوفر هذان الخطافان الوصول إلى actions تطبيقك.
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "الاسم المسجل لـ action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description: "مدخلات action، مكتوبة من مخطط `defineAction()` الخاص به.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "كل شيء من [خيارات useQuery](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) باستثناء `queryKey` و`queryFn`، التي يضبطها الخطاف نفسه.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      'مخزّن مؤقتًا تحت `["action", name, params]`. يُعاد جلبه تلقائيًا كل مرة تكتمل فيها action تُغيّر البيانات، دون الحاجة إلى إبطال يدوي.',
+  }}
+/>
+
+يُقصد استخدام هذا الخطاف مع actions للقراءة فقط. إنه غلاف رقيق حول دالة [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).
+
+في المثال أدناه، يتم استدعاء action `list-tickets`. هذا مشابه لإجراء طلب GET لجميع التذاكر.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+يوضح المثال التالي طلبًا لجلب تذكرة واحدة، من خلال action `get-ticket`. يتم تمرير `ticketId` لتحديد نطاق الاستعلام لإرجاع تذكرة معينة فقط. يتم توفير خيار `enabled` الإضافي للتأكد من أن الاستعلام لا يعمل تلقائيًا، وإنما يعمل فقط عند وجود `ticketId`.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "الاسم المسجل لـ action.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "كل شيء من [خيارات useMutation](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) باستثناء `mutationFn`، التي يضبطها الخطاف نفسه.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "يتجاوز طريقة الطلب الافتراضية.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "يلغي الاشتراك في إعادة تحديث ذاكرة التخزين المؤقت التلقائية عند النجاح.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'عند النجاح، يُصدر حدث تغيير بـ `source: "action"`، لذا تتم إعادة جلب كل `useActionQuery()` التي تقرأ البيانات المتأثرة تلقائيًا. لا حاجة إلى إبطال يدوي.',
+  }}
+/>
+
+يُقصد استخدام هذا الخطاف مع actions التي تغيّر البيانات، مثل الإنشاء أو التحديث أو الإرسال. إنه غلاف رقيق حول دالة [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation).
+
+على عكس `useActionQuery()`، لا يتم تمرير مدخلات action إلى الخطاف نفسه. يتم تمريرها إلى `mutate()` أو `mutateAsync()` عندما تكون جاهزًا لتشغيل الطفرة (mutation).
+
+في المثال أدناه، يتم استدعاء action `send-ticket-reply` لنشر رد على تذكرة. استدعِ `mutate()` من معالج حدث، مثل `onClick` لزر.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+يوضح المثال التالي نفس الطفرة مع خيار `onSuccess`. يحدث إبطال ذاكرة التخزين المؤقت تلقائيًا بعد كل طفرة، لذا لا يُحتاج إلى `onSuccess` إلا للتأثيرات الجانبية المحلية، مثل مسح مؤلف الرد بعد إرسال الرد.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "الاسم المسجل لـ action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description: "مدخلات action، مكتوبة من مخطط `defineAction()` الخاص به.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "كل ما يلي اختياري.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "يتجاوز طريقة الطلب الافتراضية.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "يلغي الطلب.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "يتجاوز المهلة الافتراضية البالغة 60 ثانية، لـ actions التي تستغرق وقتًا أطول بشكل مشروع.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "على عكس الخطافات أعلاه، لا توجد ذاكرة تخزين مؤقت ولا إعادة جلب تلقائية. اقرنه بإبطال يدوي إذا كانت واجهة مستخدم أخرى تعتمد على النتيجة.",
+  }}
+/>
+
+هذه الدالة مخصصة لاستدعاءات action الفورية لمرة واحدة خارج تدفق عرض React، مثل معالج حدث عادي، أو نص برمجي، أو أي مسار كود آخر غير React. تُرجع وعدًا (promise) مباشرة بدلاً من نتيجة خطاف.
+
+في المثال أدناه، يتم استدعاء action `update-ticket` من معالج اختصار لوحة مفاتيح خارج تدفق عرض React، لتعيين التذكرة لممثل.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+يوضح المثال التالي نفس الاستدعاء مع خيار `timeoutMs`، وهو مفيد لـ actions التي تستغرق وقتًا أطول بشكل مشروع من المهلة الافتراضية البالغة 60 ثانية.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+كل طلب من `useActionQuery()` و`useActionMutation()` و`callAction()` محكوم بمهلة 60 ثانية، وتظهر انتهاءات المهلة كأخطاء بدلاً من إعادة المحاولة بصمت. يلغي `useActionQuery()` أيضًا الطلبات المتجاوَزة تلقائيًا، باستخدام إشارة الإلغاء (abort signal) الخاصة بـ React Query.
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "كل حقل اختياري.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "عميل React Query المستخدم لإبطال ذاكرة التخزين المؤقت.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "عنوان URL لنقطة نهاية الاستقصاء.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "عنوان URL لنقطة نهاية SSE. مرر `false` لاستخدام الاستقصاء فقط.",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "الفاصل الزمني للاستقصاء بالمللي ثانية.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "فاصل الاستقصاء بينما يكون SSE متصلاً، كنسخة احتياطية في حال فوات حدث. تستطلع علامة التبويب غير المتصلة بمعدل أسرع `interval` (أو معدل خمول ثابت) بدلاً من ذلك.",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "إيقاف الاستقصاء مؤقتًا عندما تكون علامة تبويب المتصفح مخفية. تحافظ العلامات المخفية على اتصال SSE وتستطلع بمعدل لا يتجاوز كل 10 ثوانٍ أثناء النشاط، و60 ثانية عند الخمول.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "مصدر طلب لكل علامة تبويب يتم تجاهله، لذا لا تعيد علامة التبويب الجلب من عمليات الكتابة الخاصة بها.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "استدعاء اختياري عندما يستقبل SSE أو الاستقصاء حدث تغيير.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "يُصفّي الإبطال الواسع الذي يُحرّكه حدث action. نادرًا ما يُحتاج إليه. استخدمه للحفاظ على استعلام نشط مكلف على قواعد التحديث اليدوي الصريح بينما لا تزال الاستعلامات ذات المصدر المُرقّم العادية تتفاعل من خلال `useChangeVersion`.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "أسماء actions التي لا ينبغي لأحداث مزامنتها إبطال جميع استعلامات actions. فقط لـ actions ذات الحجم الكبير في الخلفية التي تنفذ إبطالًا ضيقًا خاصًا بها.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description: "مهمَل ومتجاهَل. تم الاحتفاظ به لمواقع الاتصال القديمة.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+يُقصد استخدام هذا الخطاف للحفاظ على واجهة المستخدم متزامنة مع تغييرات قاعدة البيانات التي تحدث خارج actions الخاصة بك، مثل كتابة من الوكيل، أو خطاف ويب (webhook)، أو تغيير تم إجراؤه من علامة تبويب متصفح أخرى. يستمع للتغييرات عبر الأحداث المرسلة من الخادم، ويعود إلى الاستقصاء عندما لا تكون الأحداث المرسلة من الخادم متاحة.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+بالنسبة إلى CRUD العادي، يُفضَّل `useActionQuery()` و`useActionMutation()`. تُصدر actions المُغيّرة `source: "action"`، لذا تُعيد هذه الخطافات الجلب فورًا. تصل التغييرات من الوكيل، أو خطاف ويب، أو علامة تبويب أخرى من خلال `useDbSync()` بدلاً من ذلك، عبر SSE أو الرجوع إلى الاستقصاء. إذا كان استعلام `useQuery()` خام يحتاج إلى المزامنة على مفتاح مخصص، راجع [آليات المزامنة الداخلية](/docs/client-sync-internals). إذا كنت تحتاج إلى الكتابة مباشرة إلى `application_state`، راجع [متقدم](/docs/client-advanced).
+
+## ما هي الخطوة التالية
+
+- [**نظرة عامة**](/docs/client-overview) — تخطيط دليلَي `app/` و`public/` الذي تعيش فيه خطافات هذه الصفحة
+- [**محادثة الوكيل**](/docs/client-agent-chat) — إرسال المطالبات وتهيئة السياق للوكيل
+- [**Actions**](/docs/actions) — سطح `defineAction` الذي يقف خلف كل خطاف في هذه الصفحة
+- [**متقدم**](/docs/client-advanced) — الوصول المباشر إلى `application_state`
+- [**آليات المزامنة الداخلية**](/docs/client-sync-internals) — مزامنة `useQuery` خام باستخدام `useChangeVersion`
+- [**المزامنة المباشرة**](/docs/key-concepts#polling-sync) — كيف يحافظ `useDbSync` على تحديث واجهة المستخدم
diff --git a/packages/core/docs/content/locales/ar-SA/client-entry-points.mdx b/packages/core/docs/content/locales/ar-SA/client-entry-points.mdx
new file mode 100644
index 0000000000..00ddc9634b
--- /dev/null
+++ b/packages/core/docs/content/locales/ar-SA/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "نقاط الدخول"
+description: "app/entry.client.tsx وapp/entry.server.tsx: أغلفة الترطيب (hydration) وإقلاع SSR الرقيقة، ومتى تُخصِّص سلوك البث (streaming)."
+---
+
+# نقاط الدخول
+
+يُرطِّب (hydrates) `app/entry.client.tsx` كود HTML المُصيَّر من جانب الخادم في المتصفح، ويُصيِّر `app/entry.server.tsx` ذلك الـ HTML على الخادم. كلاهما أغلفة رقيقة تُولِّدها React Router. نادرًا ما تحتاج إلى تحريرهما.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+استخدم هذه فقط لتخصيص SSR المتقدم، على سبيل المثال تغيير سلوك البث. الصفحات، والتخطيط، والبيانات العادية لا تحتاج إلى تغييرات هنا. راجع [التوجيه](/docs/client-routing) لإضافة صفحات بدلًا من ذلك.
+
+## ما هي الخطوة التالية
+
+- [**نظرة عامة**](/docs/client-overview) — أين تقع هذه الملفات في `app/`
+- [**التوجيه**](/docs/client-routing) — إضافة صفحات، الطريقة العادية لتوسيع `app/`
+- [**متقدم**](/docs/client-advanced) — البدائيات الأخرى ذات المستوى الأدنى ومخارج الطوارئ الخاصة بالعميل
diff --git a/packages/core/docs/content/locales/ar-SA/client-overview.mdx b/packages/core/docs/content/locales/ar-SA/client-overview.mdx
new file mode 100644
index 0000000000..03ecbd6664
--- /dev/null
+++ b/packages/core/docs/content/locales/ar-SA/client-overview.mdx
@@ -0,0 +1,206 @@
+---
+title: "نظرة عامة"
+description: "دليلا `app/` و`public/`: حيث تبني عرض تطبيق الوكيل الأصلي، وواجهات برمجة المتصفح التي يستخدمها للبقاء متزامنًا مع الوكيل."
+---
+
+# نظرة عامة
+
+`app/` هو المكان الذي تبني فيه العرض الفعلي لتطبيق وكيل أصلي: الصفحات، والتخطيط، والمكونات، والأنماط. يحتوي `public/` على الأصول الثابتة التي تُقدَّم بجانبه - الأيقونات، وملف البيان (manifest)، وعلامات الهوية التجارية. هذا تطبيق React Router v8 عادي، لا سطح خاص بالوكيل فقط، وهو المكان الذي يذهب إليه معظم وقت التطوير.
+
+الاختلاف المعماري الوحيد عن الواجهة الأمامية العادية: هذه الطبقة لا تمتلك خلفية خاصة بالواجهة الأمامية (backend-for-frontend) من تلقاء نفسها. إنها تقرأ وتكتب البيانات من خلال نفس actions التي يستدعيها الوكيل، لذا فإن أي شيء يتم توصيله هنا يصبح تلقائيًا شيئًا يمكن للوكيل القيام به أيضًا.
+
+<Diagram id="doc-block-client-overview-1" title="الواجهة الأمامية التقليدية مقابل الوكيل الأصلي" summary="تستدعي الواجهة الأمامية التقليدية طبقة API الخاصة بها، التي لا يصل إليها إلا هي. في Agent Native، يستدعي app/ والوكيل نفس actions، لذا تصبح كل قدرة تُبنى هنا قابلة للاستدعاء من الوكيل مجانًا.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">تقليدي</div>
+    <div class="diagram-node">app/ (واجهة React الأمامية)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>طبقة API</strong>
+      <small class="diagram-muted">فقط الواجهة الأمامية تستدعيها</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>قاعدة البيانات</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">مقابل</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (واجهة React الأمامية)</div>
+      <div class="diagram-node">الوكيل</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">شريكان متساويان، العمليات نفسها</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>قاعدة بيانات SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## أين يتناسب العميل {#role}
+
+تتحول طلبات المتصفح، وحلقة الوكيل، وعملاء API الخارجيون جميعًا إلى نفس actions ونفس قاعدة بيانات SQL - لا توجد "خلفية تطبيق" منفصلة تتحدث معها هذه الطبقة ولا يستطيع الوكيل الوصول إليها أيضًا. بناء ميزة هنا يعني بناء واجهة مستخدم فوق عملية يمتلكها الوكيل بالفعل، أو تعريف action جديد والحصول على واجهة مستخدم له في الوقت نفسه. راجع [Actions](/docs/actions) للتعرف على جانب العملية من هذا العقد.
+
+تغطي هذه الصفحة الدلائل التي تبني فيها والأجزاء من وقت تشغيل المتصفح التي لا توثقها أي صفحة أخرى (`root.tsx`، `public/`). خطافات React التي تربط مكوناتك بـ actions وبالوكيل تعيش في صفحاتها المخصصة الخاصة بها:
+
+| الصفحة                                                     | ما تغطيه                                                                                                             |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| **[البيانات والمزامنة](/docs/client-data)**                | `useActionQuery`، `useActionMutation`، `callAction`، و`useDbSync`                                                    |
+| **[محادثة الوكيل](/docs/client-agent-chat)**               | `sendToAgentChat`، `askUserQuestion`، `openAgentSettings`، الاقتراحات الديناميكية، وحالة سياق محادثة الوكيل المرحلية |
+| **[متقدم](/docs/client-advanced)**                         | الوصول المباشر إلى `application_state`، إرسال محادثة في الخلفية، شرائح اقتراحات مخصصة، وجسر استضافة MCP App          |
+| **[آليات المزامنة الداخلية](/docs/client-sync-internals)** | `useChangeVersion`/`useChangeVersions` لمزامنة `useQuery` خام                                                        |
+| **[نقاط الدخول](/docs/client-entry-points)**               | `app/entry.client.tsx`/`app/entry.server.tsx` وتخصيص SSR                                                             |
+
+## ما يوجد في app/ وpublic/ {#project-directories}
+
+| المسار                                              | ما يغطيه                                                                                                                            |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | غلاف HTML ومجموعة الموفرات (providers) - راجع [غلاف المتصفح](#app-shell) أدناه                                                      |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | إقلاع الترطيب (hydration) وSSR - راجع [نقاط الدخول](/docs/client-entry-points)                                                      |
+| **`app/routes.ts` + `app/routes/`**                 | الصفحات المستندة إلى الملفات والتنقل - راجع [التوجيه](/docs/client-routing)                                                         |
+| **`app/components/`**                               | واجهة المستخدم الخاصة بك: عناصر أساسية بأسلوب shadcn بالإضافة إلى مكونات خاصة بالتطبيق - راجع [shadcn/ui](/docs/shadcn-ui)          |
+| **`app/hooks/`**                                    | خطافات البيانات، والمزامنة، ومحادثة الوكيل - راجع [البيانات والمزامنة](/docs/client-data) و[محادثة الوكيل](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | أدوات مساعدة مشتركة للعميل (تكوين التطبيق، معرف اللسان (tab id)، `cn`) - راجع [الأدوات المساعدة](#utilities) أدناه                  |
+| **`app/design-system.ts`**                          | محول نظام تصميم مخصص اختياري - راجع [أنظمة التصميم المخصصة](/docs/custom-design-system)                                             |
+| **`app/i18n/`**                                     | كتالوجات نصوص واجهة المستخدم المترجمة - راجع [التدويل](/docs/internationalization)                                                  |
+| **`app/global.css`**                                | الأنماط الأساسية ونقطة دخول Tailwind                                                                                                |
+| **`public/`**                                       | الأصول الثابتة التي تُقدَّم كما هي - راجع [الأصول الثابتة](#public-directory) أدناه                                                 |
+
+## غلاف المتصفح: root.tsx وAppProviders {#app-shell}
+
+`app/root.tsx` هو أعلى شجرة React: غلاف مستند HTML (`<html>`، `<head>`، `<Meta>`، `<Links>`، `<Scripts>`) بالإضافة إلى مجموعة الموفرات التي يتم عرضها داخل كل مسار.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` هو الغلاف الوحيد الذي يوصل:
+
+- عميل React Query الذي يستخدمه `useActionQuery`/`useActionMutation` (راجع [البيانات والمزامنة](/docs/client-data#fetching-mutating)).
+- كتالوج i18n الذي يتم تمريره كـ `i18n.catalog` (راجع [التدويل](/docs/internationalization)).
+- فحوصات الجلسة من جانب العميل: في مسار خاص، تتم إعادة توجيه الزائر المجهول إلى تسجيل الدخول قبل تحميل أي واجهة مستخدم خاصة. مرر `isPublicPath` للمسارات العامة/الخاصة بتحسين محركات البحث، أو `sessionBypass` لسطح يتم مصادقته بطريقة أخرى، مثل رمز تضمين MCP. راجع [المصادقة](/docs/authentication).
+
+تقوم معظم التطبيقات أيضًا بتثبيت `<AgentSidebar>` أو `<AgentPanel>` هنا حتى يحصل كل مسار على لوحة الوكيل مجانًا. راجع [وكيل الدخول](/docs/drop-in-agent#sidebar).
+
+## الأصول الثابتة: public/ {#public-directory}
+
+كل ما في `public/` يتم تقديمه كما هو عند جذر الموقع، دون معالجة من عملية البناء. يشحن كل قالب:
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+يتحكم `manifest.json` في ما يظهر إذا قام الزائر بتثبيت التطبيق على شاشة رئيسية أو رصيف تطبيقات - الاسم، والاسم المختصر، وألوان السمة/الخلفية، ومجموعة الأيقونات:
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+أعد تصميم هوية التطبيق عن طريق استبدال هذه الملفات وتحديث `manifest.json` وعلامات `<link rel="icon">`/`<link rel="apple-touch-icon">` في `root.tsx` التي تشير إليها - لا توجد خطوة تسجيل منفصلة. لسحب نظام هوية تجارية كامل (الألوان، والخطوط، وأيقونة المفضلة) من موقع موجود بدلاً من تحرير هذه الملفات يدويًا، راجع [أنظمة الهوية التجارية وFigma](/docs/template-design-brand-and-figma).
+
+## الأدوات المساعدة: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+يقوم `cn` بدمج أسماء الفئات (clsx + tailwind-merge) وهو الطريقة القياسية لتركيب فئات Tailwind الشرطية عبر `app/components/`.
+
+## ما هي الخطوة التالية
+
+- [**البيانات والمزامنة**](/docs/client-data) — خطافات actions و`useDbSync`
+- [**محادثة الوكيل**](/docs/client-agent-chat) — `sendToAgentChat`، `askUserQuestion`، والاقتراحات الديناميكية
+- [**متقدم**](/docs/client-advanced) — حالة التطبيق، إرسال المحادثة في الخلفية، وجسر استضافة MCP App
+- [**آليات المزامنة الداخلية**](/docs/client-sync-internals) — `useChangeVersion` لمزامنة `useQuery` خام
+- [**نقاط الدخول**](/docs/client-entry-points) — تخصيص إقلاع SSR
+- [**التوجيه**](/docs/client-routing) — الصفحات المستندة إلى الملفات، والمعلمات الديناميكية، والتنقل
+- [**Actions**](/docs/actions) — سطح `defineAction` الذي يقف خلف كل خطاف بيانات
+- [**أنظمة التصميم المخصصة**](/docs/custom-design-system) — استبدال مكتبة المكونات الخاصة بك عبر `app/design-system.ts`
+- [**المصادقة**](/docs/authentication) — فحوصات الجلسة التي يقوم بها `AppProviders` في المسارات الخاصة
diff --git a/packages/core/docs/content/locales/ar-SA/client-routing.mdx b/packages/core/docs/content/locales/ar-SA/client-routing.mdx
new file mode 100644
index 0000000000..a5552c06c3
--- /dev/null
+++ b/packages/core/docs/content/locales/ar-SA/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "التوجيه"
+description: "التوجيه المستند إلى الملفات لتطبيقات الوكيل الأصلية باستخدام React Router v8: الصفحات والمعلمات الديناميكية والتنقل."
+---
+
+# التوجيه
+
+تستخدم تطبيقات الوكيل الأصلية **React Router v8** مع التوجيه المستند إلى الملف عبر `flatRoutes()` من `@react-router/fs-routes`. كل ملف في `app/routes/` يصبح عنوان URL. تستخدم القوالب اصطلاح التدوين النقطي. تفصل النقاط مقاطع URL داخل اسم ملف واحد.
+
+تغطي هذه الصفحة مسارات العميل، الصفحات التي تُعرَض في المتصفح من `app/routes/`. مسارات الخادم نظام منفصل: مسارات ملفات Nitro تحت `server/routes/`، بالإضافة إلى نقاط نهاية إطار العمل الخاصة `/_agent-native/*`. تعيش تلك في صفحة [المسارات](/docs/server-routes). لا يتشارك الاثنان دليلًا، أو اصطلاح تسمية، أو موجِّهًا، لذا لا يصبح ملف `server/routes/` صفحة هنا أبدًا ولا يصبح ملف `app/routes/` نقطة نهاية خادم أبدًا.
+
+<Diagram id="doc-block-client-routing-1" title="اسم الملف ← URL" summary="يصبح كل ملف في app/routes/ عنوان URL. تتحول النقاط إلى شرطات مائلة، ويصبح مقطع $ معلمة ديناميكية.">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## التوجيه المستند إلى الملف {#file-based-routing}
+
+### ملف ← تعيين URL
+
+| الملف                      | URL                    | ملاحظات                                                                             |
+| -------------------------- | ---------------------- | ----------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | مسار الفهرس                                                                         |
+| `dashboard.tsx`            | `/dashboard`           | صفحة بسيطة                                                                          |
+| `extensions.$id.tsx`       | `/extensions/:id`      | يتداخل داخل `<Outlet/>` الخاص بـ `extensions.tsx`. `$` هو معلمة ديناميكية           |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | الشرطة السفلية اللاحقة `_` تتخطى التداخل تحت `dashboard.tsx`، لذا هذه صفحتها الخاصة |
+| `_app.tsx`                 | (لا يوجد مقطع URL)     | تخطيط بلا مسار. البادئة بـ `_`                                                      |
+| `inbox/route.tsx`          | `/inbox`               | نموذج المجلد. `route.tsx` هو الفهرس                                                 |
+
+ضع بادئة لمقطع بـ `$` لمعلمة ديناميكية. ضع بادئة بـ `_` لجعله مسار تخطيط بلا مسار (لا يوجد مقطع URL)، أو أضف شرطة سفلية لاحقة `_` قبل نقطة لاستثناء مسار يبدو متداخلًا من التداخل تحت تخطيط والده. تستخدم القوالب `flatRoutes()`. ملف التدوين النقطي أعلاه هو الأساسي. يعمل أيضًا نموذج المجلد المتداخل `inbox/route.tsx`.
+
+## إضافة صفحة جديدة {#adding-a-page}
+
+أنشئ الملف وصدِّر مكونًا افتراضيًا:
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+هذا كل شيء. يستلمها React Router تلقائيًا، دون الحاجة إلى تسجيل.
+
+## المعلمات الديناميكية {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+تحافظ الشرطة السفلية اللاحقة `_` قبل النقطة على عدم تداخل هذه الصفحة داخل `<Outlet/>` الخاص بـ `dashboard.tsx`، لذا تُعرَض كصفحة كاملة خاصة بها عند `/dashboard/:ticketId` بدلاً من الظهور داخل تخطيط قائمة التذاكر.
+
+## التنقل {#navigation}
+
+استخدم `<Link>` للتنقل من جانب العميل و`useNavigate()` للتنقل البرمجي:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+لا يخبر أي منهما الوكيل بمفرده بما ينظر إليه المستخدم. هذا اهتمام منفصل، تتم معالجته من خلال `useAgentRouteState()` الذي يكتب المسار الحالي إلى حالة التطبيق. راجع [الوعي بالسياق](/docs/context-awareness).
+
+## ما هي الخطوة التالية
+
+- [**نظرة عامة**](/docs/client-overview) — أين يتناسب `app/routes/` بين بقية `app/` و`public/`
+- [**البيانات والمزامنة**](/docs/client-data) — قراءة وكتابة البيانات من داخل مسار
+- [**محادثة الوكيل**](/docs/client-agent-chat) — إرسال المطالبات وتهيئة السياق من مسار
+- [**المسارات**](/docs/server-routes) — نظام توجيه الخادم المنفصل: مسارات الملفات تحت `server/routes/` ومساحة الاسم `/_agent-native/` الخاصة بإطار العمل
+- [**الوعي بالسياق**](/docs/context-awareness) — كيف يتعلم الوكيل المسار والتحديد الحاليين
diff --git a/packages/core/docs/content/locales/ar-SA/client-sync-internals.mdx b/packages/core/docs/content/locales/ar-SA/client-sync-internals.mdx
new file mode 100644
index 0000000000..544f091bf2
--- /dev/null
+++ b/packages/core/docs/content/locales/ar-SA/client-sync-internals.mdx
@@ -0,0 +1,124 @@
+---
+title: "آليات المزامنة الداخلية"
+description: "آلية إصدار التغيير خلف useDbSync: useChangeVersion/useChangeVersions لمزامنة useQuery خام، والمساران اللذان يمكن أن تسلكهما إعادة الجلب."
+---
+
+# آليات المزامنة الداخلية
+
+تغطي [المزامنة المباشرة](/docs/key-concepts#polling-sync) النموذج المفهومي: تصبح كتابة الوكيل حدث تغيير، ويلتقطها `useDbSync()`، وتُعاد جلب الاستعلامات المتأثرة. تغطي هذه الصفحة الآلية التي تقف تحتها والتي لا تلمسها معظم التطبيقات مباشرة أبدًا: عدّادات إصدار التغيير التي تُصعِّدها `useDbSync()`، وكيفية دمجها في استدعاء `useQuery()` خام لا يمر عبر `useActionQuery()`.
+
+تُعيد `useActionQuery()` الجلب تلقائيًا بالفعل عندما تكتمل action تُغيِّر البيانات (راجع [البيانات والمزامنة](/docs/client-data#fetching-mutating)). استخدم `useChangeVersion()`/`useChangeVersions()` فقط عندما تُزامن استدعاء `useQuery()` خام خارج ذلك المسار، مثل أداة مساعدة عميل ذات مستوى منخفض تقرأ حالة تكامل.
+
+## كيف تعمل إصدارات التغيير {#how-it-works}
+
+عندما تحدث طفرة قاعدة بيانات من جانب الخادم، يسجل الخادم حدث تغيير مُعلَّمًا بمفتاح `source`. تستقبل `useDbSync()` ذلك الحدث وتُصعِّد عدادًا محليًا لذلك المصدر. يجعل دمج العداد في مفتاح استعلام React الاستعلام يُعيد الجلب تلقائيًا كل مرة يُعلن فيها الواجهة الخلفية عن نشاط جديد لذلك المصدر.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description: 'مصدر حدث التغيير المطلوب مراقبته، مثل `"dashboards"`.',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "عدّاد يتصاعد كل مرة يتم تغيير المصدر المحدد.",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "مصادر حدث تغيير متعددة لمراقبتها في آنٍ واحد.",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "مجموع عدادات الإصدار لكل مصدر مُعطى.",
+  }}
+/>
+
+في المثال أدناه، يقرأ استدعاء `useQuery()` خام لوحة معلومات مباشرة، مع دمج عداد إصدار مصدر `"dashboards"` في مفتاح استعلامه حتى يُعيد الجلب كل مرة يتغير ذلك المصدر:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+يحافظ `placeholderData: (prev) => prev` على البيانات السابقة على الشاشة أثناء إعادة الجلب، لذا لا يرمش العرض إلى حالة تحميل.
+
+## مساران لإعادة الجلب {#latency-models}
+
+تصل الطفرة إلى واجهة المستخدم بأحد طريقين، ولهما زمن انتقال مختلف.
+
+الطفرة المحلية، وهي طفرة أجراها استدعاء `useActionMutation()` الخاص بك للتو، تُصدر حدث `source: "action"` بمجرد نجاحها. تُعيد كل استعلام يعتمد على تلك action الجلب فورًا. لا يوجد تأخير في الرحلة ذهابًا وعودة، لأن علامة التبويب التي أجرت الكتابة تعرف بها بالفعل.
+
+الطفرة البعيدة، من الوكيل، أو خطاف ويب، أو علامة تبويب أخرى، أو مستخدم آخر، يجب أن تصل إلى علامة التبويب هذه أولًا. تلتقطها `useDbSync()` عبر SSE على الفور تقريبًا، أو عبر الرجوع إلى الاستقصاء في غضون ثانيتين تقريبًا إذا لم يكن SSE متاحًا. فقط بعد وصول ذلك الحدث يتصاعد عداد الإصدار ذو الصلة ويُعاد جلب الاستعلام في الخلفية.
+
+<Diagram id="doc-block-client-sync-internals-3" title="مساران لإعادة الجلب" summary="تُبطل الطفرة المحلية ذاكرتها التخزينية فورًا. تصل الكتابة البعيدة إلى علامة التبويب هذه عبر SSE، أو دورة الاستقصاء كنسخة احتياطية.">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">علامة التبويب هذه</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >تُصدر source: "action" عند النجاح &rarr; إعادة جلب محلية فورية</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent"
+        >الوكيل · خطاف ويب · علامة تبويب أخرى</span
+      ><strong>كتابة بعيدة</strong
+      ><small class="diagram-muted"
+        >دفع SSE، أو دورة الاستقصاء كل ~2 ثانية كنسخة احتياطية &rarr; يتصاعد
+        الإصدار &rarr; إعادة جلب في الخلفية</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## ما هي الخطوة التالية
+
+- [**المزامنة المباشرة**](/docs/key-concepts#polling-sync) — النموذج المفهومي الذي تقف هذه الصفحة تحته
+- [**البيانات والمزامنة**](/docs/client-data) — `useActionQuery`/`useDbSync`، التي ينبغي أن تستخدمها معظم الصفحات بدلًا من هذه البدائيات
+- [**متقدم**](/docs/client-advanced) — البدائيات الأخرى ذات المستوى الأدنى ومخارج الطوارئ الخاصة بالعميل
diff --git a/packages/core/docs/content/locales/ar-SA/client.mdx b/packages/core/docs/content/locales/ar-SA/client.mdx
deleted file mode 100644
index 85f370242f..0000000000
--- a/packages/core/docs/content/locales/ar-SA/client.mdx
+++ /dev/null
@@ -1,471 +0,0 @@
----
-title: "العميل"
-description: "الخطافات والأدوات المساعدة React لتطبيقات الوكيل الأصلية: sendToAgentChat، وحالة سياق دردشة الوكيل الاختيارية، وuseDbSync، وuseAgentChatGenerating، وcn."
----
-
-# العميل
-
-يوفر `@agent-native/core` أدوات ربط وأدوات مساعدة React لجانب المتصفح لتطبيقات الوكيل الأصلية.
-
-يتم تصدير هؤلاء العملاء/React API من `@agent-native/core` و`@agent-native/core/client`. قم باستيرادها من `@agent-native/core/client` (إدخال المتصفح) للحصول على الوضوح والتجميع الصحيح، نظرًا لأن جذر `@agent-native/core` المجرد يتحول إلى إنشاء Node افتراضيًا.
-
-بالنسبة للتوجيه المستند إلى الملف - إضافة الصفحات والمعلمات الديناميكية والتنقل - راجع [Routing](/docs/routing).
-
-## جلب البيانات وتغييرها {#fetching-mutating}
-
-الطريقة الأساسية لقراءة بيانات التطبيق وكتابتها من المتصفح هي من خلال خطافات الإجراء. لا تكتب أبدًا مكالمات `fetch` يدويًا إلى مسارات `/_agent-native/*` - استخدم المساعدين المحددين بدلاً من ذلك (راجع [Actions](/docs/actions)).
-
-<Diagram id="doc-block-12sq7bk" title={"حلقة بيانات المتصفح"} summary={"خطافات القراءة والكتابة من خلال الإجراءات؛ يراقب useDbSync قاعدة البيانات حتى يقوم الوكيل والخلفية بإعادة جلب نفس ذاكرات التخزين المؤقت تلقائيًا."}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">قراءة مخبأة</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted">كتابة + إبطال</small>
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough>
-    <strong>SQL قاعدة البيانات</strong>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; الإعادة على التغيير</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(opts) {#sendtoagentchat}
-
-أرسل رسالة إلى دردشة الوكيل عبر postMessage — الطريقة الشائعة لتفويض مهمة الذكاء الاصطناعي من تفاعل UI. مرر `context` لسياق النموذج المخفي و`submit: true` للإرسال فورًا، أو `submit: false` لملء مسودة مراجعات المستخدم أولاً مسبقًا.
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-داخل تطبيق MCP المضمن الذي تم إنشاؤه باستخدام `embedApp()`، الرسائل المرسلة تلقائيًا
-(تم حذف `submit` أو `true`) إلى جسر مضيف تطبيق MCP، والذي
-يطلب من المضيف المحتوي إضافة سياق مخفي وإرسال الدور المرئي للمستخدم.
-يظل `context` مرئيًا للنموذج دون نشره كدردشة مع المستخدم.
-يحتفظ `submit: false` بسلوك التعبئة المسبقة/المراجعة المحلي لأن تطبيقات MCP لا تفعل ذلك
-حدد مسودة قياسية للتعبئة المسبقة API. داخليًا، هذا هو مسار الدردشة المرسلة
-يظهر أحيانًا كـ `agentNative.submitChat`؛ يجب أن يتصل رمز التطبيق
-`sendToAgentChat()` بدلاً من نشر هذا الحدث مباشرةً.
-
-### يتم إرسال الخلفية الصامتة {#background-send}
-
-استخدم `background: true` عندما يؤدي إجراء UI إلى بدء عمل الوكيل الحقيقي بدون
-فتح الشريط الجانبي أو التركيز عليه. لا يزال هذا يؤدي إلى إنشاء سلسلة محادثات/تشغيل عادي،
-يستخدم أدوات الوكيل/actions/السياق، ويحافظ على إمكانية ملاحظة العمل من خلال
-علبة التشغيل؛ إنها ليست دعوة نموذجية خام لمرة واحدة.
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-تم تصميم `background` ليتم إقرانه مع `newTab` حتى لا يتم إقران العمل المخفي
-الكتابة فوق المحادثة النشطة للمستخدم. استخدم `tabId` الذي تم إرجاعه إذا كان UI
-يحتاج إلى ربط حالة المتابعة أو الارتباط العميق بالتشغيل لاحقًا.
-
-### AgentChatMessage {#agentchatmessage}
-
-| الخيار                | اكتب        | الوصف                                                                                    |
-| --------------------- | ----------- | ---------------------------------------------------------------------------------------- |
-| `message`             | `string`    | تم إرسال المطالبة المرئية إلى الدردشة                                                    |
-| `context`             | `string?`   | تم إلحاق السياق المخفي (لا يظهر في الدردشة UI)                                           |
-| `submit`              | `boolean?`  | صحيح = إرسال تلقائي، خطأ = تعبئة مسبقة فقط                                               |
-| `newTab`              | `boolean?`  | قم بإنشاء سلسلة محادثات منفصلة لهذه المطالبة                                             |
-| `background`          | `boolean?`  | باستخدام `newTab`، قم بالتشغيل دون التركيز على علامة التبويب وأظهر التشغيل في `RunsTray` |
-| `openSidebar`         | `boolean?`  | قم بتعيين خطأ للإرسال/التعبئة المسبقة دون فتح الشريط الجانبي                             |
-| `projectSlug`         | `string?`   | الارتباط الثابت للمشروع الاختياري للسياق المنظم                                          |
-| `preset`              | `string?`   | اسم اختياري محدد مسبقًا للمستهلكين النهائيين                                             |
-| `referenceImagePaths` | `string[]?` | مسارات الصور المرجعية الاختيارية                                                         |
-
-## حالة سياق محادثة الوكيل (متقدمة) {#agent-chat-context-state}
-
-تُعتبر حالة السياق API عبارة عن توصيلات اختيارية لـ UI والتي تحتاج إلى مزامنة ثنائية الاتجاه مع
-شرائح السياق المرحلية: عرض العناصر المرحلية الحالية خارج المؤلف
-يعكس ما إذا كان العنصر مرفقًا بالفعل، أو يقدم توضيحًا واضحًا
-إزالة/مسح عناصر التحكم.
-
-لا تتواصل مع هؤلاء المساعدين لمجرد "إرسال هذا إلى الوكيل" أو
-تدفقات "ملء هذه المسودة مسبقًا للمراجعة". استخدم `sendToAgentChat()` مع `context`
-و`submit` لهؤلاء.
-
-| API                               | استخدم عندما                                                                   |
-| --------------------------------- | ------------------------------------------------------------------------------ |
-| `useAgentChatContext()`           | يحتاج مكون React إلى قائمة السياقات المرحلية المباشرة                          |
-| `setAgentChatContextItem(item)`   | يجب أن تقوم التعليمات البرمجية الحتمية بتشغيل أو استبدال عنصر سياق مفتاحي واحد |
-| `listAgentChatContext()`          | تحتاج التعليمات البرمجية غير React إلى لقطة واحدة للسياق المرحلي               |
-| `removeAgentChatContextItem(key)` | يجب على UI إزالة عنصر سياق مرحلي واحد بواسطة `key` المستقر                     |
-| `clearAgentChatContext()`         | يجب أن يقوم UI بمسح كل السياق المرحلي، مثل بعد إعادة ضبط العرض أو الوضع        |
-| `refreshAgentChatContext()`       | يجب أن تعيد التعليمات البرمجية الحتمية قراءة أحدث لقطة للسياق المستمر          |
-
-ترجع `useAgentChatContext()` `{ items, set, remove, clear, refresh }`.
-
-## openAgentSettings(القسم؟) {#openagentsettings}
-
-استخدم `openAgentSettings()` عند فتح صفحة إعدادات التطبيق أو بطاقة الإعداد
-علامة التبويب إعدادات الشريط الجانبي للوكيل. قم بتمرير معرف قسم مثل `"llm"`، `"secrets"`،
-`"automations"` أو `"voice"` أو `"limits"` لفتح قسم معين.
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-تفضل هذا المساعد على إرسال `agent-panel:open-settings` مباشرة.
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` مخصص للتعليمات البرمجية الحتمية التي تحتاج فقط إلى فحص
-العناصر المرحلية الحالية مرة واحدة. `clearAgentChatContext()` واسع عمدًا؛ استخدم
-`removeAgentChatContextItem(key)` عند تغيير تحديد واحد فقط.
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| الخيار        | اكتب       | الوصف                                                 |
-| ------------- | ---------- | ----------------------------------------------------- |
-| `key`         | `string`   | معرف ثابت يستخدم لاستبدال كتلة صلبة موجودة            |
-| `title`       | `string`   | تظهر التسمية القصيرة في شريحة الملحن                  |
-| `context`     | `string`   | سياق مخفي مضمن في المطالبة التالية التي تم إرسالها    |
-| `openSidebar` | `boolean?` | الافتراضيات صحيحة؛ قم بتمرير خطأ إلى سياق المسرح بصمت |
-
-## askUserQuestion(opts) {#ask-user-question}
-
-اطرح على المستخدم سؤالاً متعدد الاختيارات من رمز التطبيق، واجعله مضمنًا في
-لوحة الوكلاء، و**انتظر إجابتهم**. إنه التوأم من جانب العميل
-أداة `ask-question` المدمجة للوكيل: تكتب `GuidedQuestionPayload` إلى
-مفتاح حالة التطبيق `"guided-questions"` (حيث تم تثبيت
-يعرضها `GuidedQuestionFlow`) ويكشف عن لوحة الوكيل لذا فإن السؤال هو
-مرئية. على عكس أداة الوكيل - التي تتدفق إجابتها مرة أخرى إلى الوكيل -
-`askUserQuestion()` **يحل مع الرد على المتصل**، لذلك يمكن لـ UI
-فرع عليه.
-
-استخدمه عندما يحتاج UI إلى قرار صغير واحد بالضبط (2-4 خيارات) قبله
-يبدأ عمل الوكيل — بدلاً من إنشاء نموذج مخصص. الوصول إلى
-مؤلف للتفاصيل الحرة، ونموذج/بوبوفر للإدخال متعدد الحقول.
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-كل خيار هو `{ label, value?, description?, preview?, recommended? }`؛ `value`
-الإعداد الافتراضي هو `label`، ويعرض `preview` نموذجًا صغيرًا/مقتطفًا برمجيًا صغيرًا ضمن
-الخيار. يتم حل الوعد باستخدام `value` المحدد (أو `value[]` عندما
-`allowMultiple`)، سلسلة النص الحر عندما يختار المستخدم "أخرى"، أو `null`
-في حالة التخطي — يظل معلقًا حتى يجيب المستخدم. يتطلب لوحة الوكيل
-الذي سيتم تركيبه (موجود في كل قالب).
-
-يصل الوكيل إلى نفس UI من خلال أداة `ask-question` الخاصة به: يفضل السماح لـ
-يسأل الوكيل عندما _it_ يضرب شوكة حقيقية لا يمكن حلها من السياق؛ استخدم
-`askUserQuestion()` عندما يحتاج _UI_ إلى تنفيذ إجراء على الاختيار.
-
-## MCP جسر مضيف التطبيق {#mcp-app-host-bridge}
-
-يجب أن تكون المسارات المضمنة كتطبيقات MCP هي URL أولاً: قم بتحميل العنصر الحالي من
-معلمات المسار/الاستعلام، عرض مسار React الحقيقي أو مكون مشترك مركَّز عليه،
-واستخدم الجسر المضيف فقط للسلوك المملوك للمضيف. `@agent-native/core/client`
-يصدر استدعاء المسارات المضمنة للمساعدين:
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-يقرأ `getMcpAppHostContext()` أحدث لقطة لسياق المضيف المدفوع؛
-يشترك `useMcpAppHostContext()` في تغييرات مكونات React. الطلب
-المساعدون (`openMcpAppHostLink`، `requestMcpAppDisplayMode`،
-`updateMcpAppModelContext`) بإرجاع `false` خارج إطار تطبيق MCP المضمن، أو
-`Promise<boolean>` داخل الإطار. يستخدم `sendToAgentChat()` نفس الجسر لـ
-المطالبات المقدمة تلقائيًا من المسارات المضمنة.
-
-الجسر نفسه — رسائل `ui/*` JSON-RPC، `agentNative.mcpHost.*`
-ترحيل الغلاف، والزرع مقابل عرض الإطار المتحكم فيه، وسياق المضيف، و
-طلبات وضع العرض — مملوكة لـ
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## الاقتراحات الديناميكية {#dynamic-suggestions}
-
-`<AgentSidebar>` و`<AgentPanel>` و`<AssistantChat>` بدمج `suggestions` الثابت مع الاقتراحات المدركة للسياق بشكل افتراضي. يقرأ إطار العمل `navigation`، و`selection`، و`pending-selection-context`، وURL الحالي من حالة التطبيق بينما تكون الدردشة الفارغة مرئية، ثم يقدم شرائح مطالبة تطابق الشاشة الحالية.
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-اضبط `dynamicSuggestions={false}` للاحتفاظ بالرقائق الثابتة فقط. قم بتمرير `getSuggestions` عندما يريد أحد التطبيقات شرائح محددة خاصة بالمجال من نفس سياق حالة التطبيق.
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-خطاف React الذي يلتف sendToAgentChat مع تتبع حالة التحميل:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-يتحول `isGenerating` إلى القيمة true عند استدعاء `send()` ويتم إعادة تعيينه تلقائيًا إلى false عندما ينتهي الوكيل من الإنشاء.
-
-## useDbSync(خيارات؟) {#usedbsync}
-
-خطاف React (`useFileWatcher` سابقًا) الذي يستمع إلى تغييرات قاعدة البيانات عبر SSE، ويعود إلى الاستقصاء، ويبطل ذاكرة التخزين المؤقت لاستعلام إطار العمل التي تحافظ على محاذاة UI مع الوكيل:
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### الخيارات {#usedbsync-options}
-
-| الخيار             | اكتب               | الوصف                                                                                            |
-| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------ |
-| `queryClient`      | `QueryClient?`     | عميل استعلام React لإبطال ذاكرة التخزين المؤقت                                                   |
-| `queryKeys`        | `string[]?`        | مهمل ومتجاهل؛ تم الاحتفاظ بها لمواقع الاتصال القديمة                                             |
-| `pollUrl`          | `string?`          | نقطة نهاية الاستقصاء URL. الافتراضي: `"/_agent-native/poll"`                                     |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only           |
-| `interval`         | `number?`          | الفاصل الزمني للاستقصاء بالمللي ثانية. الافتراضي: `2000`                                         |
-| `fallbackInterval` | `number?`          | الفاصل الزمني للاستقصاء الاحتياطي عند عدم توفر SSE. الافتراضي: `15000`                           |
-| `pauseWhenHidden`  | `boolean?`         | إيقاف الاستقصاء مؤقتًا عندما تكون علامة تبويب المتصفح مخفية. الافتراضي: `true`                   |
-| `ignoreSource`     | `string?`          | تجاهل مصدر الطلب لكل علامة تبويب حتى لا تتم إعادة جلب علامة التبويب من عمليات الكتابة الخاصة بها |
-| `onEvent`          | `(data) => void`   | رد اتصال اختياري عندما يتلقى SSE/استقصاء حدث تغيير                                               |
-
-بالنسبة إلى CRUD العادي، تفضل `useActionQuery` و`useActionMutation`؛ يؤدي تغيير actions إلى إصدار `source: "action"` ويتم إعادة جلب هذه الخطافات تلقائيًا.
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-يستخدم إطار العمل إصدارات التغيير لمزامنة ذاكرة التخزين المؤقت للاستعلام React مع التغييرات التي أجراها وكلاء الخلفية، أو مهام cron، أو مستخدمين آخرين.
-
-عند حدوث أي تغيير في قاعدة البيانات من جانب الخادم، يسجل الخادم حدث تغيير باستخدام مفتاح `source` محدد. يتلقى مستمع `useDbSync` الخاص بالعميل هذه الأحداث ويتخطى عداد إصدار التغيير المحلي لهذا المصدر. من خلال طي عداد الإصدار في مفاتيح استعلام React، تتم إعادة جلب الاستعلامات تلقائيًا عندما تقوم الواجهة الخلفية بإعلام العميل بنشاط جديد.
-
-- **`useChangeVersion(source: string): number`** — يُرجع عدادًا يتزايد كلما تم تغيير `source` المحدد.
-- **`useChangeVersions(sources: readonly string[]): number`** — يُرجع مجموع عدادات الإصدار لمصادر متعددة.
-
-### مثال: مزامنة استعلام أولي مع قاعدة البيانات
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### نماذج زمن الاستجابة وسلوك الإبطال
-
-- ** الطفرات التي بدأتها UI:** عند تنفيذ إجراء من UI باستخدام `useActionMutation`، تقوم الطفرة على الفور بإطلاق حدث محلي مع `source: "action"` عند النجاح. يؤدي هذا إلى تشغيل **إعادة جلب فورية ومتفائلة** لجميع مفاتيح الاستعلام اعتمادًا على هذا الإجراء، مع تجنب التأخير البصري.
-- **طفرات الخلفية أو الوكيل:** عندما يقوم وكيل الذكاء الاصطناعي أو خطاف الويب أو عامل الخلفية بتغيير البيانات، يتم بث التحديث إلى العميل. يلتقط `useDbSync` الخاص بالعميل هذا إما على الفور عبر SSE (الأحداث المرسلة من الخادم) أو يعود إلى **علامة الاستقصاء التي تبلغ ثانيتين**. ثم يبرز إصدار مفتاح الاستعلام، مما يؤدي إلى إعادة جلب الخلفية.
-
-<Diagram id="doc-block-ymmrn1" title={"طريقان للإعادة"} summary={"تؤدي الطفرة المحلية إلى إبطال ذاكرة التخزين المؤقت الخاصة بها على الفور؛ تصل الكتابة عن بعد إلى علامة التبويب هذه عبر SSE، أو علامة الاستقصاء كإجراء احتياطي."}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">علامة التبويب هذه</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >مصدر الحرائق: "العمل" على النجاح &rarr; الاسترداد المحلي الفوري</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent"
-        >الوكيل · خطاف الويب · علامة تبويب أخرى</span
-      ><strong>الكتابة عن بعد</strong
-      ><small class="diagram-muted"
-        >دفع SSE، أو علامة الاستقصاء ~2s كبديل &rarr; المطبات الإصدار &rarr;
-        إعادة الخلفية</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...المدخلات) {#cn}
-
-أداة مساعدة لدمج أسماء الفئات (clsx + tailwind-merge):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/ar-SA/drop-in-agent.mdx b/packages/core/docs/content/locales/ar-SA/drop-in-agent.mdx
index 9e3992eb65..60dbcb9054 100644
--- a/packages/core/docs/content/locales/ar-SA/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/ar-SA/drop-in-agent.mdx
@@ -225,7 +225,7 @@ sendToAgentChat({
 
 عندما يتم تضمين نفس المسار كتطبيق MCP، يتم إرساله
 تتم إعادة توجيه مكالمات `sendToAgentChat()` إلى الدردشة المضيفة حيثما تكون مدعومة؛ انظر
-[Client](/docs/client#sendtoagentchat) لسلوك جسر تطبيق MCP.
+[محادثة الوكيل](/docs/client-agent-chat#sendtoagentchat) لسلوك جسر تطبيق MCP.
 
 إذا كنت تريد حالة تحميل، فاستخدم الخطاف `useSendToAgentChat()` - فهو يُرجع كلاً من `send` و`isGenerating`:
 
diff --git a/packages/core/docs/content/locales/ar-SA/notifications.mdx b/packages/core/docs/content/locales/ar-SA/notifications.mdx
index 9624be27e2..40d959cd9e 100644
--- a/packages/core/docs/content/locales/ar-SA/notifications.mdx
+++ b/packages/core/docs/content/locales/ar-SA/notifications.mdx
@@ -363,7 +363,7 @@ export function HeaderBar() {
 ## كيفية العمل {#internals}
 
 - **نطاق المالك** — يحتوي كل صف على عمود `owner`؛ يتم تصفية كل استعلام عليه؛ يستخدم كل مسار البريد الإلكتروني للجلسة المصادق عليها. لا يرى المستخدمون أبدًا إشعارات بعضهم البعض.
-- **تكامل الاستقصاء** — تستدعي كل طفرة `recordChange()`, لذا يتم إبطال صحة القوالب التي تستخدم [`useDbSync`](/docs/client) تلقائيًا دون أي أسلاك إضافية.
+- **تكامل الاستقصاء** — تستدعي كل طفرة `recordChange()`, لذا يتم إبطال صحة القوالب التي تستخدم [`useDbSync`](/docs/client-data#usedbsync) تلقائيًا دون أي أسلاك إضافية.
 - **توزيع أفضل جهد** — يتم اكتشاف أخطاء القناة وتسجيلها؛ لا تؤدي إحدى القنوات الفاشلة إلى منع القنوات الأخرى أو الكتابة في البريد الوارد.
 - **أطلق النار وانسى** — يعود `notify()` بعد اكتمال الكتابة في البريد الوارد؛ تعمل القنوات المخصصة في الخلفية.
 
diff --git a/packages/core/docs/content/locales/ar-SA/progress.mdx b/packages/core/docs/content/locales/ar-SA/progress.mdx
index 76945abcfa..4daf1b4e46 100644
--- a/packages/core/docs/content/locales/ar-SA/progress.mdx
+++ b/packages/core/docs/content/locales/ar-SA/progress.mdx
@@ -233,7 +233,7 @@ mode: agentic
 ## كيفية العمل {#internals}
 
 - **نطاق المالك** — يحتوي كل صف على عمود `owner`؛ يتم تصفية كل استعلام عليه. يرى المستخدمون عمليات التشغيل الخاصة بهم فقط.
-- **تكامل الاستقصاء** — تستدعي كل طفرة `recordChange()`, لذا يتم إبطال صحة القوالب التي تستخدم [`useDbSync`](/docs/client) تلقائيًا دون أي أسلاك إضافية.
+- **تكامل الاستقصاء** — تستدعي كل طفرة `recordChange()`, لذا يتم إبطال صحة القوالب التي تستخدم [`useDbSync`](/docs/client-data#usedbsync) تلقائيًا دون أي أسلاك إضافية.
 - **اسم الجدول** — يحتوي إطار العمل أيضًا على جدول `agent_runs` لتتبع دورة حياة دورة حياة الوكيل الداخلي للدردشة. يستخدم التقدم البدائي `progress_runs` للفصل بين الاهتمامين.
 - **تثبيت النسبة المئوية** — يتم تثبيت القيم على `[0, 100]` وتقريبها إلى عدد صحيح عند الكتابة.
 
@@ -241,4 +241,4 @@ mode: agentic
 
 - [**Notifications**](/docs/notifications) — قم بالاقتران مع `manage-progress` (`action=complete`) لإخبار المستخدم عند انتهاء العمل
 - [**Automations**](/docs/automations) — يعمل جهاز المراقبة ببطء عبر `run.progress.updated`
-- [**Client**](/docs/client) — `useDbSync` لإبطال ذاكرة التخزين المؤقت في الوقت الفعلي
+- [**البيانات والمزامنة**](/docs/client-data) — `useDbSync` لإبطال ذاكرة التخزين المؤقت في الوقت الفعلي
diff --git a/packages/core/docs/content/locales/ar-SA/real-time-collaboration.mdx b/packages/core/docs/content/locales/ar-SA/real-time-collaboration.mdx
index 6ddba0163c..33cd064017 100644
--- a/packages/core/docs/content/locales/ar-SA/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/ar-SA/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ description: "تحرير تعاوني متعدد المستخدمين حيث ي
 يبدو التحرير جنبًا إلى جنب مع الوكيل وكأنه يعمل في محرر تعاوني مع
 زميل عمل فوري ولا يكل:
 
-إذا كنت تحتاج فقط إلى تحديث UI عندما يكتب الوكيل أو مستخدم آخر إلى SQL، فلن تحتاج إلى أي من هذا — استخدم [`useDbSync`](/docs/client). هذه الصفحة مخصصة للتحرير المشترك على مستوى الأحرف لمستند نص منسق واحد (المؤشرات المشتركة، والدمج الخالي من الصراع). كلاهما يركبان نفس قناة `/_agent-native/poll`.
+إذا كنت تحتاج فقط إلى تحديث UI عندما يكتب الوكيل أو مستخدم آخر إلى SQL، فلن تحتاج إلى أي من هذا — استخدم [`useDbSync`](/docs/client-data#usedbsync). هذه الصفحة مخصصة للتحرير المشترك على مستوى الأحرف لمستند نص منسق واحد (المؤشرات المشتركة، والدمج الخالي من الصراع). كلاهما يركبان نفس قناة `/_agent-native/poll`.
 
 تم بناء هذا على ثلاث تقنيات تم اختبارها في المعارك: **Yjs** (CRDT للدمج الخالي من الصراعات)، **TipTap** (محرر النص المنسق)، و **المزامنة المستندة إلى الاقتراع** (تعمل في جميع بيئات النشر بما في ذلك بيئات النشر بدون خادم وبيئات Edge).
 
@@ -768,7 +768,7 @@ undoManager.redo(); // Shift+Cmd+Z
 
 ## المستندات ذات الصلة {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) — `useDbSync` + `useChangeVersion`
+- [آليات المزامنة الداخلية](/docs/client-sync-internals) — `useDbSync` + `useChangeVersion`
   النظام الذي يقدم تسوية محرر قيادة الصدمات `updatedAt`.
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   و`assertAccess` للتعاون المحدد النطاق بمورد.
diff --git a/packages/core/docs/content/locales/ar-SA/routing.mdx b/packages/core/docs/content/locales/ar-SA/routing.mdx
deleted file mode 100644
index b9d0f12a84..0000000000
--- a/packages/core/docs/content/locales/ar-SA/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "التوجيه"
-description: "التوجيه المستند إلى الملفات لتطبيقات الوكيل الأصلية باستخدام React Router v8 - الصفحات والمعلمات الديناميكية والتنقل."
----
-
-# التوجيه
-
-تستخدم تطبيقات الوكيل الأصلية **React Router v8** مع التوجيه المستند إلى الملف عبر `flatRoutes()` من `@react-router/fs-routes`. كل ملف في `app/routes/` يصبح URL. تستخدم القوالب اصطلاح التدوين النقطي — حيث تفصل النقاط مقاطع URL داخل اسم ملف واحد.
-
-## التوجيه المستند إلى الملف {#file-based-routing}
-
-### ملف → تعيين URL
-
-| ملف                   | URL                | ملاحظات                                 |
-| --------------------- | ------------------ | --------------------------------------- |
-| `_index.tsx`          | `/`                | فهرس المسار                             |
-| `settings.tsx`        | `/settings`        | صفحة بسيطة                              |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | النقطة = `/`، `$` = المعلمة الديناميكية |
-| `_app.tsx`            | (لا يوجد مقطع URL) | تخطيط بدون مسار — بادئة بـ `_`          |
-| `inbox/route.tsx`     | `/inbox`           | نموذج المجلد — `route.tsx` هو الفهرس    |
-
-بادئة مقطع بـ `$` لمعلمة ديناميكية. البادئة بـ `_` لجعلها مسار تخطيط بلا مسار (لا يوجد مقطع URL). تستخدم القوالب `flatRoutes()` — ملف التدوين النقطي أعلاه هو ملف أساسي؛ يعمل أيضًا نموذج المجلد المتداخل `inbox/route.tsx`.
-
-<Diagram id="doc-block-2d9jmv" title={"تخطيط بلا مسار يلتف الصفحات"} summary={"يعرض تخطيط _app.tsx (لا يوجد مقطع URL) الصدفة المشتركة مرة واحدة؛ يتم عرض الصفحات المطابقة داخل <Outlet/> الخاص بها، لذلك لا يتم إعادة تحميل الشريط الجانبي للوكيل أبدًا أثناء التنقل."}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >تخطيط بلا مسار · غلاف دائم + شريط الوكيل</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## إضافة صفحة جديدة {#adding-a-page}
-
-قم بإنشاء الملف وتصدير المكون الافتراضي:
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-هذا كل شيء — يقوم جهاز التوجيه React باستلامها تلقائيًا، دون الحاجة إلى التسجيل.
-
-## المعاملات الديناميكية {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## الملاحة {#navigation}
-
-استخدم `<Link>` للتنقل من جانب العميل و`useNavigate()` للتنقل البرمجي:
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## ما هي الخطوة التالية
-
-- [**Client**](/docs/client) — أدوات مساعدة وربط المتصفح الأصلي للوكيل
-- [**Server**](/docs/server) — مسارات الخادم المستندة إلى الملفات ومساحة الاسم `/_agent-native/`
diff --git a/packages/core/docs/content/locales/de-DE/client-advanced.mdx b/packages/core/docs/content/locales/de-DE/client-advanced.mdx
new file mode 100644
index 0000000000..997d7165a6
--- /dev/null
+++ b/packages/core/docs/content/locales/de-DE/client-advanced.mdx
@@ -0,0 +1,191 @@
+---
+title: "Fortgeschritten"
+description: "Niedrigere app/-Primitive und Escape-Hatches: direkter Zugriff auf den Anwendungsstatus, Hintergrund-Chat-Sendungen, benutzerdefinierte Vorschlags-Chips und die MCP-App-Host-Bridge."
+---
+
+# Fortgeschritten
+
+Überblick, Daten & Sync, Agent Chat und Routing behandeln den typischen Fall: die Hooks und Helfer, die die meisten Seiten benötigen. Diese Seite behandelt die niedrigeren Primitive und engeren Escape-Hatches darunter. Die meisten Apps fassen diese nie direkt an. Greifen Sie zu einem, wenn Sie etwas Individuelleres bauen, als die Standard-Hooks unterstützen, etwa eine benutzerdefinierte Auswahlsynchronisierung oder eine eingebettete MCP-App. Um ein rohes `useQuery` mit einem handgebauten Schlüssel zu synchronisieren, siehe stattdessen [Sync-Interna](/docs/client-sync-internals).
+
+## Anwendungsstatus {#application-state}
+
+`application_state` ist der SQL-gestützte Key/Value-Speicher, den der Agent liest, um zu wissen, was die UI aktuell betrachtet, einschließlich Navigation, Auswahl und anderem fokussiertem Objektkontext (siehe [Context Awareness](/docs/context-awareness)). `useAgentRouteState` und `useSemanticNavigationState` (ebenfalls in Context Awareness behandelt) umschließen diese Primitive bereits für den üblichen Navigationsfall. Greifen Sie direkt zu den untenstehenden Primitiven, wenn Sie etwas synchronisieren, das diese nicht abdecken, etwa eine benutzerdefinierte Auswahl, oder wenn Sie außerhalb des Renderns einer Komponente schreiben.
+
+### readClientAppState {#read-client-app-state}
+
+Liest den aktuellen Wert für einen Schlüssel. Löst sich zu dem auf, was zuletzt für diesen Schlüssel geschrieben wurde, oder zu `null`, wenn der Schlüssel noch nie geschrieben wurde.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection ist genau das, was zuletzt für diesen Schlüssel geschrieben wurde, z. B.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// oder, wenn noch nichts für "selection" geschrieben wurde:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+Schreibt einen Wert für einen Schlüssel. Im Gegensatz zu `setClientAppState` unten schreibt es immer, selbst wenn Sie `null` übergeben. Die Übergabe von `undefined` löst einen Fehler aus, da `undefined` kein gültiges JSON ist. Verwenden Sie `setClientAppState(key, undefined)` oder `deleteClientAppState()`, um einen Schlüssel zu löschen.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+Der Komfort-Wrapper, zu dem die meisten UI-Codes greifen sollten: schreibt den Wert oder löscht den Schlüssel, wenn Sie `null`/`undefined` übergeben. Verwenden Sie dies statt `writeClientAppState`, außer eine Aufrufstelle braucht wirklich "immer schreiben, nie löschen".
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // löscht den Schlüssel, genau wie deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+Entfernt einen Schlüssel vollständig.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+Liest mehrere Schlüssel in einer Anfrage. Gibt `{ values, missing }` zurück. `values` enthält einen Eintrag für jeden Schlüssel, für den der Server eine Zeile hat, einschließlich eines Schlüssels, der explizit als `null` geschrieben wurde. `missing` listet die Schlüssel auf, die überhaupt noch nie geschrieben wurden. So bleibt "nie geschrieben" von "als null geschrieben" unterscheidbar.
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+Anfragen über 100 Schlüssel werden automatisch aufgeteilt. `readClientAppState()` selbst baut darauf auf: Im selben Tick ausgelöste Aufrufe werden hinter den Kulissen zu einer gebündelten Anfrage zusammengefasst, sodass ein vielfacher Aufruf in einem einzelnen Render-Durchlauf eine Roundtrip kostet, nicht eine pro Aufruf.
+
+### Optionen {#application-state-options}
+
+`signal` wird von allen fünf obigen Funktionen akzeptiert, um einen laufenden Aufruf abzubrechen. `requestSource` und `keepalive` gelten nur für die drei Schreibfunktionen, da sie für ein Lesen keine Bedeutung haben.
+
+| Option          | Typ            | Gilt für                                                           | Beschreibung                                                                                                                                |
+| --------------- | -------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Kennzeichnet den Schreibvorgang mit einer Id, damit ein passendes `useDbSync({ ignoreSource })` das erneute Abrufen dafür überspringen kann |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Lässt die Anfrage das Entladen der Seite überleben. Für Aufräum-Schreibvorgänge wie das Löschen der Auswahl verwenden                       |
+| `signal`        | `AbortSignal?` | alle fünf Funktionen                                               | Bricht die Anfrage ab                                                                                                                       |
+
+### Fehlerverhalten {#failure-behavior}
+
+Alle fünf Funktionen werfen bei einer fehlgeschlagenen Anfrage, einer Nicht-2xx-Antwort oder einem Body, der nicht geparst werden kann. Der geworfene `Error` trägt eine `.status`-Eigenschaft, wenn der Server geantwortet hat, sodass ein Aufrufer bei Bedarf nach dem HTTP-Status verzweigen kann. Umschließen Sie einen Aufruf mit `try`/`catch`, oder lassen Sie ihn zu einer Error Boundary propagieren, genau wie jeden anderen Netzwerkaufruf.
+
+### Was TAB_ID ist {#tab-id}
+
+`requestSource` wird üblicherweise auf `TAB_ID` gesetzt, eine einfache Konstante, die jede Vorlage aus `app/lib/tab-id.ts` exportiert: eine kurze zufällige Zeichenfolge, die für die Lebensdauer eines Tabs gleich bleibt und sich zwischen Tabs unterscheidet. Das Paaren von `requestSource: TAB_ID` bei einem Schreibvorgang mit `useDbSync({ ignoreSource: TAB_ID })` auf der Leseseite ist, wie ein Tab vermeidet, seinen eigenen Schreibvorgang erneut abzurufen, während er trotzdem auf alle anderen reagiert. Siehe [Context Awareness](/docs/context-awareness#jitter-prevention) für den vollständigen Durchlauf.
+
+## sendToAgentChat: Hintergrundsendungen {#background-send}
+
+Verwenden Sie `background: true`, wenn eine UI-Aktion echte Agentenarbeit auslösen soll, ohne
+die Seitenleiste zu öffnen oder zu fokussieren. Dies erstellt weiterhin einen normalen Chat-Thread/Lauf,
+verwendet die Tools/Actions/den Kontext des Agenten und hält die Arbeit über
+das Lauf-Tray beobachtbar. Es ist kein roher One-Shot-Modellaufruf.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` ist dazu gedacht, mit `newTab` gepaart zu werden, damit die versteckte Arbeit die aktive
+Konversation des Benutzers nicht überschreibt. Verwenden Sie die zurückgegebene `tabId`, wenn die UI
+den Folgestatus korrelieren oder später zum Lauf tief verlinken muss.
+
+Ein paar weitere `AgentChatMessage`-Optionen existieren über die in [Agent Chat](/docs/client-agent-chat#agentchatmessage) behandelten hinaus, meist für eingebettete oder nachgeschaltete Integrationsfälle:
+
+| Option                | Typ         | Beschreibung                                                                    |
+| --------------------- | ----------- | ------------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | Läuft mit `newTab` ohne den Tab zu fokussieren und zeigt den Lauf in `RunsTray` |
+| `projectSlug`         | `string?`   | Optionaler Projekt-Slug für strukturierten Kontext                              |
+| `preset`              | `string?`   | Optionaler Preset-Name für nachgeschaltete Verbraucher                          |
+| `referenceImagePaths` | `string[]?` | Optionale Referenzbildpfade                                                     |
+
+## MCP-App-Host-Bridge {#mcp-app-host-bridge}
+
+Als MCP-Apps eingebettete Routen sollten URL-first sein: das aktuelle Artefakt aus
+Pfad-/Abfrageparametern laden, die echte React-Route oder eine fokussierte gemeinsame Komponente rendern
+und die Host-Bridge nur für host-eigenes Verhalten verwenden. `@agent-native/core/client`
+exportiert die Helfer, die eingebettete Routen aufrufen:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` liest den zuletzt gepushten Host-Kontext-Snapshot.
+`useMcpAppHostContext()` abonniert React-Komponenten für Änderungen. Die Anfrage-Helfer
+(`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) geben außerhalb eines eingebetteten MCP-App-Frames `false` zurück, oder
+`Promise<boolean>` innerhalb eines Frames.
+
+`sendToAgentChat()` (siehe [Agent Chat](/docs/client-agent-chat#sendtoagentchat)) verwendet dieselbe Bridge für automatisch gesendete Prompts von eingebetteten Routen. Innerhalb einer mit `embedApp()` erstellten MCP-App-Einbettung werden automatisch gesendete Nachrichten (`submit` weggelassen oder `true`) an die Bridge weitergeleitet, die den umschließenden Host bittet, versteckten Kontext hinzuzufügen und den sichtbaren Benutzerzug zu senden. `context` bleibt für das Modell sichtbar, ohne als benutzersichtbarer Chat gepostet zu werden. `submit: false` behält das lokale Vorabausfüll-/Überprüfungsverhalten bei, da MCP-Apps keine Standard-API für Entwurfsvorabausfüllung definieren. Intern ist dies der Pfad des gesendeten Chats, der manchmal als `agentNative.submitChat` auftaucht. App-Code sollte weiterhin `sendToAgentChat()` aufrufen, statt dieses Ereignis direkt zu posten.
+
+Die Bridge selbst, die `ui/*`-JSON-RPC-Nachrichten, das `agentNative.mcpHost.*`-Wrapper-Relay, Transplantation vs. Controlled-Frame-Rendering, Host-Kontext und
+Anzeigemodus-Anfragen, gehört zu
+[External Agents](/docs/external-agents#mcp-app-bridge). Siehe [MCP Apps](/docs/mcp-apps) für das vollständige Protokoll.
+
+## Benutzerdefinierte Vorschlags-Chips {#custom-suggestions}
+
+`dynamicSuggestions` von `<AgentSidebar>` (siehe [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) führt statische `suggestions` bereits mit der eigenen kontextbewussten Heuristik des Frameworks zusammen. Übergeben Sie stattdessen `getSuggestions`, wenn eine App deterministische, domänenspezifische Chips möchte, berechnet aus demselben `application_state`-Kontext statt aus der Standard-Heuristik des Frameworks.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` erhält denselben `navigation`/`selection`/`pending-selection-context`-Snapshot, den die eingebaute Heuristik liest, sodass eine benutzerdefinierte Implementierung auf genau den Zustand reagieren kann, auf den auch die Standardimplementierung reagiert, nur mit app-spezifischen Regeln statt generischer.
+
+## Was kommt als nächstes?
+
+- [**Überblick**](/docs/client-overview) — das Layout der Verzeichnisse `app/` und `public/`, in dem diese Primitive leben
+- [**Daten & Sync**](/docs/client-data) — die Standard-Action-Hooks und `useDbSync`, die die meisten Seiten stattdessen verwenden sollten
+- [**Sync-Interna**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` und die zwei Latenzpfade, die ein erneutes Abrufen nehmen kann
+- [**Agent Chat**](/docs/client-agent-chat) — die Standard-Helfer `sendToAgentChat`/`askUserQuestion`, die die meiste UI stattdessen verwenden sollte, und die bereitgestellten Agent-Chat-Kontextstatus-APIs
+- [**Einstiegspunkte**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` und Anpassung des SSR-Streamings
+- [**Context Awareness**](/docs/context-awareness) — die `navigation`/`selection`-Semantik, aufgebaut auf `application_state`, und der `TAB_ID`/Jitter-Vermeidung-Durchlauf
+- [**Generative UI**](/docs/generative-ui) — reichhaltigere Inline-Chat-Steuerelemente jenseits von `askUserQuestion`
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — die vollständigen Interna der MCP-App-Host-Bridge
diff --git a/packages/core/docs/content/locales/de-DE/client-agent-chat.mdx b/packages/core/docs/content/locales/de-DE/client-agent-chat.mdx
new file mode 100644
index 0000000000..6815134716
--- /dev/null
+++ b/packages/core/docs/content/locales/de-DE/client-agent-chat.mdx
@@ -0,0 +1,315 @@
+---
+title: "Agent Chat"
+description: "Clientseitige Einstiegspunkte in den Agent-Chat: sendToAgentChat, openAgentSettings, askUserQuestion, dynamische Vorschläge, useAgentChatGenerating und bereitgestellter Agent-Chat-Kontextstatus."
+---
+
+# Agent Chat
+
+Der Client Ihrer Anwendung kann über eine kleine Gruppe von Client-Helfern mit dem Agenten sprechen. Diese decken das Senden eines Prompts, das Bereitstellen versteckten Kontexts, das Stellen einer blockierenden Frage an den Benutzer und das Öffnen des Agenten-Panels ab.
+
+Im folgenden Beispiel veranlasst eine Schaltfläche **Antwort entwerfen** den Agenten, dem Benutzer eine Frage zu stellen. Sobald der Benutzer antwortet, entwirft der Agent eine Antwort unter Berücksichtigung des aktuellen Seitenkontexts und der Antwort des Benutzers.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="Dispatch-App-Screenshot mit der Seitenleiste des Ausführungsverlaufs"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Die Seitenleiste des Ausführungsverlaufs von Dispatch."
+/>
+
+## Wie es funktioniert
+
+Mit den von Agent-Native bereitgestellten Client-Helfermethoden kann Ihre UI den Agenten dazu bringen, auf verschiedene Weise mit dem Benutzer zu interagieren. Das Diagramm unten zeigt, wie eine Schaltfläche "Antwort entwerfen" vom Benutzer angeklickt werden kann, was den Agenten veranlasst, mit dem Benutzer zu interagieren, bevor eine Antwort generiert wird.
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="Sequenzdiagramm 'wem gehört welcher Schritt' mit drei Lifelines: App-Code, UI und Agent. Klick auf 'Antwort entwerfen' löst askUserQuestion() aus (rendert inline im Agenten-Panel). Nach der Antwort ruft sendDraftRequest() draft-ticket-reply auf und gibt eine Antwort an den UI-Composer zurück."
+  align="full"
+  width={600}
+  caption="Sequenzdiagramm zur Visualisierung eines Ablaufs der Schaltfläche 'Antwort entwerfen'."
+/>
+
+Die Benutzererfahrung ist wie folgt:
+
+1. Der Benutzer klickt auf die Schaltfläche **Antwort entwerfen**, wodurch die Funktion `askUserQuestion()` aufgerufen wird. Die Frage wird inline im Agenten-Panel beantwortet.
+
+1. Der Benutzer wählt **Rückerstattung anbieten**, wodurch `sendDraftRequest()` den Prompt und den Ticket-Kontext an den Agenten sendet.
+
+1. Der Agent ruft die [Action](/docs/actions) `draft-ticket-reply` auf, und die entworfene Antwort erscheint im Antwort-Composer.
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "Die Frage, ihre Optionen und wie sie sich verhalten soll.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "Die vollständige Frage. Klar, spezifisch, endet mit einem Fragezeichen.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'Sehr kurzer Chip/Titel, etwa 12 Zeichen, z. B. `"Antwort"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2–4 unterschiedliche Optionen. Jede ist `{ label, value?, description?, preview?, recommended? }`. `value` entspricht standardmäßig `label`.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            'Fügt eine Freitext-Option "Andere" hinzu, in die der Mitarbeiter tippen kann.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Mehrfachauswahl statt Einzelauswahl.",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description:
+            "Anwendungsstatus-Schlüssel, den das Agenten-Panel abfragt.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'Der gewählte `value` (oder `value[]` bei `allowMultiple`), der eingetippte "Andere"-Text des Mitarbeiters oder `null`, wenn er überspringt. Bleibt ausstehend, bis geantwortet wird. Erfordert, dass das Agenten-Panel gemountet ist, was in jeder Vorlage der Fall ist.',
+  }}
+/>
+
+Diese Funktion stellt dem Benutzer aus App-Code eine Multiple-Choice-Frage, rendert sie inline im Agenten-Panel und wartet auf die Antwort. Verwenden Sie sie, wenn die UI vor dem Start der Agentenarbeit eine kleine Entscheidung mit zwei bis vier Optionen benötigt, statt ein benutzerdefiniertes Modal zu bauen.
+
+Im folgenden Beispiel fragt eine Schaltfläche "Antwort entwerfen" auf einer Ticket-Seite den Mitarbeiter, wie er antworten möchte, bevor etwas an den Agenten gesendet wird:
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optionaler kurzer Chip/Titel (≈12 Zeichen)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "Ein `[isGenerating, send]`-Tupel. `isGenerating` ist `true`, ab dem Moment, in dem `send()` aufgerufen wird, bis der Agent-Chat-Lauf meldet, dass er gestoppt hat. `send(opts)` hat dieselbe Signatur wie `sendToAgentChat()` und gibt die Tab-Id zurück, an die gesendet wurde.",
+  }}
+/>
+
+Dieser React-Hook umschließt `sendToAgentChat()` mit Ladezustandsverfolgung.
+
+1. Das erste Argument, `isGenerating`, wird beim Aufruf `true` und setzt sich zurück auf `false`, sobald der Agent die Generierung beendet hat.
+
+2. Das zweite Argument, `send()`, spiegelt die Funktion `sendToAgentChat()`.
+
+`isGenerating` setzt sich erst zurück, sobald ein Lauf tatsächlich startet und meldet, dass er gestoppt hat. Ein Aufruf mit `submit: false` füllt einen Entwurf vorab aus, ohne einen Lauf zu starten, sodass `isGenerating` danach für immer `true` bleibt. Verwenden Sie diesen Hook nur für Sendungen mit `submit: true`; rufen Sie `sendToAgentChat()` direkt für reine Vorabausfüllungen auf.
+
+Die Kombination davon mit dem `askUserQuestion()`-Beispiel oben vervollständigt den Handler der Schaltfläche:
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="Den Draft-Response-Handler vervollständigen"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "Ladezustand + Senden, zusammen",
+      note: "`useAgentChatGenerating()` gibt dieselbe Tupel-Form wie ein bloßer `sendToAgentChat()`-Aufruf zurück, fügt aber `isDrafting` hinzu, damit sich die Schaltfläche selbst deaktivieren kann, während die Anfrage läuft.",
+    },
+    {
+      lines: "10-17",
+      label: "Wiederverwendung des Frage-Schritts",
+      note: "Dies ist genau der `askUserQuestion()`-Aufruf aus dem Abschnitt oben, jetzt im eigenen Handler der Schaltfläche.",
+    },
+    {
+      lines: "18",
+      label: "Vor Verwendung der Antwort einschränken",
+      note: "Der Rückgabetyp erlaubt wegen `allowMultiple` immer auch `string[]`, daher ist diese Prüfung nötig, auch wenn dieser Aufruf es nie setzt.",
+    },
+    {
+      lines: "20-25",
+      label: "Aus der Auswahl einen Satz machen",
+      note: "Ordnet den ausgewählten Wert oder den eigenen eingetippten Text des Mitarbeiters der Formulierung zu, die der Prompt unten natürlich liest.",
+    },
+    {
+      lines: "27-32",
+      label: "Action und Absicht benennen",
+      note: "Die Nachricht sagt dem Agenten genau, welche Action aufgerufen werden soll (`draft-ticket-reply`), und erinnert ihn daran, die Antwort nicht direkt zu senden. `openSidebar: true` sorgt dafür, dass die entworfene Antwort sichtbar ist, selbst wenn die Seitenleiste geschlossen war.",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting steuert die Schaltfläche",
+      note: "Nur deaktiviert und umbenannt, während `sendDraftRequest()` läuft. Die Schaltfläche bleibt klickbar, während `askUserQuestion()` auf den Mitarbeiter wartet, da das passiert, bevor `sendDraftRequest()` überhaupt aufgerufen wird.",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Sendet eine Nachricht an den Agent-Chat über `postMessage`. Dies ist die niedrigere Primitive, die `useAgentChatGenerating()` oben umschließt, nützlich, wenn eine UI-Interaktion keine eigene Ladezustandsverfolgung benötigt. Übergeben Sie `context` für zusätzliche Details, die die Nachricht allein nicht trägt. Er wird derselben sichtbaren Nachricht angehängt, eingeschlossen in `<context>`-Tags. Er ist nicht vor dem Benutzer verborgen. Übergeben Sie `submit: true`, um sofort zu senden, oder `submit: false`, um einen Entwurf vorab auszufüllen, den der Benutzer zuerst überprüft.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Automatisches Senden eines Prompts mit angehängtem Kontext
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Vorab ausfüllen ohne Senden (Benutzer prüft zuerst)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| Option        | Typ        | Beschreibung                                                                                                                    |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | Der an den Chat gesendete Prompt. `context`, falls gesetzt, wird derselben sichtbaren Nachricht angehängt                       |
+| `context`     | `string?`  | Zusätzliche Details, angehängt an die sichtbare Nachricht, eingeschlossen in `<context>`-Tags. Nicht vor dem Benutzer verborgen |
+| `submit`      | `boolean?` | true = automatisches Senden, false = nur Vorabausfüllung                                                                        |
+| `newTab`      | `boolean?` | Einen separaten Chat-Thread für diesen Prompt erstellen                                                                         |
+| `openSidebar` | `boolean?` | Auf false setzen, um zu senden/vorab auszufüllen, ohne die Seitenleiste zu öffnen                                               |
+
+Das Ausführen davon aus einem eingebetteten MCP-App-Frame heraus, oder das Ausführen im Hintergrund ohne Öffnen der Seitenleiste, wird beides in [Fortgeschritten](/docs/client-advanced#background-send) behandelt.
+
+## Dynamische Vorschläge {#dynamic-suggestions}
+
+Bevor eine Konversation beginnt, zeigen `<AgentSidebar>`, `<AgentPanel>` und `<AssistantChat>` Prompt-Chips im leeren Chat. Standardmäßig sind das nicht nur Ihre feste `suggestions`-Liste: Das Framework liest `navigation`, `selection`, `pending-selection-context` und die aktuelle URL aus dem Anwendungsstatus und mischt Chips ein, die zu dem passen, was tatsächlich auf dem Bildschirm ist.
+
+Dabei werden zwei Prüfungen durchgeführt. Wenn etwas ausgewählt ist, werden generische Chips wie "Diese Auswahl zusammenfassen" hinzugefügt. Getrennt davon wird `navigation` auf Feldnamen untersucht, die bestehende Apps bereits verwenden, wie `threadId`/`emailId` für einen E-Mail-Thread oder `dashboardId`/`chartId` für ein Diagramm, und Chips hinzugefügt, die auf diese Art von Bildschirm zugeschnitten sind, etwa "Eine Antwort entwerfen" für einen Thread oder "Anomalien in diesen Daten finden" für ein Diagramm. Was dabei herauskommt, wird mit Ihren statischen `suggestions` zusammengeführt, dedupliziert und bei `max` gekappt.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+Wenn der aktuelle Bildschirm zu nichts passt, was die Heuristik erkennt, und nichts ausgewählt ist, trägt sie keine Chips bei, und der leere Chat greift allein auf Ihre statischen `suggestions` zurück. Setzen Sie `dynamicSuggestions={false}`, um nur statische Chips zu behalten. Wenn die Navigationsform Ihrer App nicht zur eingebauten Heuristik passt, oder Sie vollständig deterministische, app-spezifische Chips möchten, siehe [Fortgeschritten](/docs/client-advanced#custom-suggestions).
+
+## openAgentSettings(section?) {#openagentsettings}
+
+Verwenden Sie `openAgentSettings()`, wenn eine App-Einstellungsseite oder eine Setup-Karte
+den Tab "Einstellungen" der Agenten-Seitenleiste öffnen soll. Übergeben Sie eine Abschnitts-Id wie `"llm"`, `"secrets"`,
+`"automations"`, `"voice"` oder `"limits"`, um einen bestimmten Abschnitt zu öffnen.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Bevorzugen Sie diesen Helfer gegenüber dem direkten Versand von `agent-panel:open-settings`.
+
+## Agent-Chat-Kontextstatus {#agent-chat-context-state}
+
+Die Kontextstatus-APIs sind optionale Verkabelung für UI, die eine bidirektionale Synchronisierung mit bereitgestellten Kontext-Chips benötigt: das Rendern der aktuell bereitgestellten Elemente außerhalb des Composers, das Anzeigen, ob ein Element bereits angehängt ist, oder das Bereitstellen expliziter Entfernen-/Löschen-Steuerelemente.
+
+Greifen Sie für einfache "Dies an den Agenten senden"- oder "Diesen Entwurf zur Überprüfung vorab ausfüllen"-Abläufe nicht zu diesen Helfern. Verwenden Sie [`sendToAgentChat()`](#sendtoagentchat) mit `context` und `submit` dafür.
+
+| API                               | Wann verwenden                                                                                       |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | Eine React-Komponente benötigt die live bereitgestellte Kontextliste                                 |
+| `setAgentChatContextItem(item)`   | Imperativer Code sollte ein Schlüsselkontextelement bereitstellen oder ersetzen                      |
+| `listAgentChatContext()`          | Nicht-React-Code benötigt einen einmaligen Snapshot des bereitgestellten Kontexts                    |
+| `removeAgentChatContextItem(key)` | UI sollte ein bereitgestelltes Kontextelement über seinen stabilen `key` entfernen                   |
+| `clearAgentChatContext()`         | UI sollte den gesamten bereitgestellten Kontext löschen, etwa nach einem Ansichts- oder Moduswechsel |
+| `refreshAgentChatContext()`       | Imperativer Code sollte den neuesten persistierten Kontext-Snapshot erneut lesen                     |
+
+`useAgentChatContext()` gibt `{ items, set, remove, clear, refresh }` zurück.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` ist für imperativen Code gedacht, der die aktuell bereitgestellten Elemente nur einmal einsehen muss. `clearAgentChatContext()` ist absichtlich breit gefasst. Verwenden Sie `removeAgentChatContextItem(key)`, wenn sich nur eine Auswahl geändert hat.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| Option        | Typ        | Beschreibung                                                                            |
+| ------------- | ---------- | --------------------------------------------------------------------------------------- |
+| `key`         | `string`   | Stabile Kennung, die verwendet wird, um ein vorhandenes Nugget zu ersetzen              |
+| `title`       | `string`   | Kurzbezeichnung, angezeigt im Composer-Chip                                             |
+| `context`     | `string`   | Versteckter Kontext, der der nächsten gesendeten Aufforderung beigelegt wird            |
+| `openSidebar` | `boolean?` | Standardmäßig true. Übergeben Sie false, um den Kontext stillschweigend bereitzustellen |
+
+## Was kommt als nächstes?
+
+- [**Überblick**](/docs/client-overview) — wo diese Helfer in `app/` hineinpassen
+- [**Daten & Sync**](/docs/client-data) — die Action-Hooks und `useDbSync`, die die UI selbst aktuell halten
+- [**Drop-in Agent**](/docs/drop-in-agent) — `<AgentSidebar>`/`<AgentPanel>` mounten, damit diese Helfer etwas haben, worin sie rendern können
+- [**Fortgeschritten**](/docs/client-advanced) — Hintergrundsendungen, benutzerdefinierte Vorschlags-Chips und die MCP-App-Host-Bridge
+- [**Generative UI**](/docs/generative-ui) — reichhaltigere Inline-Chat-Steuerelemente jenseits von `askUserQuestion` bauen
diff --git a/packages/core/docs/content/locales/de-DE/client-data.mdx b/packages/core/docs/content/locales/de-DE/client-data.mdx
new file mode 100644
index 0000000000..fe35f4c03f
--- /dev/null
+++ b/packages/core/docs/content/locales/de-DE/client-data.mdx
@@ -0,0 +1,435 @@
+---
+title: "Daten & Sync"
+description: "Die Action-Hooks, mit denen app/ dieselben Actions liest, schreibt und live synchron hält, die auch der Agent aufruft."
+---
+
+# Daten & Sync
+
+Der primäre Weg, App-Daten aus dem Client zu lesen und zu schreiben, führt über [Action](/docs/actions)-Hooks. Indem Anfragen in Actions eingebettet werden, können sowohl Ihr Client als auch der Agent auf dieselbe Weise mit Ihrer Anwendung interagieren.
+
+Im folgenden Beispiel wird ein Ticket manuell über ein Dropdown und dann über den Chat-Agenten dem aktuellen Benutzer zugewiesen. Sowohl die UI als auch der Agent greifen auf dieselbe Action zu.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="Beispiel einer UI-Action und einer Agent-Action mit demselben Ergebnis."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Beispiel einer UI-Action und einer Agent-Action mit demselben Ergebnis."
+/>
+
+## Daten abrufen und ändern {#fetching-mutating}
+
+Eine typische App baut ihre eigene API-Schicht und ruft sie mit handschriftlichen `fetch`-Anfragen auf. Eine agentennative App überspringt diese Schicht: `app/` ruft dieselben Actions auf, die der Agent bereits als Tools hat, über die untenstehenden Hooks.
+
+<Diagram id="doc-block-client-data-fm-1" title="Typischer Fetch vs. ein Action-Hook" summary="Eine typische Komponente ruft eine Route auf, die nur sie erreichen kann. Eine agentennative Komponente ruft eine Action auf, die auch der Agent aufrufen kann.">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Typisch</div>
+    <div class="diagram-node">Komponente</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Ihre API-Route</strong>
+      <small class="diagram-muted">nur das Frontend kann sie aufrufen</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Datenbank</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Komponente</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead-Action</span>
+      <small class="diagram-muted">auch ein Agent-Tool</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL-Datenbank</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Action-Hooks {#action-hooks}
+
+Es gibt zwei Action-Hooks, die Sie am wahrscheinlichsten verwenden werden: `useActionQuery()` und `useActionMutation()`. Diese beiden Hooks bieten Zugriff auf die Actions Ihrer App.
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "Der registrierte Name der Action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "Die Eingabe der Action, typisiert nach ihrem `defineAction()`-Schema.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "Alles aus den [useQuery-Optionen](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) außer `queryKey` und `queryFn`, die der Hook selbst setzt.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      'Zwischengespeichert unter `["action", name, params]`. Ruft automatisch erneut ab, sobald eine mutierende Action abschließt, ohne manuelle Invalidierung.',
+  }}
+/>
+
+Dieser Hook ist für schreibgeschützte Actions gedacht. Es ist ein dünner Wrapper um die Funktion [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).
+
+Im folgenden Beispiel wird die Action `list-tickets` aufgerufen. Dies ähnelt einer GET-Anfrage für alle Tickets.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+Das folgende Beispiel zeigt eine Anfrage, um ein einzelnes Ticket über die Action `get-ticket` abzurufen. Eine `ticketId` wird übergeben, um die Abfrage auf ein bestimmtes Ticket zu beschränken. Die zusätzliche Option `enabled` sorgt dafür, dass die Abfrage nicht automatisch läuft, sondern nur, wenn eine `ticketId` vorhanden ist.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "Der registrierte Name der Action.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "Alles aus den [useMutation-Optionen](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) außer `mutationFn`, die der Hook selbst setzt.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Überschreibt die Standard-Anfragemethode.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Deaktiviert die automatische Cache-Auffrischung bei Erfolg.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'Bei Erfolg wird ein Änderungsereignis mit `source: "action"` ausgegeben, sodass jede `useActionQuery()`, die betroffene Daten liest, automatisch erneut abruft. Keine manuelle Invalidierung nötig.',
+  }}
+/>
+
+Dieser Hook ist für Actions gedacht, die Daten ändern, wie Erstellen, Aktualisieren oder Senden. Es ist ein dünner Wrapper um die Funktion [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation).
+
+Im Gegensatz zu `useActionQuery()` wird die Eingabe der Action nicht dem Hook selbst übergeben. Sie wird `mutate()` oder `mutateAsync()` übergeben, wenn Sie bereit sind, die Mutation auszuführen.
+
+Im folgenden Beispiel wird die Action `send-ticket-reply` aufgerufen, um eine Antwort auf ein Ticket zu posten. Rufen Sie `mutate()` aus einem Event-Handler auf, etwa dem `onClick` einer Schaltfläche.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+Das folgende Beispiel zeigt dieselbe Mutation mit einer `onSuccess`-Option. Die Cache-Invalidierung erfolgt nach jeder Mutation automatisch, daher wird `onSuccess` nur für lokale Nebeneffekte benötigt, etwa das Leeren des Antwort-Composers, nachdem die Antwort gesendet wurde.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "Der registrierte Name der Action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "Die Eingabe der Action, typisiert nach ihrem `defineAction()`-Schema.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "Alles Folgende ist optional.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Überschreibt die Standard-Anfragemethode.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "Bricht die Anfrage ab.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Überschreibt das Standard-Timeout von 60 Sekunden, für Actions, die berechtigterweise länger dauern.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "Im Gegensatz zu den obigen Hooks gibt es keinen Cache und kein automatisches erneutes Abrufen. Kombinieren Sie es mit einer manuellen Invalidierung, wenn andere UI vom Ergebnis abhängt.",
+  }}
+/>
+
+Diese Funktion ist für imperative Einzelaufrufe von Actions außerhalb eines React-Render-Flows gedacht, etwa einen einfachen Event-Handler, ein Skript oder einen anderen Nicht-React-Codepfad. Sie gibt direkt ein Promise zurück statt eines Hook-Ergebnisses.
+
+Im folgenden Beispiel wird die Action `update-ticket` aus einem Tastenkürzel-Handler außerhalb des Render-Flows von React aufgerufen, um das Ticket einem Mitarbeiter zuzuweisen.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+Das folgende Beispiel zeigt denselben Aufruf mit einer `timeoutMs`-Option, nützlich für Actions, die berechtigterweise länger als das Standard-Timeout von 60 Sekunden dauern.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+Jede Anfrage von `useActionQuery()`, `useActionMutation()` und `callAction()` ist durch ein 60-Sekunden-Timeout begrenzt, und Timeouts erscheinen als Fehler statt stillschweigend erneut zu versuchen. `useActionQuery()` bricht außerdem automatisch überholte Anfragen ab, mithilfe des Abort-Signals von React Query.
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "Jedes Feld ist optional.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "React-Query-Client für die Cache-Invalidierung.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "Polling-Endpunkt-URL.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "SSE-Endpunkt-URL. Übergeben Sie `false`, um nur Polling zu verwenden.",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "Polling-Intervall in ms.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Polling-Intervall, während SSE verbunden ist, als Backup, falls ein Ereignis verpasst wird. Ein getrennter Tab pollt stattdessen mit dem schnelleren `interval` (oder einem festen Leerlauftakt).",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Pausiert das Polling, wenn der Browser-Tab ausgeblendet ist. Ausgeblendete Tabs halten SSE verbunden und pollen aktiv höchstens alle 10s, im Leerlauf alle 60s.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "Pro-Tab-Anfragequelle, die ignoriert werden soll, damit ein Tab nicht wegen eigener Schreibvorgänge erneut abruft.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "Optionaler Callback, wenn SSE oder Polling ein Änderungsereignis empfängt.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "Filtert die breite Invalidierung, die ein Action-Ereignis auslöst. Selten benötigt. Verwenden Sie es, um eine teure aktive Abfrage bei expliziter Aktualisierungssemantik zu halten, während normale quellversionierte Abfragen weiterhin über `useChangeVersion` reagieren.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "Action-Namen, deren Sync-Ereignisse nicht alle Action-Abfragen invalidieren sollen. Nur für hochfrequente Hintergrund-Actions, die bereits eine eigene enge Invalidierung durchführen.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description:
+            "Veraltet und ignoriert. Für alte Aufrufstellen beibehalten.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+Dieser Hook ist dafür gedacht, die UI mit Datenbankänderungen synchron zu halten, die außerhalb Ihrer eigenen Actions passieren, wie ein Agent-Schreibvorgang, ein Webhook oder eine Änderung aus einem anderen Browser-Tab. Er lauscht auf Änderungen über Server-Sent Events und greift auf Polling zurück, wenn Server-Sent Events nicht verfügbar sind.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+Für normales CRUD bevorzugen Sie `useActionQuery()` und `useActionMutation()`. Mutierende Actions geben `source: "action"` aus, sodass diese Hooks sofort erneut abrufen. Änderungen vom Agenten, einem Webhook oder einem anderen Tab kommen stattdessen über `useDbSync()` an, per SSE oder dem Polling-Fallback. Wenn ein roher `useQuery()`-Aufruf auf einem benutzerdefinierten Schlüssel synchronisiert werden muss, siehe [Sync-Interna](/docs/client-sync-internals). Wenn Sie direkt in `application_state` schreiben müssen, siehe [Fortgeschritten](/docs/client-advanced).
+
+## Was kommt als nächstes?
+
+- [**Überblick**](/docs/client-overview) — das Layout der Verzeichnisse `app/` und `public/`, in dem die Hooks dieser Seite leben
+- [**Agent Chat**](/docs/client-agent-chat) — Prompts senden und Kontext für den Agenten bereitstellen
+- [**Actions**](/docs/actions) — die `defineAction`-Oberfläche hinter jedem Hook auf dieser Seite
+- [**Fortgeschritten**](/docs/client-advanced) — direkter `application_state`-Zugriff
+- [**Sync-Interna**](/docs/client-sync-internals) — Synchronisierung eines rohen `useQuery` mit `useChangeVersion`
+- [**Real-Time Sync**](/docs/key-concepts#polling-sync) — wie `useDbSync` die UI aktuell hält
diff --git a/packages/core/docs/content/locales/de-DE/client-entry-points.mdx b/packages/core/docs/content/locales/de-DE/client-entry-points.mdx
new file mode 100644
index 0000000000..393035d3f5
--- /dev/null
+++ b/packages/core/docs/content/locales/de-DE/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "Einstiegspunkte"
+description: "app/entry.client.tsx und app/entry.server.tsx: die dünnen Hydration- und SSR-Bootstrap-Wrapper, und wann das Streaming-Verhalten angepasst werden sollte."
+---
+
+# Einstiegspunkte
+
+`app/entry.client.tsx` hydratisiert das serverseitig gerenderte HTML im Browser, und `app/entry.server.tsx` rendert dieses HTML auf dem Server. Beide sind dünne, von React Router generierte Wrapper. Sie müssen sie selten bearbeiten.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+Greifen Sie hierauf nur für fortgeschrittene SSR-Anpassungen zu, etwa das Ändern des Streaming-Verhaltens. Gewöhnliche Seiten, Layout und Daten benötigen hier keine Änderungen. Siehe [Routing](/docs/client-routing), um stattdessen Seiten hinzuzufügen.
+
+## Was kommt als nächstes?
+
+- [**Überblick**](/docs/client-overview) — wo diese Dateien in `app/` sitzen
+- [**Routing**](/docs/client-routing) — Seiten hinzufügen, der normale Weg, `app/` zu erweitern
+- [**Fortgeschritten**](/docs/client-advanced) — die anderen niedrigeren Client-Primitive und Escape-Hatches
diff --git a/packages/core/docs/content/locales/de-DE/client-overview.mdx b/packages/core/docs/content/locales/de-DE/client-overview.mdx
new file mode 100644
index 0000000000..5d67c8b7e4
--- /dev/null
+++ b/packages/core/docs/content/locales/de-DE/client-overview.mdx
@@ -0,0 +1,208 @@
+---
+title: "Überblick"
+description: "Die Verzeichnisse app/ und public/: hier bauen Sie die Darstellung einer agentennativen App, und die Browser-APIs, mit denen sie mit dem Agenten synchron bleibt."
+---
+
+# Überblick
+
+`app/` ist der Ort, an dem Sie die eigentliche Darstellung einer agentennativen App bauen: Seiten, Layout, Komponenten, Styles. `public/` enthält die statischen Assets, die daneben ausgeliefert werden – Icons, Manifest, Markenzeichen. Dies ist eine typische React Router v8 App, keine spezielle Nur-Agenten-Oberfläche, und hier fließt der Großteil der Entwicklungszeit.
+
+Der eine architektonische Unterschied zu einem typischen Frontend: Diese Schicht hat kein eigenes Backend-for-Frontend. Sie liest und schreibt Daten über dieselben Actions, die auch der Agent aufruft, sodass alles, was hier verkabelt wird, automatisch etwas ist, das der Agent auch tun kann.
+
+<Diagram id="doc-block-client-overview-1" title="Traditionelles Frontend vs. Agent Native" summary="Ein traditionelles Frontend ruft seine eigene API-Schicht auf, die nur es selbst erreichen kann. In Agent Native rufen app/ und der Agent dieselben Actions auf, sodass jede hier gebaute Fähigkeit kostenlos agentenaufrufbar ist.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Traditionell</div>
+    <div class="diagram-node">app/ (React-Frontend)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API-Schicht</strong>
+      <small class="diagram-muted">nur das Frontend ruft sie auf</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Datenbank</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React-Frontend)</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted"
+        >gleichwertige Partner, gleiche Operationen</small
+      >
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL-Datenbank</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Wo der Client hineinpasst {#role}
+
+Browseranfragen, die Agentenschleife und externe API-Clients lösen sich alle zu denselben Actions und derselben SQL-Datenbank auf – es gibt kein separates "App-Backend", das diese Schicht anspricht und das der Agent nicht auch erreichen kann. Eine Funktion hier zu bauen bedeutet, eine UI über einer Operation zu bauen, die der Agent bereits hat, oder eine neue Action zu definieren und gleichzeitig eine UI dafür zu bekommen. Siehe [Actions](/docs/actions) für die Operationsseite dieses Vertrags.
+
+Diese Seite behandelt die Verzeichnisse, in denen Sie bauen, und die Teile der Browser-Laufzeitumgebung, die sonst nirgendwo dokumentiert sind (`root.tsx`, `public/`). Die React-Hooks, die Ihre Komponenten mit Actions und dem Agenten verbinden, leben auf ihren eigenen fokussierten Seiten:
+
+| Seite                                            | Was sie behandelt                                                                                                                 |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
+| **[Daten & Sync](/docs/client-data)**            | `useActionQuery`, `useActionMutation`, `callAction` und `useDbSync`                                                               |
+| **[Agent Chat](/docs/client-agent-chat)**        | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, dynamische Vorschläge und bereitgestellter Agent-Chat-Kontextstatus    |
+| **[Fortgeschritten](/docs/client-advanced)**     | Direkter `application_state`-Zugriff, Hintergrund-Chat-Sendungen, benutzerdefinierte Vorschlags-Chips und die MCP-App-Host-Bridge |
+| **[Sync-Interna](/docs/client-sync-internals)**  | `useChangeVersion`/`useChangeVersions` zur Synchronisierung eines rohen `useQuery`                                                |
+| **[Einstiegspunkte](/docs/client-entry-points)** | `app/entry.client.tsx`/`app/entry.server.tsx` und SSR-Anpassung                                                                   |
+
+## Was in app/ und public/ steckt {#project-directories}
+
+| Pfad                                                | Was es behandelt                                                                                                       |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | Die HTML-Hülle und der Provider-Stack – siehe [Die Browser-Hülle](#app-shell) unten                                    |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration und SSR-Bootstrap – siehe [Einstiegspunkte](/docs/client-entry-points)                                       |
+| **`app/routes.ts` + `app/routes/`**                 | Dateibasierte Seiten und Navigation – siehe [Routing](/docs/client-routing)                                            |
+| **`app/components/`**                               | Ihre UI: shadcn-artige Primitive plus app-spezifische Komponenten – siehe [shadcn/ui](/docs/shadcn-ui)                 |
+| **`app/hooks/`**                                    | Daten-, Sync- und Agent-Chat-Hooks – siehe [Daten & Sync](/docs/client-data) und [Agent Chat](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | Gemeinsame Client-Utilities (App-Konfiguration, Tab-Id, `cn`) – siehe [Utilities](#utilities) unten                    |
+| **`app/design-system.ts`**                          | Optionaler benutzerdefinierter Design-System-Adapter – siehe [Custom Design Systems](/docs/custom-design-system)       |
+| **`app/i18n/`**                                     | Lokalisierte UI-Textkataloge – siehe [Internationalization](/docs/internationalization)                                |
+| **`app/global.css`**                                | Basisstile und der Tailwind-Einstiegspunkt                                                                             |
+| **`public/`**                                       | Statische Assets, die unverändert ausgeliefert werden – siehe [Statische Assets](#public-directory) unten              |
+
+## Die Browser-Hülle: root.tsx und AppProviders {#app-shell}
+
+`app/root.tsx` ist die Spitze des React-Baums: die HTML-Dokumenthülle (`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`) plus der Provider-Stack, in dem jede Route rendert.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` ist der einzelne Wrapper, der Folgendes verkabelt:
+
+- Den React-Query-Client, den `useActionQuery`/`useActionMutation` verwenden (siehe [Daten & Sync](/docs/client-data#fetching-mutating)).
+- Den i18n-Katalog, übergeben als `i18n.catalog` (siehe [Internationalization](/docs/internationalization)).
+- Clientseitige Sitzungsprüfungen: Auf einem privaten Pfad wird ein anonymer Besucher zur Anmeldung umgeleitet, bevor private UI überhaupt mountet. Übergeben Sie `isPublicPath` für öffentliche/SEO-Routen oder `sessionBypass` für eine Oberfläche, die sich anders authentifiziert, etwa über ein MCP-Embed-Token. Siehe [Authentication](/docs/authentication).
+
+Die meisten Apps mounten hier auch `<AgentSidebar>` oder `<AgentPanel>`, damit jede Route das Agent-Panel kostenlos erhält. Siehe [Drop-in Agent](/docs/drop-in-agent#sidebar).
+
+## Statische Assets: public/ {#public-directory}
+
+Alles in `public/` wird unverändert am Site-Root ausgeliefert, unverarbeitet vom Build. Jede Vorlage liefert:
+
+```text
+public/
+  favicon.svg           -> Browser-Tab-Symbol
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA-Symbole, referenziert aus manifest.json
+  manifest.json          -> Web-App-Manifest (Name, Themenfarbe, Symbole)
+  *-logo-*.svg, *-icon-*.svg -> Markenzeichen in der Standard-UI
+```
+
+`manifest.json` steuert, was angezeigt wird, wenn ein Besucher die App auf einem Homescreen oder App-Dock installiert – Name, Kurzname, Theme-/Hintergrundfarbe und der Symbolsatz:
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+Rebranden Sie eine App, indem Sie diese Dateien ersetzen und `manifest.json` sowie die `<link rel="icon">`/`<link rel="apple-touch-icon">`-Tags in `root.tsx`, die darauf verweisen, aktualisieren – es gibt keinen separaten Registrierungsschritt. Um ein vollständiges Markensystem (Farben, Schriften, Favicon) von einer bestehenden Website zu übernehmen, statt diese Dateien von Hand zu bearbeiten, siehe [Brand Systems and Figma](/docs/template-design-brand-and-figma).
+
+## Utilities: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` führt Klassennamen zusammen (clsx + tailwind-merge) und ist die Standardmethode, um bedingte Tailwind-Klassen über `app/components/` hinweg zu komponieren.
+
+## Was kommt als nächstes?
+
+- [**Daten & Sync**](/docs/client-data) — Action-Hooks und `useDbSync`
+- [**Agent Chat**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion` und dynamische Vorschläge
+- [**Fortgeschritten**](/docs/client-advanced) — Anwendungsstatus, Hintergrund-Chat-Sendungen und die MCP-App-Host-Bridge
+- [**Sync-Interna**](/docs/client-sync-internals) — `useChangeVersion` zur Synchronisierung eines rohen `useQuery`
+- [**Einstiegspunkte**](/docs/client-entry-points) — Anpassung des SSR-Bootstraps
+- [**Routing**](/docs/client-routing) — dateibasierte Seiten, dynamische Parameter und Navigation
+- [**Actions**](/docs/actions) — die `defineAction`-Oberfläche hinter jedem Daten-Hook
+- [**Custom Design Systems**](/docs/custom-design-system) — Austausch der eigenen Komponentenbibliothek über `app/design-system.ts`
+- [**Authentication**](/docs/authentication) — die Sitzungsprüfungen, die `AppProviders` auf privaten Pfaden ausführt
diff --git a/packages/core/docs/content/locales/de-DE/client-routing.mdx b/packages/core/docs/content/locales/de-DE/client-routing.mdx
new file mode 100644
index 0000000000..2e03e56636
--- /dev/null
+++ b/packages/core/docs/content/locales/de-DE/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "Routing"
+description: "Dateibasiertes Routing für agentennative Apps mit React Router v8: Seiten, dynamische Parameter und Navigation."
+---
+
+# Routing
+
+Agentennative Apps verwenden **React Router v8** mit dateibasiertem Routing über `flatRoutes()` aus `@react-router/fs-routes`. Jede Datei in `app/routes/` wird zu einer URL. Vorlagen verwenden die Punktnotationskonvention. Punkte trennen URL-Segmente innerhalb eines einzelnen Dateinamens.
+
+Diese Seite behandelt Client-Routen, die im Browser aus `app/routes/` gerenderten Seiten. Server-Routen sind ein separates System: Nitro-Dateirouten unter `server/routes/`, plus die eigenen `/_agent-native/*`-Endpunkte des Frameworks. Diese leben auf der Seite [Routen](/docs/server-routes). Die beiden teilen sich kein Verzeichnis, keine Namenskonvention und keinen Router, sodass eine Datei in `server/routes/` nie zu einer Seite hier wird und eine Datei in `app/routes/` nie zu einem Server-Endpunkt.
+
+<Diagram id="doc-block-client-routing-1" title="Dateiname → URL" summary="Jede Datei in app/routes/ wird zu einer URL. Punkte werden zu Schrägstrichen, und ein $-Segment wird zu einem dynamischen Parameter.">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Dateibasiertes Routing {#file-based-routing}
+
+### Datei → URL-Zuordnung
+
+| Datei                      | URL                    | Hinweise                                                                                                               |
+| -------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | Index-Route                                                                                                            |
+| `dashboard.tsx`            | `/dashboard`           | Einfache Seite                                                                                                         |
+| `extensions.$id.tsx`       | `/extensions/:id`      | Nistet innerhalb des `<Outlet/>` von `extensions.tsx`. `$` ist ein dynamischer Parameter                               |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | Ein nachgestelltes `_` überspringt die Verschachtelung unter `dashboard.tsx`, sodass dies eine eigenständige Seite ist |
+| `_app.tsx`                 | (kein URL-Segment)     | Pathless-Layout. Mit `_` präfixieren                                                                                   |
+| `inbox/route.tsx`          | `/inbox`               | Ordnerform. `route.tsx` ist der Index                                                                                  |
+
+Präfixen Sie ein Segment mit `$` für einen dynamischen Parameter. Präfixen Sie mit `_`, um es zu einer Pathless-Layout-Route zu machen (kein URL-Segment), oder fügen Sie ein nachgestelltes `_` vor einem Punkt hinzu, um einen scheinbar verschachtelten Pfad von der Verschachtelung unter dem Layout seines Elternteils auszunehmen. Vorlagen verwenden `flatRoutes()`. Die Punktnotationsdatei oben ist die primäre Form. Die verschachtelte Ordnerform `inbox/route.tsx` funktioniert auch.
+
+## Eine neue Seite hinzufügen {#adding-a-page}
+
+Erstellen Sie die Datei und exportieren Sie eine Standardkomponente:
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+Das ist alles. React Router erkennt sie automatisch, keine Registrierung nötig.
+
+## Dynamische Parameter {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+Das nachgestellte `_` vor dem Punkt verhindert, dass diese Seite innerhalb des `<Outlet/>` von `dashboard.tsx` verschachtelt wird, sodass sie als eigenständige vollständige Seite unter `/dashboard/:ticketId` rendert, statt innerhalb des Layouts der Ticket-Warteschlange zu erscheinen.
+
+## Navigation {#navigation}
+
+Verwenden Sie `<Link>` für clientseitige Navigation und `useNavigate()` für programmatische Navigation:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatisch
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+Keiner von beiden teilt dem Agenten von sich aus mit, was der Benutzer gerade betrachtet. Das ist ein separates Anliegen, das von `useAgentRouteState()` behandelt wird, indem die aktuelle Route in den Anwendungsstatus geschrieben wird. Siehe [Context Awareness](/docs/context-awareness).
+
+## Was kommt als nächstes?
+
+- [**Überblick**](/docs/client-overview) — wo `app/routes/` unter dem Rest von `app/` und `public/` hineinpasst
+- [**Daten & Sync**](/docs/client-data) — Daten aus einer Route lesen und schreiben
+- [**Agent Chat**](/docs/client-agent-chat) — Prompts senden und Kontext aus einer Route bereitstellen
+- [**Routen**](/docs/server-routes) — das separate Server-Routing-System: Dateirouten unter `server/routes/` und der `/_agent-native/`-Namespace des Frameworks
+- [**Context Awareness**](/docs/context-awareness) — wie der Agent die aktuelle Route und Auswahl erfährt
diff --git a/packages/core/docs/content/locales/de-DE/client-sync-internals.mdx b/packages/core/docs/content/locales/de-DE/client-sync-internals.mdx
new file mode 100644
index 0000000000..23b1b9da26
--- /dev/null
+++ b/packages/core/docs/content/locales/de-DE/client-sync-internals.mdx
@@ -0,0 +1,127 @@
+---
+title: "Sync-Interna"
+description: "Der Änderungsversionsmechanismus hinter useDbSync: useChangeVersion/useChangeVersions zur Synchronisierung eines rohen useQuery, und die zwei Latenzpfade, die ein erneutes Abrufen nehmen kann."
+---
+
+# Sync-Interna
+
+[Live Sync](/docs/key-concepts#polling-sync) behandelt das mentale Modell: Ein Agenten-Schreibvorgang wird zu einem Änderungsereignis, `useDbSync()` nimmt es auf, und betroffene Abfragen rufen erneut ab. Diese Seite behandelt den Mechanismus darunter, den die meisten Apps nie direkt anfassen: die Änderungsversionszähler, die `useDbSync()` erhöht, und wie man sie in einen rohen `useQuery()`-Aufruf einbaut, der nicht über `useActionQuery()` läuft.
+
+`useActionQuery()` ruft bereits automatisch erneut ab, wenn eine mutierende Action abschließt (siehe [Daten & Sync](/docs/client-data#fetching-mutating)). Greifen Sie nur zu `useChangeVersion()`/`useChangeVersions()`, wenn Sie einen rohen `useQuery()`-Aufruf außerhalb dieses Pfads synchronisieren, etwa einen niedrigen Client-Helfer, der den Integrationsstatus liest.
+
+## Wie Änderungsversionen funktionieren {#how-it-works}
+
+Wenn eine serverseitige Datenbankmutation auftritt, zeichnet der Server ein Änderungsereignis mit einem `source`-Schlüssel auf. `useDbSync()` empfängt dieses Ereignis und erhöht einen lokalen Zähler für diese Quelle. Das Einbauen des Zählers in einen React-Query-Schlüssel lässt die Abfrage automatisch erneut abrufen, sobald das Backend neue Aktivität für diese Quelle meldet.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description:
+        'Die zu beobachtende Änderungsereignisquelle, z. B. `"dashboards"`.',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description:
+      "Ein Zähler, der sich erhöht, sobald die angegebene Quelle mutiert wird.",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description:
+        "Mehrere gleichzeitig zu beobachtende Änderungsereignisquellen.",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "Die Summe der Versionszähler für jede angegebene Quelle.",
+  }}
+/>
+
+Im folgenden Beispiel liest ein roher `useQuery()`-Aufruf direkt ein Dashboard und baut den Versionszähler der Quelle `"dashboards"` in seinen Abfrageschlüssel ein, sodass er erneut abruft, sobald sich diese Quelle ändert:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` behält die vorherigen Daten während des erneuten Abrufens auf dem Bildschirm, sodass die Ansicht nicht zu einem Ladezustand flackert.
+
+## Zwei Wege zu einem erneuten Abruf {#latency-models}
+
+Eine Mutation erreicht die UI auf einem von zwei Wegen, und diese haben unterschiedliche Latenz.
+
+Eine lokale Mutation, eine, die Ihr eigener `useActionMutation()`-Aufruf gerade ausgeführt hat, löst bei Erfolg sofort ein `source: "action"`-Ereignis aus. Jede Abfrage, die von dieser Action abhängt, ruft sofort erneut ab. Es gibt keine Roundtrip-Verzögerung, da der Tab, der den Schreibvorgang ausgeführt hat, bereits davon weiß.
+
+Eine entfernte Mutation, vom Agenten, einem Webhook, einem anderen Tab oder einem anderen Benutzer, muss diesen Tab erst erreichen. `useDbSync()` nimmt sie fast sofort über SSE auf, oder über den Polling-Fallback innerhalb von etwa zwei Sekunden, wenn SSE nicht verfügbar ist. Erst wenn dieses Ereignis eintrifft, erhöht sich der entsprechende Versionszähler und die Abfrage ruft im Hintergrund erneut ab.
+
+<Diagram id="doc-block-client-sync-internals-3" title="Zwei Wege zu einem erneuten Abruf" summary="Eine lokale Mutation macht ihre eigenen Caches sofort ungültig. Ein entfernter Schreibvorgang erreicht diesen Tab über SSE oder den Polling-Tick als Fallback.">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">Dieser Tab</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >löst bei Erfolg source: "action" aus &rarr; sofortiges lokales erneutes
+        Abrufen</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">Agent · Webhook · anderer Tab</span
+      ><strong>Entfernter Schreibvorgang</strong
+      ><small class="diagram-muted"
+        >SSE-Push, oder der ~2s-Polling-Tick als Fallback &rarr; Version erhöht
+        sich &rarr; erneutes Abrufen im Hintergrund</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## Was kommt als nächstes?
+
+- [**Live Sync**](/docs/key-concepts#polling-sync) — das konzeptuelle mentale Modell, das diese Seite unterlegt
+- [**Daten & Sync**](/docs/client-data) — `useActionQuery`/`useDbSync`, die die meisten Seiten statt dieser Primitive verwenden sollten
+- [**Fortgeschritten**](/docs/client-advanced) — die anderen niedrigeren Client-Primitive und Escape-Hatches
diff --git a/packages/core/docs/content/locales/de-DE/client.mdx b/packages/core/docs/content/locales/de-DE/client.mdx
deleted file mode 100644
index 735f26d906..0000000000
--- a/packages/core/docs/content/locales/de-DE/client.mdx
+++ /dev/null
@@ -1,470 +0,0 @@
----
-title: "Kunde"
-description: "React-Hooks und Dienstprogramme für agentennative Apps: sendToAgentChat, optionaler Agent-Chat-Kontextstatus, useDbSync, useAgentChatGenerating und cn."
----
-
-# Kunde
-
-`@agent-native/core` stellt React-Hooks und Dienstprogramme für die Browserseite agentennativer Apps bereit.
-
-Diese Client/React APIs werden sowohl aus `@agent-native/core` als auch aus `@agent-native/core/client` exportiert. Importieren Sie sie aus Gründen der Übersichtlichkeit und korrekten Bündelung aus `@agent-native/core/client` (dem Browsereintrag), da das bloße `@agent-native/core`-Root standardmäßig in den Node-Build aufgelöst wird.
-
-Informationen zum dateibasierten Routing – Hinzufügen von Seiten, dynamischen Parametern und Navigation – siehe [Routing](/docs/routing).
-
-## Daten abrufen und ändern {#fetching-mutating}
-
-Die primäre Möglichkeit, App-Daten vom Browser zu lesen und zu schreiben, sind die Aktions-Hooks. Schreiben Sie `fetch`-Aufrufe an `/_agent-native/*`-Routen niemals handschriftlich – verwenden Sie stattdessen die benannten Helfer (siehe [Actions](/docs/actions)).
-
-<Diagram id="doc-block-1pykvnz" title="Die Browser-Datenschleife" summary={"Hooks lesen und schreiben durch Aktionen; useDbSync überwacht die Datenbank, sodass Agent- und Hintergrundschreibvorgänge automatisch dieselben Caches erneut abrufen."}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>SQL-Datenbank</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(opts) {#sendtoagentchat}
-
-Senden Sie eine Nachricht an den Agenten-Chat über postMessage – die übliche Methode zum Delegieren einer KI-Aufgabe aus einer UI-Interaktion. Übergeben Sie `context` für versteckten Modellkontext und `submit: true`, um es sofort zu senden, oder `submit: false`, um einen Entwurf vorab auszufüllen, den der Benutzer zuerst überprüft.
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-In einer mit `embedApp()` erstellten MCP-App-Einbettung werden automatisch Nachrichten übermittelt
-(`submit` weggelassen oder `true`) werden an die MCP App-Host-Bridge weitergeleitet, die
-fordert den enthaltenden Host auf, versteckten Kontext hinzuzufügen und den sichtbaren Benutzerzug zu senden.
-`context` bleibt für das Model sichtbar, ohne als Benutzer-Chat gepostet zu werden.
-`submit: false` behält das lokale Vorausfüll-/Überprüfungsverhalten bei, da MCP-Apps dies nicht tun
-Definieren Sie eine Standard-Entwurfsvorausfüllung API. Intern ist dies der Pfad zum übermittelten Chat
-tauchte manchmal als `agentNative.submitChat` auf; App-Code sollte aufrufen
-`sendToAgentChat()`, anstatt dieses Ereignis direkt zu veröffentlichen.
-
-### Stille Hintergrundsendungen {#background-send}
-
-Verwenden Sie `background: true`, wenn eine UI-Aktion die eigentliche Arbeit eines Agenten einleiten soll.
-Seitenleiste öffnen oder fokussieren. Dadurch wird immer noch ein normaler Chat-Thread/Lauf erstellt,
-verwendet die Tools/actions/context des Agenten und sorgt dafür, dass die Arbeit beobachtbar bleibt
-das Lauffach; Es handelt sich nicht um einen einmaligen Modellaufruf.
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` soll mit `newTab` gepaart werden, damit die versteckte Arbeit nicht funktioniert
-überschreibt die aktive Konversation des Benutzers. Verwenden Sie das zurückgegebene `tabId`, wenn UI
-muss den Follow-up-Status korrelieren oder später einen Deep-Link zum Lauf erstellen.
-
-### AgentChatMessage {#agentchatmessage}
-
-| Option                | Typ         | Beschreibung                                                                                       |
-| --------------------- | ----------- | -------------------------------------------------------------------------------------------------- |
-| `message`             | `string`    | Die sichtbare Eingabeaufforderung, die an den Chat gesendet wurde                                  |
-| `context`             | `string?`   | Versteckter Kontext angehängt (nicht im Chat-Oberfläche angezeigt)                                 |
-| `submit`              | `boolean?`  | true = automatische Übermittlung, false = nur Vorabausfüllung                                      |
-| `newTab`              | `boolean?`  | Erstellen Sie einen separaten Chat-Thread für diese Eingabeaufforderung                            |
-| `background`          | `boolean?`  | Mit `newTab` ausführen, ohne die Registerkarte zu fokussieren, und den Lauf in `RunsTray` anzeigen |
-| `openSidebar`         | `boolean?`  | Setzen Sie „false“, um zu senden/vorab auszufüllen, ohne die Seitenleiste zu öffnen                |
-| `projectSlug`         | `string?`   | Optionaler Projekt-Slug für strukturierten Kontext                                                 |
-| `preset`              | `string?`   | Optionaler voreingestellter Name für nachgeschaltete Verbraucher                                   |
-| `referenceImagePaths` | `string[]?` | Optionale Referenzbildpfade                                                                        |
-
-## Agent-Chat-Kontextstatus (Erweitert) {#agent-chat-context-state}
-
-Die Kontextstatus-APIs sind optionale Installationen für UI, die eine bidirektionale Synchronisierung mit erfordern
-Staging-Kontext-Chips: Rendern der aktuell bereitgestellten Elemente außerhalb des Verfassenrs
-zeigt an, ob ein Element bereits angehängt ist, oder stellt explizite Angaben bereit
-Steuerelemente entfernen/löschen.
-
-Nehmen Sie diese Helfer nicht für ein einfaches „Senden Sie dies an den Agenten“ oder
-Flows „Diesen Entwurf zur Überprüfung vorab ausfüllen“. Verwenden Sie `sendToAgentChat()` mit `context`
-und `submit` für diese.
-
-| API                               | Verwenden wenn                                                                                                    |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `useAgentChatContext()`           | Eine React-Komponente benötigt die live bereitgestellte Kontextliste                                              |
-| `setAgentChatContextItem(item)`   | Imperativer Code sollte ein Schlüsselkontextelement bereitstellen oder ersetzen                                   |
-| `listAgentChatContext()`          | Nicht-React-Code benötigt einen einmaligen Snapshot des bereitgestellten Kontexts                                 |
-| `removeAgentChatContextItem(key)` | UI sollte ein bereitgestelltes Kontextelement durch sein stabiles `key` entfernen                                 |
-| `clearAgentChatContext()`         | UI sollte den gesamten bereitgestellten Kontext löschen, z. B. nach einem Zurücksetzen der Ansicht oder des Modus |
-| `refreshAgentChatContext()`       | Imperativer Code sollte den neuesten persistenten Kontext-Snapshot erneut lesen                                   |
-
-`useAgentChatContext()` gibt `{ items, set, remove, clear, refresh }` zurück.
-
-## openAgentSettings(Abschnitt?) {#openagentsettings}
-
-Verwenden Sie `openAgentSettings()`, wenn eine App-Einstellungsseite oder eine Setup-Karte geöffnet werden soll
-Registerkarte „Einstellungen“ der Agent-Seitenleiste. Übergeben Sie eine Abschnitts-ID wie `"llm"`, `"secrets"`,
-`"automations"`, `"voice"` oder `"limits"`, um einen bestimmten Abschnitt zu öffnen.
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-Ziehen Sie diesen Helfer dem direkten Versand von `agent-panel:open-settings` vor.
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` ist für zwingenden Code, der nur die
-aktuelle bereitgestellte Elemente einmal. `clearAgentChatContext()` ist absichtlich breit gefasst; verwenden
-`removeAgentChatContextItem(key)`, wenn sich nur eine Auswahl geändert hat.
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| Option        | Typ        | Beschreibung                                                                                  |
-| ------------- | ---------- | --------------------------------------------------------------------------------------------- |
-| `key`         | `string`   | Stabile Kennung, die zum Ersetzen eines vorhandenen Nuggets verwendet wird                    |
-| `title`       | `string`   | Kurzbezeichnung wird im Verfassenr-Chip angezeigt                                             |
-| `context`     | `string`   | Versteckter Kontext in der nächsten übermittelten Eingabeaufforderung enthalten               |
-| `openSidebar` | `boolean?` | Standardmäßig ist true; Übergeben Sie „false“, um den Kontext stillschweigend bereitzustellen |
-
-## askUserQuestion(opts) {#ask-user-question}
-
-Stellen Sie dem Benutzer eine Multiple-Choice-Frage aus dem App-Code und rendern Sie diese inline im
-Agent-Panel und **warten Sie auf ihre Antwort**. Es ist der clientseitige Zwilling von
-Das integrierte `ask-question`-Tool des Agenten: Es schreibt ein `GuidedQuestionPayload` in den
-`"guided-questions"` Anwendungsstatusschlüssel (wo der gemountete
-`GuidedQuestionFlow` rendert es) und zeigt das Agentenfeld an, sodass die Frage lautet
-sichtbar. Im Gegensatz zum Agenten-Tool – dessen Antwort an den Agenten zurückfließt –
-`askUserQuestion()` **wird mit der Antwort an den Anrufer aufgelöst**, sodass UI dies kann
-darauf verzweigen.
-
-Verwenden Sie es, wenn der UI vor ihm genau eine kleine Entscheidung (2–4 Optionen) benötigt.
-startet die Agentenarbeit – anstatt ein benutzerdefiniertes Modal zu erstellen. Greifen Sie nach
-Verfassenr für Freiformdetails und ein Formular/Popover für die Eingabe mehrerer Felder.
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-Jede Option ist `{ label, value?, description?, preview?, recommended? }`; `value`
-ist standardmäßig `label` und `preview` rendert ein kleines Mockup/Code-Snippet unter
-Option. Das Versprechen wird mit dem ausgewählten `value` (oder `value[]`, wenn
-`allowMultiple`), die Freitextzeichenfolge, wenn der Benutzer „Andere“ auswählt, oder `null`
-Wenn sie überspringen, bleibt es ausstehend, bis der Benutzer antwortet. Erfordert das Agentenpanel
-muss gemountet werden (ist in jeder Vorlage enthalten).
-
-Der Agent erreicht das gleiche UI über sein `ask-question`-Tool: Lassen Sie lieber das
-Agent fragt, wenn _es_ auf einen echten Fork trifft, der nicht aus dem Kontext aufgelöst werden kann; verwenden
-`askUserQuestion()`, wenn der _UI_ eine Aktion für eine Auswahl steuern muss.
-
-## MCP App Host Bridge {#mcp-app-host-bridge}
-
-Routen, die als MCP-Apps eingebettet sind, sollten URL-first sein: Laden Sie das aktuelle Artefakt von
-Pfad-/Abfrageparameter, rendern die echte React-Route oder eine fokussierte gemeinsame Komponente
-und verwenden Sie die Host-Bridge nur für Host-eigenes Verhalten. `@agent-native/core/client`
-exportiert den Aufruf der eingebetteten Routen des Helfers:
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()` liest den neuesten gepushten Host-Kontext-Snapshot;
-`useMcpAppHostContext()` abonniert React-Komponenten für Änderungen. Die Anfrage
-Helfer (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
-`updateMcpAppModelContext`) geben `false` außerhalb eines eingebetteten MCP-App-Frames zurück, oder
-`Promise<boolean>` innerhalb eines Frames. `sendToAgentChat()` verwendet dieselbe Bridge für
-Automatisch übermittelte Eingabeaufforderungen von eingebetteten Routen.
-
-Die Brücke selbst – die `ui/*` JSON-RPC-Nachrichten, die `agentNative.mcpHost.*`
-Wrapper-Relay, Transplantation vs. Controlled-Frame-Rendering, Host-Kontext und
-Anzeigemodus-Anfragen – ist Eigentum von
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## Dynamische Vorschläge {#dynamic-suggestions}
-
-`<AgentSidebar>`, `<AgentPanel>` und `<AssistantChat>` führen standardmäßig statische `suggestions` mit kontextbezogenen Vorschlägen zusammen. Das Framework liest `navigation`, `selection`, `pending-selection-context` und den aktuellen URL aus dem Anwendungsstatus, während ein leerer Chat sichtbar ist, und bietet dann Eingabeaufforderungschips an, die zum aktuellen Bildschirm passen.
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-Legen Sie `dynamicSuggestions={false}` fest, um nur statische Chips zu behalten. Übergeben Sie `getSuggestions`, wenn eine App deterministische domänenspezifische Chips aus demselben Anwendungsstatuskontext benötigt.
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-React-Hook, der sendToAgentChat mit der Ladestatusverfolgung umschließt:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-`isGenerating` wird wahr, wenn Sie `send()` aufrufen, und wird automatisch auf falsch zurückgesetzt, wenn der Agent die Generierung abgeschlossen hat.
-
-## useDbSync(Optionen?) {#usedbsync}
-
-React-Hook (früher `useFileWatcher`), der über SSE auf Datenbankänderungen lauscht, auf Abfragen zurückgreift und die Framework-Abfragecaches ungültig macht, die dafür sorgen, dass UI mit Agent-Schreibvorgängen in Einklang steht:
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### Optionen {#usedbsync-options}
-
-| Option             | Typ                | Beschreibung                                                                                                                         |
-| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `queryClient`      | `QueryClient?`     | React-Abfrage-Client für Cache-Ungültigmachung                                                                                       |
-| `queryKeys`        | `string[]?`        | Veraltet und ignoriert; für alte Anrufseiten beibehalten                                                                             |
-| `pollUrl`          | `string?`          | Polling-Endpunkt URL. Standard: `"/_agent-native/poll"`                                                                              |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                                               |
-| `interval`         | `number?`          | Abfrageintervall in ms. Standard: `2000`                                                                                             |
-| `fallbackInterval` | `number?`          | Fallback-Abfrageintervall, wenn SSE nicht verfügbar ist. Standard: `15000`                                                           |
-| `pauseWhenHidden`  | `boolean?`         | Pausieren Sie die Abfrage, wenn die Browser-Registerkarte ausgeblendet ist. Standard: `true`                                         |
-| `ignoreSource`     | `string?`          | Anforderungsquelle pro Tab, die ignoriert werden soll, damit ein Tab nicht erneut aus seinen eigenen Schreibvorgängen abgerufen wird |
-| `onEvent`          | `(data) => void`   | Optionaler Rückruf, wenn SSE/polling ein Änderungsereignis empfängt                                                                  |
-
-Für normales CRUD bevorzugen Sie `useActionQuery` und `useActionMutation`; mutierendes actions gibt `source: "action"` aus und diese Hooks werden automatisch erneut abgerufen.
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-Das Framework verwendet Änderungsversionen, um React Abfrage-Caches mit Änderungen zu synchronisieren, die von Hintergrundagenten, Cron-Jobs oder anderen Benutzern vorgenommen wurden.
-
-Wenn eine serverseitige Datenbankmutation auftritt, zeichnet der Server ein Änderungsereignis mit einem bestimmten `source`-Schlüssel auf. Der `useDbSync`-Listener des Clients empfängt diese Ereignisse und erhöht den lokalen Änderungsversionszähler für diese Quelle. Indem Sie den Versionszähler in Ihre React-Abfrageschlüssel integrieren, werden Abfragen automatisch erneut abgerufen, wenn das Backend den Client über neue Aktivitäten benachrichtigt.
-
-- **`useChangeVersion(source: string): number`** – gibt einen Zähler zurück, der immer dann erhöht wird, wenn der angegebene `source` mutiert wird.
-- **`useChangeVersions(sources: readonly string[]): number`** – gibt die Summe der Versionszähler für mehrere Quellen zurück.
-
-### Beispiel: Synchronisieren einer Rohabfrage mit der Datenbank
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### Latenzmodelle und Invalidierungsverhalten
-
-- **UI-initiierte Mutationen:** Wenn Sie eine Aktion vom UI mit `useActionMutation` ausführen, löst die Mutation bei Erfolg sofort ein lokales Ereignis mit `source: "action"` aus. Dies löst abhängig von dieser Aktion einen **sofortigen, optimistischen erneuten Abruf** aller Abfrageschlüssel aus und vermeidet so visuelle Verzögerungen.
-- **Hintergrund- oder Agent-Mutationen:** Wenn der KI-Agent, ein Webhook oder ein Hintergrund-Worker Daten mutiert, wird das Update an den Client gesendet. Der `useDbSync` des Clients erfasst dies entweder sofort über SSE (vom Server gesendete Ereignisse) oder greift auf den **2-Sekunden-Polling-Tick** zurück. Die Version des Abfrageschlüssels ändert sich dann und löst einen erneuten Abruf im Hintergrund aus.
-
-<Diagram id="doc-block-1pgr3u2" title="Zwei Wege zu einem erneuten Abruf" summary={"Eine lokale Mutation macht ihre eigenen Caches sofort ungültig; Ein Remote-Schreibvorgang erreicht diese Registerkarte über SSE oder den Polling-Tick als Fallback."}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">Dieser Tab</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">Agent · Webhook · anderer Tab</span
-      ><strong>Remote-Schreibvorgang</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...Eingaben) {#cn}
-
-Dienstprogramm zum Zusammenführen von Klassennamen (clsx + tailwind-merge):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/de-DE/drop-in-agent.mdx b/packages/core/docs/content/locales/de-DE/drop-in-agent.mdx
index 57e4f32123..c32c1ca13e 100644
--- a/packages/core/docs/content/locales/de-DE/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/de-DE/drop-in-agent.mdx
@@ -225,7 +225,7 @@ Verfolgung. Es stiehlt einfach nicht den Fokus vom aktuellen Seitenleistenstatus
 
 Wenn dieselbe Route als MCP-App eingebettet ist, wird sie übermittelt
 `sendToAgentChat()`-Anrufe werden an den Host-Chat weitergeleitet, sofern dies unterstützt wird; siehe
-[Client](/docs/client#sendtoagentchat) für das MCP-App-Bridge-Verhalten.
+[Agent-Chat](/docs/client-agent-chat#sendtoagentchat) für das MCP-App-Bridge-Verhalten.
 
 Wenn Sie einen Ladezustand wünschen, verwenden Sie den Hook `useSendToAgentChat()` – er gibt sowohl `send` als auch `isGenerating` zurück:
 
diff --git a/packages/core/docs/content/locales/de-DE/notifications.mdx b/packages/core/docs/content/locales/de-DE/notifications.mdx
index b9d378701f..eeaade16c7 100644
--- a/packages/core/docs/content/locales/de-DE/notifications.mdx
+++ b/packages/core/docs/content/locales/de-DE/notifications.mdx
@@ -363,7 +363,7 @@ Automatisierungen können dies verketten – z.B. _"Wenn eine kritische Benachri
 ## Wie es funktioniert {#internals}
 
 - **Owner Scoping** – jede Zeile hat eine `owner`-Spalte; jede Abfrage filtert danach; Jede Route verwendet die E-Mail-Adresse der authentifizierten Sitzung. Benutzer sehen nie die Benachrichtigungen der anderen.
-- **Umfrageintegration** – jede Mutation ruft `recordChange()` auf, sodass Vorlagen, die [`useDbSync`](/docs/client) verwenden, ohne zusätzliche Verkabelung automatisch ungültig werden.
+- **Umfrageintegration** – jede Mutation ruft `recordChange()` auf, sodass Vorlagen, die [`useDbSync`](/docs/client-data#usedbsync) verwenden, ohne zusätzliche Verkabelung automatisch ungültig werden.
 - **Best-Effort-Fanout** – Kanalfehler werden abgefangen und protokolliert; Ein ausgefallener Kanal blockiert nicht andere oder das Schreiben in den Posteingang.
 - **Fire-and-Forget** – `notify()` kehrt zurück, nachdem der Posteingangsschreibvorgang abgeschlossen ist; Benutzerdefinierte Kanäle werden im Hintergrund ausgeführt.
 
diff --git a/packages/core/docs/content/locales/de-DE/progress.mdx b/packages/core/docs/content/locales/de-DE/progress.mdx
index f6a55328d6..65b033b109 100644
--- a/packages/core/docs/content/locales/de-DE/progress.mdx
+++ b/packages/core/docs/content/locales/de-DE/progress.mdx
@@ -233,7 +233,7 @@ Benachrichtigen me that run {{runId}} has failed.
 ## Wie es funktioniert {#internals}
 
 - **Owner Scoping** – jede Zeile hat eine `owner`-Spalte; Jede Abfrage filtert danach. Benutzer sehen nur ihre eigenen Läufe.
-- **Umfrageintegration** – jede Mutation ruft `recordChange()` auf, sodass Vorlagen, die [`useDbSync`](/docs/client) verwenden, ohne zusätzliche Verkabelung automatisch ungültig werden.
+- **Umfrageintegration** – jede Mutation ruft `recordChange()` auf, sodass Vorlagen, die [`useDbSync`](/docs/client-data#usedbsync) verwenden, ohne zusätzliche Verkabelung automatisch ungültig werden.
 - **Tabellenname** – das Framework verfügt außerdem über eine `agent_runs`-Tabelle für die interne Nachverfolgung des Agent-Chat-Turn-Lebenszyklus. Das Fortschrittsprimitiv verwendet `progress_runs`, um die beiden Anliegen getrennt zu halten.
 - **Prozent-Klammerung** – Werte werden auf `[0, 100]` geklemmt und beim Schreiben auf eine Ganzzahl gerundet.
 
@@ -241,4 +241,4 @@ Benachrichtigen me that run {{runId}} has failed.
 
 - [**Notifications**](/docs/notifications) – koppeln Sie es mit `manage-progress` (`action=complete`), um dem Benutzer mitzuteilen, wann die Arbeit beendet ist
 - [**Automations**](/docs/automations) – langsamer Watchdog läuft über `run.progress.updated`
-- [**Client**](/docs/client) – `useDbSync` für Echtzeit-Cache-Ungültigmachung
+- [**Daten & Sync**](/docs/client-data) – `useDbSync` für Echtzeit-Cache-Ungültigmachung
diff --git a/packages/core/docs/content/locales/de-DE/real-time-collaboration.mdx b/packages/core/docs/content/locales/de-DE/real-time-collaboration.mdx
index 18e7b338ac..67c1ccff22 100644
--- a/packages/core/docs/content/locales/de-DE/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/de-DE/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ Agent-natives Kollaborationsmodell.
 Das Bearbeiten zusammen mit dem Agenten fühlt sich an wie die Arbeit in einem kollaborativen Editor mit
 einem Kollegen, der sowohl spontan als auch unermüdlich ist:
 
-Wenn Sie UI nur zum Aktualisieren benötigen, wenn der Agent oder ein anderer Benutzer in SQL schreibt, brauchen Sie nichts davon – verwenden Sie [`useDbSync`](/docs/client). Diese Seite dient der gemeinsamen Bearbeitung eines einzelnen Rich-Text-Dokuments auf Zeichenebene (gemeinsame Cursor, konfliktfreies Zusammenführen). Beide nutzen denselben `/_agent-native/poll`-Kanal.
+Wenn Sie UI nur zum Aktualisieren benötigen, wenn der Agent oder ein anderer Benutzer in SQL schreibt, brauchen Sie nichts davon – verwenden Sie [`useDbSync`](/docs/client-data#usedbsync). Diese Seite dient der gemeinsamen Bearbeitung eines einzelnen Rich-Text-Dokuments auf Zeichenebene (gemeinsame Cursor, konfliktfreies Zusammenführen). Beide nutzen denselben `/_agent-native/poll`-Kanal.
 
 Dies basiert auf drei kampferprobten Technologien: **Yjs** (CRDT für konfliktfreies Zusammenführen), **TipTap** (Rich-Text-Editor) und **abfragebasierte Synchronisierung** (funktioniert in allen Bereitstellungsumgebungen, einschließlich Serverless und Edge).
 
@@ -774,7 +774,7 @@ Ebenen über dem gleichen Bewusstseinszustand.
 
 ## Verwandte Dokumente {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) – der `useDbSync` + `useChangeVersion`
+- [Sync-Interna](/docs/client-sync-internals) – der `useDbSync` + `useChangeVersion`
   System, das den `updatedAt` Bump-Drive-Editor-Abgleich ermöglicht.
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   und `assertAccess` für ressourcenbezogene Zusammenarbeit.
diff --git a/packages/core/docs/content/locales/de-DE/routing.mdx b/packages/core/docs/content/locales/de-DE/routing.mdx
deleted file mode 100644
index ae5daf8a85..0000000000
--- a/packages/core/docs/content/locales/de-DE/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "Routing"
-description: "Dateibasiertes Routing für agentennative Apps mit React Router v8 – Seiten, dynamische Parameter und Navigation."
----
-
-# Routing
-
-Agent-native Apps verwenden **React Router v8** mit dateibasiertem Routing über `flatRoutes()` von `@react-router/fs-routes`. Jede Datei in `app/routes/` wird zu einem URL. Vorlagen verwenden die Punktnotationskonvention – Punkte trennen URL-Segmente innerhalb eines einzelnen Dateinamens.
-
-## Dateibasiertes Routing {#file-based-routing}
-
-### Datei → URL-Zuordnung
-
-| Datei                 | URL                | Notizen                                  |
-| --------------------- | ------------------ | ---------------------------------------- |
-| `_index.tsx`          | `/`                | Indexroute                               |
-| `settings.tsx`        | `/settings`        | Einfache Seite                           |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | Punkt = `/`, `$` = dynamischer Parameter |
-| `_app.tsx`            | (kein URL-Segment) | Pfadloses Layout – Präfix mit `_`        |
-| `inbox/route.tsx`     | `/inbox`           | Ordnerform – `route.tsx` ist der Index   |
-
-Stellen Sie einem Segment `$` für einen dynamischen Parameter voran. Setzen Sie als Präfix `_`, um eine pfadlose Layoutroute zu erstellen (kein URL-Segment). Vorlagen verwenden `flatRoutes()` – die obige Punktnotationsdatei ist primär; Die verschachtelte Ordnerform `inbox/route.tsx` funktioniert auch.
-
-<Diagram id="doc-block-11pjycp" title={"Das pfadlose Layout umschließt die Seiten"} summary={"Ein _app.tsx-Layout (kein URL-Segment) rendert die gemeinsam genutzte Shell einmal; übereinstimmende Seiten werden in ihrem <Outlet/> gerendert, sodass die Agent-Seitenleiste bei der Navigation nie wieder angezeigt wird."}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >pfadloses Layout · persistente Shell + Agent-Seitenleiste</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## Eine neue Seite hinzufügen {#adding-a-page}
-
-Erstellen Sie die Datei und exportieren Sie eine Standardkomponente:
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-Das ist alles – der React-Router nimmt es automatisch auf, keine Registrierung erforderlich.
-
-## Dynamische Parameter {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## Navigation {#navigation}
-
-Verwenden Sie `<Link>` für die clientseitige Navigation und `useNavigate()` für die programmgesteuerte Navigation:
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## Was kommt als nächstes?
-
-- [**Client**](/docs/client) – die agentennativen Browser-Hooks und Dienstprogramme
-- [**Server**](/docs/server) – dateibasierte Serverrouten und der `/_agent-native/`-Namespace
diff --git a/packages/core/docs/content/locales/es-ES/client-advanced.mdx b/packages/core/docs/content/locales/es-ES/client-advanced.mdx
new file mode 100644
index 0000000000..47f1878436
--- /dev/null
+++ b/packages/core/docs/content/locales/es-ES/client-advanced.mdx
@@ -0,0 +1,193 @@
+---
+title: "Avanzado"
+description: "Primitivos de bajo nivel de app/ y vías de escape: acceso directo al estado de la aplicación, envíos de chat en segundo plano, chips de sugerencias personalizadas y el puente de host de aplicaciones MCP."
+---
+
+# Avanzado
+
+Resumen, Datos y sincronización, Chat del Agent y Enrutamiento cubren el caso típico: los hooks y helpers que necesita la mayoría de las páginas. Esta página cubre los primitivos de más bajo nivel y las vías de escape más específicas que hay debajo. La mayoría de las apps nunca los tocan directamente. Recurre a uno cuando estés construyendo algo más personalizado de lo que soportan los hooks predeterminados, como una sincronización de selección personalizada o una aplicación MCP embebida. Para sincronizar un `useQuery` sin procesar con una clave hecha a mano, consulta [Sincronización interna](/docs/client-sync-internals) en su lugar.
+
+## Estado de la aplicación {#application-state}
+
+`application_state` es el almacén clave/valor respaldado por SQL que lee el agente para saber qué está mirando actualmente la UI, incluyendo navegación, selección y otro contexto de objeto enfocado (consulta [Conciencia del contexto](/docs/context-awareness)). `useAgentRouteState` y `useSemanticNavigationState` (también cubiertos en Conciencia del contexto) ya envuelven esto para el caso común de navegación. Recurre a los primitivos siguientes directamente cuando estés sincronizando algo que ellos no cubren, como una selección personalizada, o escribiendo desde fuera del renderizado de un componente.
+
+### readClientAppState {#read-client-app-state}
+
+Lee el valor actual de una clave. Se resuelve con lo último que se escribió para esa clave, o `null` si nunca se ha escrito la clave.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+Escribe un valor para una clave. A diferencia de `setClientAppState` de abajo, siempre escribe, incluso si pasas `null`. Pasar `undefined` lanza un error en su lugar, ya que `undefined` no es JSON válido. Usa `setClientAppState(key, undefined)` o `deleteClientAppState()` para borrar una clave.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+El wrapper de conveniencia al que debería recurrir la mayoría del código de UI: escribe el valor, o borra la clave cuando pasas `null`/`undefined`. Usa este en lugar de `writeClientAppState` a menos que un sitio de llamada realmente necesite "siempre escribir, nunca borrar."
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+Elimina una clave por completo.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+Lee varias claves en una sola solicitud. Devuelve `{ values, missing }`. `values` tiene una entrada para cada clave para la que el servidor tiene una fila, incluyendo una clave que se escribió explícitamente como `null`. `missing` lista las claves que nunca se han escrito en absoluto. Así es como "nunca escrito" se mantiene distinguible de "escrito como null."
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+Las solicitudes de más de 100 claves se dividen en fragmentos automáticamente. `readClientAppState()` en sí está construido sobre esto: las llamadas realizadas en el mismo tick se combinan en una sola solicitud por lotes internamente, así que llamarlo muchas veces en un solo ciclo de renderizado cuesta un viaje de ida y vuelta, no uno por llamada.
+
+### Opciones {#application-state-options}
+
+`signal` es aceptado por las cinco funciones anteriores, para cancelar una llamada en curso. `requestSource` y `keepalive` solo aplican a las tres funciones de escritura, ya que no significan nada para una lectura.
+
+| Opción          | Tipo           | Aplica a                                                           | Descripción                                                                                                              |
+| --------------- | -------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Etiqueta la escritura con un id para que un `useDbSync({ ignoreSource })` coincidente pueda omitir su recuperación       |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Permite que la solicitud sobreviva al descargarse la página. Úsalo para escrituras de limpieza como borrar una selección |
+| `signal`        | `AbortSignal?` | las cinco funciones                                                | Cancela la solicitud                                                                                                     |
+
+### Comportamiento ante fallos {#failure-behavior}
+
+Las cinco funciones lanzan un error ante una solicitud fallida, una respuesta no-2xx, o un cuerpo que no se puede analizar. El `Error` lanzado lleva una propiedad `.status` cuando el servidor respondió, para que quien llama pueda bifurcar según el estado HTTP si es necesario. Envuelve una llamada en `try`/`catch`, o déjala propagarse a un límite de error, igual que cualquier otra llamada de red.
+
+### Qué es TAB_ID {#tab-id}
+
+`requestSource` se establece comúnmente como `TAB_ID`, una constante simple que cada plantilla exporta desde `app/lib/tab-id.ts`: una cadena aleatoria corta que permanece igual durante la vida de una pestaña y difiere entre pestañas. Emparejar `requestSource: TAB_ID` en una escritura con `useDbSync({ ignoreSource: TAB_ID })` en el lado de lectura es cómo una pestaña evita recuperar su propia escritura mientras sigue reaccionando a todas las demás. Consulta [Conciencia del contexto](/docs/context-awareness#jitter-prevention) para el recorrido completo.
+
+## sendToAgentChat: envíos en segundo plano {#background-send}
+
+Usa `background: true` cuando una acción de UI deba iniciar trabajo real del agente sin
+abrir ni enfocar la barra lateral. Esto sigue creando un hilo/ejecución de chat normal,
+usa las herramientas/acciones/contexto del agente y mantiene el trabajo observable a través de
+la bandeja de ejecuciones. No es una llamada al modelo puntual y sin procesar.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` está pensado para combinarse con `newTab` para que el trabajo oculto no
+sobrescriba la conversación activa del usuario. Usa el `tabId` devuelto si la UI
+necesita correlacionar el estado de seguimiento o enlazar profundamente con la ejecución más adelante.
+
+Existen algunas opciones más de `AgentChatMessage` además de las cubiertas en [Chat del Agent](/docs/client-agent-chat#agentchatmessage), sobre todo para casos embebidos o de integración downstream:
+
+| Opción                | Tipo        | Descripción                                                                       |
+| --------------------- | ----------- | --------------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | Con `newTab`, ejecuta sin enfocar la pestaña y muestra la ejecución en `RunsTray` |
+| `projectSlug`         | `string?`   | Slug de proyecto opcional para contexto estructurado                              |
+| `preset`              | `string?`   | Nombre de preset opcional para consumidores downstream                            |
+| `referenceImagePaths` | `string[]?` | Rutas opcionales de imágenes de referencia                                        |
+
+## Puente de host de aplicaciones MCP {#mcp-app-host-bridge}
+
+Las rutas embebidas como aplicaciones MCP deben ser URL-first: cargar el artefacto actual desde
+parámetros de ruta/consulta, renderizar la ruta React real o un componente compartido enfocado,
+y usar el puente de host solo para comportamiento propiedad del host. `@agent-native/core/client`
+exporta los helpers que llaman las rutas embebidas:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` lee la última instantánea de contexto de host enviada.
+`useMcpAppHostContext()` suscribe componentes de React a los cambios. Los helpers de solicitud
+(`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) devuelven `false` fuera de un marco de aplicación MCP embebido, o
+`Promise<boolean>` dentro de un marco.
+
+`sendToAgentChat()` (consulta [Chat del Agent](/docs/client-agent-chat#sendtoagentchat)) usa el mismo puente para prompts autoenviados desde rutas embebidas. Dentro de una inserción de aplicación MCP creada con `embedApp()`, los mensajes autoenviados (`submit` omitido o `true`) se reenvían al puente, que le pide al host contenedor que agregue contexto oculto y envíe el turno visible del usuario. `context` permanece visible para el modelo sin publicarse como chat de cara al usuario. `submit: false` conserva el comportamiento local de precompletar/revisar porque las aplicaciones MCP no definen una API estándar de borrador previo. Internamente esta es la ruta de chat enviado, a veces expuesta como `agentNative.submitChat`. El código de la app debería seguir llamando a `sendToAgentChat()` en lugar de publicar ese evento directamente.
+
+El puente en sí, los mensajes JSON-RPC `ui/*`, el relé wrapper
+`agentNative.mcpHost.*`, el trasplante frente al renderizado de marco controlado, el contexto de host, y
+las solicitudes de modo de visualización, son propiedad de
+[Agentes externos](/docs/external-agents#mcp-app-bridge). Consulta [Aplicaciones MCP](/docs/mcp-apps) para el protocolo completo.
+
+## Chips de sugerencias personalizadas {#custom-suggestions}
+
+`dynamicSuggestions` de `<AgentSidebar>` (consulta [Chat del Agent](/docs/client-agent-chat#dynamic-suggestions)) ya combina las `suggestions` estáticas con la propia heurística consciente del contexto del framework. Pasa `getSuggestions` en su lugar cuando una app quiera chips deterministas y específicos de dominio calculados a partir del mismo contexto de `application_state` en lugar de la heurística predeterminada del framework.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` recibe la misma instantánea de `navigation`/`selection`/`pending-selection-context` que lee la heurística incorporada, así que una implementación personalizada puede reaccionar exactamente al mismo estado que la predeterminada, solo que con reglas específicas de la app en lugar de genéricas.
+
+## ¿Qué sigue?
+
+- [**Resumen**](/docs/client-overview) — la disposición de directorios `app/` y `public/` en la que viven estos primitivos
+- [**Datos y sincronización**](/docs/client-data) — los hooks de acciones predeterminados y `useDbSync` que debería usar la mayoría de las páginas en su lugar
+- [**Sincronización interna**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` y las dos rutas de latencia que puede tomar una recuperación
+- [**Chat del Agent**](/docs/client-agent-chat) — los helpers predeterminados `sendToAgentChat`/`askUserQuestion` que debería usar la mayoría de la UI en su lugar, y las API de estado de contexto de chat del agente preparado
+- [**Puntos de entrada**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` y personalización de streaming de SSR
+- [**Conciencia del contexto**](/docs/context-awareness) — la semántica de `navigation`/`selection` construida sobre `application_state`, y el recorrido de `TAB_ID`/prevención de fluctuaciones
+- [**Interfaz generativa**](/docs/generative-ui) — controles de chat en línea más ricos más allá de `askUserQuestion`
+- [**Agentes externos**](/docs/external-agents#mcp-app-bridge) — los detalles completos del puente de host de aplicaciones MCP
+  </content>
diff --git a/packages/core/docs/content/locales/es-ES/client-agent-chat.mdx b/packages/core/docs/content/locales/es-ES/client-agent-chat.mdx
new file mode 100644
index 0000000000..96e8a59100
--- /dev/null
+++ b/packages/core/docs/content/locales/es-ES/client-agent-chat.mdx
@@ -0,0 +1,317 @@
+---
+title: "Chat del Agent"
+description: "Puntos de entrada del cliente al chat del agente: sendToAgentChat, openAgentSettings, askUserQuestion, sugerencias dinámicas, useAgentChatGenerating y el estado de contexto de chat del agente preparado."
+---
+
+# Chat del Agent
+
+El cliente de tu aplicación puede hablar con el agente a través de un pequeño conjunto de helpers de cliente. Estos cubren enviar un prompt, preparar contexto oculto, hacerle una pregunta bloqueante al usuario y abrir el panel del agente.
+
+En el ejemplo siguiente, un botón **Draft response** le pide al agente que le haga una pregunta al usuario. Una vez que el usuario responde, el agente se pone a redactar una respuesta teniendo en cuenta el contexto actual de la página y la respuesta del usuario.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="Captura de pantalla de la app Dispatch mostrando la barra lateral de historial de ejecuciones"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="La barra lateral de historial de ejecuciones de Dispatch."
+/>
+
+## Cómo funciona
+
+Al usar los métodos helper de cliente que ofrece Agent-Native, tu UI puede pedirle al agente que interactúe con el usuario de varias formas. El siguiente diagrama muestra cómo un botón "Draft response" puede ser pulsado por el usuario, lo que hace que el agente interactúe con el usuario antes de generar una respuesta.
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="Diagrama de secuencia 'quién es responsable de cada paso' con tres líneas de vida: App Code, UI y Agent. Al hacer clic en 'draft response' se dispara askUserQuestion() (se renderiza en línea en el panel del agente). Tras la respuesta, sendDraftRequest() llama a draft-ticket-reply y devuelve una respuesta al compositor de la UI."
+  align="full"
+  width={600}
+  caption="Diagrama de secuencia que visualiza el flujo del botón 'Draft response'."
+/>
+
+La experiencia del usuario es la siguiente:
+
+1. El usuario hace clic en el botón **Draft response**, lo que hace que se llame a la función `askUserQuestion()`. La pregunta se responde en línea en el panel del agente.
+
+1. El usuario elige **Offer a refund**, lo que hace que `sendDraftRequest()` envíe el prompt y el contexto del ticket al agente.
+
+1. El agente llama a la [acción](/docs/actions) `draft-ticket-reply`, y la respuesta redactada aparece en el compositor de respuestas.
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "La pregunta, sus opciones, y cómo debe comportarse.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "La pregunta completa. Clara, específica, termina con un signo de interrogación.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'Chip/encabezado muy corto, de unos 12 caracteres, p. ej. `"Response"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2 a 4 opciones distintas. Cada una es `{ label, value?, description?, preview?, recommended? }`. `value` toma como valor predeterminado `label`.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            'Agrega una opción de texto libre "Other" en la que el representante puede escribir.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Selección múltiple en lugar de selección única.",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description:
+            "Clave de estado de la aplicación que sondea el panel del agente.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'El `value` elegido (o `value[]` cuando `allowMultiple`), el texto escrito por el representante en "Other", o `null` si lo omite. Permanece pendiente hasta que responda. Requiere que el panel del agente esté montado, lo cual ocurre en cada plantilla.',
+  }}
+/>
+
+Esta función le hace al usuario una pregunta de opción múltiple desde el código de la app, la renderiza en línea en el panel del agente y espera su respuesta. Úsala cuando la UI necesite una pequeña decisión con dos a cuatro opciones antes de iniciar trabajo del agente, en lugar de construir un modal personalizado.
+
+En el ejemplo siguiente, un botón "Draft Response" en la página de un ticket le pregunta al representante cómo quiere responder antes de enviar nada al agente:
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "Una tupla `[isGenerating, send]`. `isGenerating` es `true` desde el momento en que se llama a `send()` hasta que la ejecución del chat del agente reporta que se ha detenido. `send(opts)` tiene la misma firma que `sendToAgentChat()`, y devuelve el id de pestaña al que se despachó.",
+  }}
+/>
+
+Este hook de React envuelve `sendToAgentChat()` con seguimiento de estado de carga.
+
+1. El primer argumento, `isGenerating`, se vuelve verdadero cuando lo llamas, y luego vuelve a falso cuando el agente termina de generar.
+
+2. El segundo argumento, `send()`, refleja la función `sendToAgentChat()`.
+
+`isGenerating` solo se restablece una vez que una ejecución realmente comienza y reporta que se ha detenido. Una llamada con `submit: false` precompleta un borrador sin iniciar una ejecución, así que `isGenerating` se queda en `true` para siempre después de una de esas. Usa este hook solo para envíos con `submit: true`; llama a `sendToAgentChat()` directamente para los que solo precompletan.
+
+Combinar esto con el ejemplo de `askUserQuestion()` de arriba completa el manejador del botón:
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="Completando el manejador de Draft Response"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "Estado de carga + envío, juntos",
+      note: "`useAgentChatGenerating()` devuelve la misma forma de tupla que una llamada directa a `sendToAgentChat()`, pero agrega `isDrafting` para que el botón pueda desactivarse mientras la solicitud está en curso.",
+    },
+    {
+      lines: "10-17",
+      label: "Reutiliza el paso de la pregunta",
+      note: "Esta es exactamente la llamada a `askUserQuestion()` de la sección anterior, ahora dentro del propio manejador del botón.",
+    },
+    {
+      lines: "18",
+      label: "Reduce el tipo antes de usar la respuesta",
+      note: "El tipo de retorno siempre admite `string[]` por `allowMultiple`, así que esta comprobación es necesaria aunque esta llamada nunca lo active.",
+    },
+    {
+      lines: "20-25",
+      label: "Convierte la elección en una frase",
+      note: "Traduce el valor seleccionado, o el texto propio escrito por el representante, en la frase que el prompt de abajo lee de forma natural.",
+    },
+    {
+      lines: "27-32",
+      label: "Nombra la acción y la intención",
+      note: "El mensaje le dice al agente exactamente qué acción llamar (`draft-ticket-reply`) y le recuerda que no debe enviar la respuesta directamente. `openSidebar: true` asegura que la respuesta redactada sea visible aunque la barra lateral estuviera cerrada.",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting impulsa el botón",
+      note: "Se desactiva y se reetiqueta solo mientras `sendDraftRequest()` está en curso. El botón permanece pulsable mientras `askUserQuestion()` espera al representante, ya que eso ocurre antes de que `sendDraftRequest()` se llame siquiera.",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Envía un mensaje al chat del agente a través de `postMessage`. Este es el primitivo de nivel más bajo que envuelve `useAgentChatGenerating()` arriba, útil cuando una interacción de UI no necesita su propio seguimiento de estado de carga. Pasa `context` para detalle adicional que el mensaje por sí solo no transmite. Se agrega al mismo mensaje visible, envuelto en etiquetas `<context>`. No se oculta al usuario. Pasa `submit: true` para enviar de inmediato, o `submit: false` para precompletar un borrador que el usuario revisa primero.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| Opción        | Tipo       | Descripción                                                                                               |
+| ------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | El prompt enviado al chat. `context`, si se establece, se agrega a este mismo mensaje visible             |
+| `context`     | `string?`  | Detalle adicional agregado al mensaje visible, envuelto en etiquetas `<context>`. No se oculta al usuario |
+| `submit`      | `boolean?` | true = envío automático, false = solo precompletar                                                        |
+| `newTab`      | `boolean?` | Crea un hilo de chat independiente para este prompt                                                       |
+| `openSidebar` | `boolean?` | Establece falso para enviar/precompletar sin abrir la barra lateral                                       |
+
+Ejecutar esto desde dentro de una inserción de aplicación MCP, o poner la ejecución en segundo plano sin abrir la barra lateral, se cubren ambos en [Avanzado](/docs/client-advanced#background-send).
+
+## Sugerencias dinámicas {#dynamic-suggestions}
+
+Antes de que empiece una conversación, `<AgentSidebar>`, `<AgentPanel>` y `<AssistantChat>` muestran chips de prompt en el chat vacío. De forma predeterminada esos no son solo tu lista fija de `suggestions`: el framework lee `navigation`, `selection`, `pending-selection-context` y la URL actual del estado de la aplicación, y combina chips que coinciden con lo que realmente hay en pantalla.
+
+Lo hace con dos comprobaciones. Si hay algo seleccionado, agrega chips genéricos como "Summarize this selection". Por separado, examina `navigation` en busca de nombres de campo comunes que ya usan las apps existentes, como `threadId`/`emailId` para un hilo de correo o `dashboardId`/`chartId` para un gráfico, y agrega chips adaptados a ese tipo de pantalla, como "Draft a reply" para un hilo o "Find anomalies in this data" para un gráfico. Lo que se le ocurra se combina con tus `suggestions` estáticas, se deduplica y se limita a `max`.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+Si la pantalla actual no coincide con nada que reconozca la heurística y no hay nada seleccionado, no aporta chips, y el chat vacío recurre solo a tus `suggestions` estáticas. Establece `dynamicSuggestions={false}` para conservar solo chips estáticos. Si la forma de navegación de tu app no coincide con la heurística incorporada, o quieres chips totalmente deterministas y específicos de la app, consulta [Avanzado](/docs/client-advanced#custom-suggestions).
+
+## openAgentSettings(section?) {#openagentsettings}
+
+Usa `openAgentSettings()` cuando una página de configuración de la app o una tarjeta de configuración deba
+abrir la pestaña Settings de la barra lateral del agente. Pasa un id de sección como `"llm"`, `"secrets"`,
+`"automations"`, `"voice"` o `"limits"` para abrir una sección específica.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Prefiere este helper en lugar de despachar `agent-panel:open-settings` directamente.
+
+## Estado de contexto de chat del agente {#agent-chat-context-state}
+
+Las API de estado de contexto son conexiones opcionales para UI que necesita sincronización bidireccional con
+chips de contexto preparados: renderizar los elementos preparados actuales fuera del compositor, reflejar si un elemento ya está adjunto, o proporcionar controles explícitos de eliminar/borrar.
+
+No recurras a estos helpers para flujos simples de "enviar esto al agente" o "precompletar este borrador para revisión". Usa [`sendToAgentChat()`](#sendtoagentchat) con `context` y `submit` para esos casos.
+
+| API                               | Usar cuando                                                                              |
+| --------------------------------- | ---------------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | Un componente de React necesita la lista de contexto preparada en vivo                   |
+| `setAgentChatContextItem(item)`   | El código imperativo debe preparar o reemplazar un elemento de contexto con clave        |
+| `listAgentChatContext()`          | El código no-React necesita una instantánea puntual del contexto preparado               |
+| `removeAgentChatContextItem(key)` | La UI debe eliminar un elemento de contexto preparado por su `key` estable               |
+| `clearAgentChatContext()`         | La UI debe borrar todo el contexto preparado, como después de reiniciar una vista o modo |
+| `refreshAgentChatContext()`       | El código imperativo debe volver a leer la última instantánea de contexto persistida     |
+
+`useAgentChatContext()` devuelve `{ items, set, remove, clear, refresh }`.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` es para código imperativo que solo necesita inspeccionar los elementos preparados actuales una sola vez. `clearAgentChatContext()` es intencionalmente amplia. Usa `removeAgentChatContextItem(key)` cuando solo cambió una selección.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| Opción        | Tipo       | Descripción                                                                       |
+| ------------- | ---------- | --------------------------------------------------------------------------------- |
+| `key`         | `string`   | Identificador estable usado para reemplazar un elemento existente                 |
+| `title`       | `string`   | Etiqueta corta mostrada en el chip del compositor                                 |
+| `context`     | `string`   | Contexto oculto incluido con el próximo prompt enviado                            |
+| `openSidebar` | `boolean?` | El valor predeterminado es true. Pasa false para preparar el contexto en silencio |
+
+## ¿Qué sigue?
+
+- [**Resumen**](/docs/client-overview) — dónde encajan estos helpers dentro de `app/`
+- [**Datos y sincronización**](/docs/client-data) — los hooks de acciones y `useDbSync` que mantienen actualizada a la propia UI
+- [**Agente sin cita previa**](/docs/drop-in-agent) — montar `<AgentSidebar>`/`<AgentPanel>` para que estos helpers tengan dónde renderizarse
+- [**Avanzado**](/docs/client-advanced) — envíos en segundo plano, chips de sugerencias personalizadas y el puente de host de aplicaciones MCP
+- [**Interfaz generativa**](/docs/generative-ui) — construir controles de chat en línea más ricos más allá de `askUserQuestion`
+  </content>
diff --git a/packages/core/docs/content/locales/es-ES/client-data.mdx b/packages/core/docs/content/locales/es-ES/client-data.mdx
new file mode 100644
index 0000000000..0eeba6130d
--- /dev/null
+++ b/packages/core/docs/content/locales/es-ES/client-data.mdx
@@ -0,0 +1,436 @@
+---
+title: "Datos y sincronización"
+description: "Los hooks de acciones que usa app/ para leer, escribir y mantenerse sincronizado en vivo con las mismas acciones que llama el agente."
+---
+
+# Datos y sincronización
+
+La forma principal de leer y escribir datos de la app desde el cliente es a través de los hooks de [acciones](/docs/actions). Al incorporar las solicitudes en acciones, tanto tu cliente como el agente pueden interactuar con tu aplicación de la misma manera.
+
+En el ejemplo siguiente, un ticket se asigna al usuario actual manualmente a través de un desplegable, y luego a través del agente de chat. Tanto la UI como el agente acceden a la misma acción.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="Ejemplo de una acción de UI y una acción del agente con el mismo resultado."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Ejemplo de una acción de UI y una acción del agente con el mismo resultado."
+/>
+
+## Obtener y mutar datos {#fetching-mutating}
+
+Una app típica construye su propia capa de API y la llama con solicitudes `fetch` escritas a mano. Una app nativa del agente se salta esa capa: `app/` llama a las mismas acciones que el agente ya tiene como herramientas, a través de los hooks siguientes.
+
+<Diagram id="doc-block-client-data-fm-1" title="Fetch típico frente a un hook de acción" summary="Un componente típico llama a una ruta a la que solo él puede acceder. Un componente nativo del agente llama a una acción que el agente también puede llamar.">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Típico</div>
+    <div class="diagram-node">Componente</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Tu ruta de API</strong>
+      <small class="diagram-muted">solo el frontend puede llamarla</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Base de datos</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Componente</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">acción get-lead</span>
+      <small class="diagram-muted">también es una herramienta del agente</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Base de datos SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Hooks de acciones {#action-hooks}
+
+Hay dos hooks de acciones que probablemente usarás más: `useActionQuery()` y `useActionMutation()`. Estos dos hooks dan acceso a las acciones de tu app.
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "El nombre registrado de la acción.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "La entrada de la acción, tipada a partir de su esquema `defineAction()`.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "Todo lo de [las opciones de useQuery](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) salvo `queryKey` y `queryFn`, que el hook establece por sí mismo.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      'Almacenado en caché bajo `["action", name, params]`. Se vuelve a obtener automáticamente cada vez que se completa una acción mutante, sin necesidad de invalidación manual.',
+  }}
+/>
+
+Este hook está pensado para usarse con acciones de solo lectura. Es un envoltorio ligero alrededor de la función [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).
+
+En el ejemplo siguiente, se llama a la acción `list-tickets`. Esto es similar a hacer una solicitud GET para todos los tickets.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+El siguiente ejemplo muestra una solicitud para obtener un único ticket, a través de la acción `get-ticket`. Se pasa un `ticketId` para limitar la consulta a un ticket específico. La opción adicional `enabled` se proporciona para asegurar que la consulta no se ejecute automáticamente, y en su lugar solo se ejecute cuando haya un `ticketId` presente.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "El nombre registrado de la acción.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "Todo lo de [las opciones de useMutation](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) salvo `mutationFn`, que el hook establece por sí mismo.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Sobrescribe el método de solicitud predeterminado.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Excluye la actualización automática de la caché al tener éxito.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'Al tener éxito, emite un evento de cambio con `source: "action"`, para que cada `useActionQuery()` que lea los datos afectados se vuelva a obtener automáticamente. No se necesita invalidación manual.',
+  }}
+/>
+
+Este hook está pensado para usarse con acciones que cambian datos, como crear, actualizar o enviar algo. Es un envoltorio ligero alrededor de la función [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation).
+
+A diferencia de `useActionQuery()`, la entrada de la acción no se pasa al propio hook. Se pasa a `mutate()` o `mutateAsync()` cuando estás listo para ejecutar la mutación.
+
+En el ejemplo siguiente, se llama a la acción `send-ticket-reply` para publicar una respuesta a un ticket. Llama a `mutate()` desde un manejador de eventos, como el `onClick` de un botón.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+El siguiente ejemplo muestra la misma mutación con una opción `onSuccess`. La invalidación de la caché ocurre automáticamente después de cada mutación, así que `onSuccess` solo se necesita para efectos secundarios locales, como limpiar el compositor de respuesta una vez enviada.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "El nombre registrado de la acción.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "La entrada de la acción, tipada a partir de su esquema `defineAction()`.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "Todo lo siguiente es opcional.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Sobrescribe el método de solicitud predeterminado.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "Cancela la solicitud.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Sobrescribe el tiempo de espera predeterminado de 60 segundos, para acciones que legítimamente tardan más.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "A diferencia de los hooks anteriores, no hay caché ni recuperación automática. Combínalo con una invalidación manual si otra UI depende del resultado.",
+  }}
+/>
+
+Esta función es para llamadas imperativas puntuales a acciones fuera de un flujo de renderizado de React, como un manejador de eventos simple, un script, o cualquier otra ruta de código que no sea React. Devuelve una promesa directamente en lugar de un resultado de hook.
+
+En el ejemplo siguiente, se llama a la acción `update-ticket` desde un manejador de atajo de teclado fuera del flujo de renderizado de React, asignando el ticket a un representante.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+El siguiente ejemplo muestra la misma llamada con una opción `timeoutMs`, útil para acciones que legítimamente tardan más que el tiempo de espera predeterminado de 60 segundos.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+Cada solicitud de `useActionQuery()`, `useActionMutation()` y `callAction()` está acotada por un tiempo de espera de 60 segundos, y los tiempos de espera se muestran como errores en lugar de reintentarse silenciosamente. `useActionQuery()` también cancela automáticamente las solicitudes reemplazadas, usando la señal de aborto de React Query.
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "Todos los campos son opcionales.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "Cliente de React Query usado para invalidar la caché.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "URL del endpoint de sondeo.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "URL del endpoint SSE. Pasa `false` para usar solo sondeo.",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "Intervalo de sondeo en ms.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Intervalo de sondeo mientras SSE está conectado, como respaldo por si se pierde un evento. Una pestaña desconectada sondea con la `interval` más rápida (o una cadencia fija en inactividad) en su lugar.",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Pausa el sondeo cuando la pestaña del navegador está oculta. Las pestañas ocultas mantienen SSE conectado y sondean como máximo cada 10s mientras están activas, 60s una vez inactivas.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "Fuente de solicitud por pestaña que se debe ignorar, para que una pestaña no se recupere de sus propias escrituras.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "Callback opcional cuando SSE o el sondeo reciben un evento de cambio.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "Filtra la invalidación amplia que dispara un evento de acción. Rara vez se necesita. Úsalo para mantener una consulta activa costosa en semántica de refresco explícito mientras las consultas normales con versión de fuente siguen reaccionando a través de `useChangeVersion`.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "Nombres de acciones cuyos eventos de sincronización no deben invalidar todas las consultas de acción. Solo para acciones de alto volumen en segundo plano que ya realizan su propia invalidación específica.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description:
+            "Obsoleto e ignorado. Se conserva para sitios de llamada antiguos.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+Este hook está pensado para mantener la UI sincronizada con cambios en la base de datos que ocurren fuera de tus propias acciones, como una escritura del agente, un webhook o un cambio hecho desde otra pestaña del navegador. Escucha cambios a través de eventos enviados por el servidor, y recurre al sondeo cuando los eventos enviados por el servidor no están disponibles.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+Para operaciones CRUD normales, prefiere `useActionQuery()` y `useActionMutation()`. Las acciones mutantes emiten `source: "action"`, así que esos hooks se recuperan de inmediato. Los cambios provenientes del agente, un webhook u otra pestaña llegan a través de `useDbSync()` en su lugar, por SSE o el respaldo de sondeo. Si una llamada `useQuery()` sin procesar necesita sincronizarse con una clave personalizada, consulta [Sincronización interna](/docs/client-sync-internals). Si necesitas escribir directamente en `application_state`, consulta [Avanzado](/docs/client-advanced).
+
+## ¿Qué sigue?
+
+- [**Resumen**](/docs/client-overview) — la disposición de directorios `app/` y `public/` en la que viven los hooks de esta página
+- [**Chat del Agent**](/docs/client-agent-chat) — enviar prompts y preparar contexto para el agente
+- [**Actions**](/docs/actions) — la superficie `defineAction` detrás de cada hook de esta página
+- [**Avanzado**](/docs/client-advanced) — acceso directo a `application_state`
+- [**Sincronización interna**](/docs/client-sync-internals) — sincronizar un `useQuery` sin procesar con `useChangeVersion`
+- [**Sincronización en vivo**](/docs/key-concepts#polling-sync) — cómo `useDbSync` mantiene la UI actualizada
+  </content>
diff --git a/packages/core/docs/content/locales/es-ES/client-entry-points.mdx b/packages/core/docs/content/locales/es-ES/client-entry-points.mdx
new file mode 100644
index 0000000000..b406a7dd1a
--- /dev/null
+++ b/packages/core/docs/content/locales/es-ES/client-entry-points.mdx
@@ -0,0 +1,28 @@
+---
+title: "Puntos de entrada"
+description: "app/entry.client.tsx y app/entry.server.tsx: los wrappers ligeros de arranque de hidratación y SSR, y cuándo personalizar el comportamiento de streaming."
+---
+
+# Puntos de entrada
+
+`app/entry.client.tsx` hidrata en el navegador el HTML renderizado en el servidor, y `app/entry.server.tsx` renderiza ese HTML en el servidor. Ambos son wrappers ligeros generados por React Router. Rara vez necesitas editarlos.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+Recurre a estos solo para personalización avanzada de SSR, por ejemplo cambiar el comportamiento de streaming. Las páginas, el layout y los datos ordinarios no necesitan cambios aquí. Consulta [Enrutamiento](/docs/client-routing) para agregar páginas en su lugar.
+
+## ¿Qué sigue?
+
+- [**Resumen**](/docs/client-overview) — dónde se ubican estos archivos dentro de `app/`
+- [**Enrutamiento**](/docs/client-routing) — agregar páginas, la forma normal de extender `app/`
+- [**Avanzado**](/docs/client-advanced) — los otros primitivos de cliente de bajo nivel y vías de escape
+  </content>
diff --git a/packages/core/docs/content/locales/es-ES/client-overview.mdx b/packages/core/docs/content/locales/es-ES/client-overview.mdx
new file mode 100644
index 0000000000..6df10c8264
--- /dev/null
+++ b/packages/core/docs/content/locales/es-ES/client-overview.mdx
@@ -0,0 +1,206 @@
+---
+title: "Resumen"
+description: "Los directorios app/ y public/: dónde se construye la visualización de una aplicación nativa del agente, y las API del navegador que usa para mantenerse sincronizada con el agente."
+---
+
+# Resumen
+
+`app/` es donde se construye la visualización real de una aplicación nativa del agente: páginas, layout, componentes, estilos. `public/` contiene los activos estáticos que se sirven junto a ella (iconos, manifest, marcas de marca). Esta es una aplicación típica de React Router v8, no una superficie especial solo para el agente, y es donde se invierte la mayor parte del tiempo de desarrollo.
+
+La única diferencia arquitectónica respecto a un frontend típico: esta capa no tiene su propio backend-for-frontend. Lee y escribe datos a través de las mismas acciones que llama el agente, así que cualquier cosa que se conecte aquí es automáticamente algo que el agente también puede hacer.
+
+<Diagram id="doc-block-client-overview-1" title="Frontend tradicional frente a Agent Native" summary="Un frontend tradicional llama a su propia capa de API, a la que solo él puede acceder. En Agent Native, app/ y el agente llaman ambos a las mismas acciones, por lo que toda capacidad creada aquí queda disponible para el agente sin coste adicional.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Tradicional</div>
+    <div class="diagram-node">app/ (frontend de React)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Capa de API</strong>
+      <small class="diagram-muted">solo el frontend la llama</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Base de datos</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (frontend de React)</div>
+      <div class="diagram-node">Agente</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Acciones</span
+      ><small class="diagram-muted">socios iguales, mismas operaciones</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Base de datos SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Dónde encaja el cliente {#role}
+
+Las solicitudes del navegador, el bucle del agente y los clientes de API externos resuelven todos hacia las mismas acciones y la misma base de datos SQL: no existe un "backend de la app" aparte al que hable esta capa y que el agente no pueda alcanzar también. Construir una funcionalidad aquí significa construir una UI sobre una operación que el agente ya tiene, o definir una acción nueva y obtener una UI para ella al mismo tiempo. Consulta [Actions](/docs/actions) para el lado de la operación de ese contrato.
+
+Esta página cubre los directorios en los que trabajas y las piezas del runtime del navegador que no documenta ningún otro lugar (`root.tsx`, `public/`). Los hooks de React que conectan tus componentes con las acciones y con el agente viven en sus propias páginas dedicadas:
+
+| Página                                                    | Qué cubre                                                                                                                                          |
+| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **[Datos y sincronización](/docs/client-data)**           | `useActionQuery`, `useActionMutation`, `callAction` y `useDbSync`                                                                                  |
+| **[Chat del Agent](/docs/client-agent-chat)**             | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, sugerencias dinámicas y el estado de contexto de chat del agente preparado              |
+| **[Avanzado](/docs/client-advanced)**                     | Acceso directo a `application_state`, envíos de chat en segundo plano, chips de sugerencias personalizadas y el puente de host de aplicaciones MCP |
+| **[Sincronización interna](/docs/client-sync-internals)** | `useChangeVersion`/`useChangeVersions` para sincronizar un `useQuery` sin procesar                                                                 |
+| **[Puntos de entrada](/docs/client-entry-points)**        | `app/entry.client.tsx`/`app/entry.server.tsx` y personalización de SSR                                                                             |
+
+## Qué hay en app/ y public/ {#project-directories}
+
+| Ruta                                                | Qué cubre                                                                                                                                           |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | El shell HTML y la pila de providers — consulta [El shell del navegador](#app-shell) más abajo                                                      |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hidratación y arranque de SSR — consulta [Puntos de entrada](/docs/client-entry-points)                                                             |
+| **`app/routes.ts` + `app/routes/`**                 | Páginas basadas en archivos y navegación — consulta [Enrutamiento](/docs/client-routing)                                                            |
+| **`app/components/`**                               | Tu UI: primitivos de estilo shadcn más componentes específicos de la app — consulta [shadcn/ui](/docs/shadcn-ui)                                    |
+| **`app/hooks/`**                                    | Hooks de datos, sincronización y chat del agente — consulta [Datos y sincronización](/docs/client-data) y [Chat del Agent](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | Utilidades compartidas del cliente (configuración de la app, id de pestaña, `cn`) — consulta [Utilidades](#utilities) más abajo                     |
+| **`app/design-system.ts`**                          | Adaptador opcional de sistema de diseño personalizado — consulta [Sistemas de diseño personalizados](/docs/custom-design-system)                    |
+| **`app/i18n/`**                                     | Catálogos de textos de UI localizados — consulta [Internacionalización](/docs/internationalization)                                                 |
+| **`app/global.css`**                                | Estilos base y el punto de entrada de Tailwind                                                                                                      |
+| **`public/`**                                       | Activos estáticos servidos tal cual — consulta [Activos estáticos](#public-directory) más abajo                                                     |
+
+## El shell del navegador: root.tsx y AppProviders {#app-shell}
+
+`app/root.tsx` es la parte superior del árbol de React: el shell del documento HTML (`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`) más la pila de providers dentro de la cual se renderiza cada ruta.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` es el único wrapper que conecta:
+
+- El cliente de React Query usado por `useActionQuery`/`useActionMutation` (consulta [Datos y sincronización](/docs/client-data#fetching-mutating)).
+- El catálogo de i18n pasado como `i18n.catalog` (consulta [Internacionalización](/docs/internationalization)).
+- Comprobaciones de sesión del lado del cliente: en una ruta privada, un visitante anónimo es redirigido a iniciar sesión antes de que se monte cualquier UI privada. Pasa `isPublicPath` para rutas públicas/SEO, o `sessionBypass` para una superficie que se autentica de otra forma, como un token de inserción MCP. Consulta [Autenticación](/docs/authentication).
+
+La mayoría de las apps también montan aquí `<AgentSidebar>` o `<AgentPanel>` para que cada ruta obtenga el panel del agente sin esfuerzo adicional. Consulta [Agente sin cita previa](/docs/drop-in-agent#sidebar).
+
+## Activos estáticos: public/ {#public-directory}
+
+Todo lo que hay en `public/` se sirve tal cual desde la raíz del sitio, sin procesar por el build. Cada plantilla incluye:
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+`manifest.json` controla qué aparece si un visitante instala la app en la pantalla de inicio o el dock: nombre, nombre corto, color de tema/fondo y el conjunto de iconos:
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+Rebrandea una app reemplazando estos archivos y actualizando `manifest.json` y las etiquetas `<link rel="icon">`/`<link rel="apple-touch-icon">` en `root.tsx` que los referencian; no hay un paso de registro aparte. Para importar un sistema de marca completo (colores, fuentes, favicon) desde un sitio existente en lugar de editar estos archivos a mano, consulta [Sistemas de marca y Figma](/docs/template-design-brand-and-figma).
+
+## Utilidades: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` combina nombres de clase (clsx + tailwind-merge) y es la forma estándar de componer clases condicionales de Tailwind en `app/components/`.
+
+## ¿Qué sigue?
+
+- [**Datos y sincronización**](/docs/client-data) — hooks de acciones y `useDbSync`
+- [**Chat del Agent**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion` y sugerencias dinámicas
+- [**Avanzado**](/docs/client-advanced) — estado de la aplicación, envíos de chat en segundo plano y el puente de host de aplicaciones MCP
+- [**Sincronización interna**](/docs/client-sync-internals) — `useChangeVersion` para sincronizar un `useQuery` sin procesar
+- [**Enrutamiento**](/docs/client-routing) — páginas basadas en archivos, parámetros dinámicos y navegación
+- [**Actions**](/docs/actions) — la superficie `defineAction` detrás de cada hook de datos
+- [**Sistemas de diseño personalizados**](/docs/custom-design-system) — cómo sustituir tu propia librería de componentes a través de `app/design-system.ts`
+- [**Autenticación**](/docs/authentication) — las comprobaciones de sesión que `AppProviders` ejecuta en rutas privadas
+  </content>
diff --git a/packages/core/docs/content/locales/es-ES/client-routing.mdx b/packages/core/docs/content/locales/es-ES/client-routing.mdx
new file mode 100644
index 0000000000..94d381430b
--- /dev/null
+++ b/packages/core/docs/content/locales/es-ES/client-routing.mdx
@@ -0,0 +1,122 @@
+---
+title: "Enrutamiento"
+description: "Enrutamiento basado en archivos para aplicaciones nativas del agente con React Router v8: páginas, parámetros dinámicos y navegación."
+---
+
+# Enrutamiento
+
+Las aplicaciones nativas del agente usan **React Router v8** con enrutamiento basado en archivos a través de `flatRoutes()` de `@react-router/fs-routes`. Cada archivo en `app/routes/` se convierte en una URL. Las plantillas usan la convención de notación con puntos. Los puntos separan segmentos de URL dentro de un único nombre de archivo.
+
+Esta página cubre las rutas de cliente, las páginas renderizadas en el navegador a partir de `app/routes/`. Las rutas de servidor son un sistema aparte: rutas de archivo de Nitro bajo `server/routes/`, más los propios endpoints `/_agent-native/*` del framework. Esas viven en la página [Rutas](/docs/server-routes). Los dos no comparten directorio, convención de nombres, ni router, así que un archivo de `server/routes/` nunca se convierte en una página aquí y un archivo de `app/routes/` nunca se convierte en un endpoint de servidor.
+
+<Diagram id="doc-block-client-routing-1" title="Nombre de archivo → URL" summary="Cada archivo en app/routes/ se convierte en una URL. Los puntos se convierten en barras, y un segmento $ se convierte en un parámetro dinámico.">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Enrutamiento basado en archivos {#file-based-routing}
+
+### Mapeo de archivo → URL
+
+| Archivo                    | URL                    | Notas                                                                             |
+| -------------------------- | ---------------------- | --------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | Ruta de índice                                                                    |
+| `dashboard.tsx`            | `/dashboard`           | Página simple                                                                     |
+| `extensions.$id.tsx`       | `/extensions/:id`      | Se anida dentro del `<Outlet/>` de `extensions.tsx`. `$` es un parámetro dinámico |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | El `_` final evita la anidación bajo `dashboard.tsx`, así que es su propia página |
+| `_app.tsx`                 | (sin segmento de URL)  | Layout sin ruta. Prefijo con `_`                                                  |
+| `inbox/route.tsx`          | `/inbox`               | Forma de carpeta. `route.tsx` es el índice                                        |
+
+Prefija un segmento con `$` para un parámetro dinámico. Prefija con `_` para que sea una ruta de layout sin ruta (sin segmento de URL), o agrega un `_` final antes del punto para que una ruta que parece anidada no se anide bajo el layout de su padre. Las plantillas usan `flatRoutes()`. El archivo de notación con puntos de arriba es la forma principal. La forma de carpeta anidada `inbox/route.tsx` también funciona.
+
+## Agregar una página nueva {#adding-a-page}
+
+Crea el archivo y exporta un componente predeterminado:
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+Eso es todo. React Router lo detecta automáticamente, no se necesita registro.
+
+## Parámetros dinámicos {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+El `_` final antes del punto evita que esta página se anide dentro del `<Outlet/>` de `dashboard.tsx`, así que se renderiza como su propia página completa en `/dashboard/:ticketId` en lugar de aparecer dentro del layout de la cola de tickets.
+
+## Navegación {#navigation}
+
+Usa `<Link>` para navegación del lado del cliente y `useNavigate()` para navegación programática:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+Ninguno de estos le dice al agente por sí solo qué está mirando el usuario. Eso es una preocupación aparte, gestionada por `useAgentRouteState()` al escribir la ruta actual en el estado de la aplicación. Consulta [Conciencia del contexto](/docs/context-awareness).
+
+## ¿Qué sigue?
+
+- [**Resumen**](/docs/client-overview) — dónde encaja `app/routes/` dentro del resto de `app/` y `public/`
+- [**Datos y sincronización**](/docs/client-data) — leer y escribir datos desde dentro de una ruta
+- [**Chat del Agent**](/docs/client-agent-chat) — enviar prompts y preparar contexto desde una ruta
+- [**Rutas**](/docs/server-routes) — el sistema de enrutamiento de servidor aparte: rutas de archivo bajo `server/routes/` y el espacio de nombres `/_agent-native/` del framework
+- [**Conciencia del contexto**](/docs/context-awareness) — cómo aprende el agente la ruta y selección actuales
+  </content>
diff --git a/packages/core/docs/content/locales/es-ES/client-sync-internals.mdx b/packages/core/docs/content/locales/es-ES/client-sync-internals.mdx
new file mode 100644
index 0000000000..63f8ac4e8b
--- /dev/null
+++ b/packages/core/docs/content/locales/es-ES/client-sync-internals.mdx
@@ -0,0 +1,128 @@
+---
+title: "Sincronización interna"
+description: "El mecanismo de versión de cambio detrás de useDbSync: useChangeVersion/useChangeVersions para sincronizar un useQuery sin procesar, y las dos rutas de latencia que puede tomar una recuperación."
+---
+
+# Sincronización interna
+
+[Sincronización en vivo](/docs/key-concepts#polling-sync) cubre el modelo mental: una escritura del agente se convierte en un evento de cambio, `useDbSync()` lo recoge, y las consultas afectadas se recuperan. Esta página cubre el mecanismo subyacente que la mayoría de las apps nunca tocan directamente: los contadores de versión de cambio que incrementa `useDbSync()`, y cómo incorporarlos en una llamada `useQuery()` sin procesar que no pasa por `useActionQuery()`.
+
+`useActionQuery()` ya se recupera automáticamente cuando se completa una acción mutante (consulta [Datos y sincronización](/docs/client-data#fetching-mutating)). Recurre a `useChangeVersion()`/`useChangeVersions()` solo cuando estés sincronizando una llamada `useQuery()` sin procesar fuera de esa ruta, como un helper de cliente de bajo nivel que lee el estado de una integración.
+
+## Cómo funcionan las versiones de cambio {#how-it-works}
+
+Cuando ocurre una mutación de base de datos del lado del servidor, el servidor registra un evento de cambio etiquetado con una clave `source`. `useDbSync()` recibe ese evento e incrementa un contador local para esa fuente. Incorporar el contador en una clave de consulta de React Query hace que la consulta se recupere automáticamente cada vez que el backend reporta nueva actividad para esa fuente.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description:
+        'La fuente de evento de cambio a observar, p. ej. `"dashboards"`.',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description:
+      "Un contador que se incrementa cada vez que se muta la fuente dada.",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "Varias fuentes de eventos de cambio a observar a la vez.",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "La suma de los contadores de versión de cada fuente dada.",
+  }}
+/>
+
+En el ejemplo siguiente, una llamada `useQuery()` sin procesar lee un dashboard directamente, incorporando el contador de versión de la fuente `"dashboards"` en su clave de consulta para que se recupere cada vez que cambie esa fuente:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` mantiene los datos anteriores en pantalla durante la recuperación, así que la vista no parpadea a un estado de carga.
+
+## Dos rutas hacia una recuperación {#latency-models}
+
+Una mutación llega a la UI de una de dos formas, y tienen latencia distinta.
+
+Una mutación local, una que acaba de hacer tu propia llamada a `useActionMutation()`, emite un evento `source: "action"` en cuanto tiene éxito. Cada consulta que depende de esa acción se recupera de inmediato. No hay retraso de ida y vuelta, ya que la pestaña que hizo la escritura ya sabe de ella.
+
+Una mutación remota, del agente, un webhook, otra pestaña, u otro usuario, tiene que llegar primero a esta pestaña. `useDbSync()` la recoge por SSE casi de inmediato, o por el respaldo de sondeo dentro de unos dos segundos si SSE no está disponible. Solo una vez que llega ese evento, el contador de versión correspondiente se incrementa y la consulta se recupera en segundo plano.
+
+<Diagram id="doc-block-client-sync-internals-3" title="Dos rutas hacia una recuperación" summary="Una mutación local invalida sus propias cachés al instante. Una escritura remota llega a esta pestaña por SSE, o por el tick de sondeo como respaldo.">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">Esta pestaña</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >emite source: "action" al tener éxito &rarr; recuperación local
+        instantánea</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">Agente · webhook · otra pestaña</span
+      ><strong>Escritura remota</strong
+      ><small class="diagram-muted"
+        >push por SSE, o el tick de sondeo de ~2s como respaldo &rarr; el
+        contador de versión se incrementa &rarr; recuperación en segundo
+        plano</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## ¿Qué sigue?
+
+- [**Sincronización en vivo**](/docs/key-concepts#polling-sync) — el modelo mental conceptual bajo el cual está esta página
+- [**Datos y sincronización**](/docs/client-data) — `useActionQuery`/`useDbSync`, que debería usar la mayoría de las páginas en lugar de estos primitivos
+- [**Avanzado**](/docs/client-advanced) — los otros primitivos de cliente de bajo nivel y vías de escape
+  </content>
diff --git a/packages/core/docs/content/locales/es-ES/client.mdx b/packages/core/docs/content/locales/es-ES/client.mdx
deleted file mode 100644
index 4243196be4..0000000000
--- a/packages/core/docs/content/locales/es-ES/client.mdx
+++ /dev/null
@@ -1,470 +0,0 @@
----
-title: "Cliente"
-description: "Utilidades y enlaces React para aplicaciones nativas del agente: sendToAgentChat, estado de contexto de chat del agente opcional, useDbSync, useAgentChatGenerating y cn."
----
-
-# Cliente
-
-`@agent-native/core` proporciona ganchos y utilidades React para el lado del navegador de aplicaciones nativas del agente.
-
-Estos clientes/React API se exportan desde `@agent-native/core` y `@agent-native/core/client`. Importarlos desde `@agent-native/core/client` (la entrada del navegador) para mayor claridad y correcta agrupación, ya que la raíz desnuda de `@agent-native/core` se resuelve en la compilación del Nodo de forma predeterminada.
-
-Para enrutamiento basado en archivos (agregar páginas, parámetros dinámicos y navegación), consulte [Routing](/docs/routing).
-
-## Obtener y mutar datos {#fetching-mutating}
-
-La forma principal de leer y escribir datos de aplicaciones desde el navegador es a través de enlaces de acción. Nunca escriba a mano llamadas `fetch` a rutas `/_agent-native/*`; en su lugar, utilice los ayudantes con nombre (consulte [Actions](/docs/actions)).
-
-<Diagram id="doc-block-1gc0aq4" title="El bucle de datos del navegador" summary={"Los ganchos leen y escriben mediante acciones; useDbSync observa la base de datos para que las escrituras en segundo plano y del agente vuelvan a buscar los mismos cachés automáticamente."}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>base de datos SQL</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(opta) {#sendtoagentchat}
-
-Envíe un mensaje al chat del agente a través de postMessage, la forma común de delegar una tarea de IA desde una interacción UI. Pase `context` para contexto de modelo oculto y `submit: true` para enviar inmediatamente, o `submit: false` para completar previamente un borrador que el usuario revisa primero.
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-Dentro de una aplicación integrada MCP creada con `embedApp()`, mensajes enviados automáticamente
-(`submit` omitido o `true`) se reenvían al puente host de la aplicación MCP, que
-pide al host contenedor que agregue contexto oculto y envíe el turno al usuario visible.
-`context` permanece visible como modelo sin publicarse en el chat de cara al usuario.
-`submit: false` mantiene el comportamiento de precarga/revisión local porque las aplicaciones MCP no lo hacen
-definir un borrador previo estándar API. Internamente esta es la ruta del chat enviado
-a veces aparecía como `agentNative.submitChat`; el código de la aplicación debe llamar
-`sendToAgentChat()` en lugar de publicar ese evento directamente.
-
-### Envíos silenciosos en segundo plano {#background-send}
-
-Utilice `background: true` cuando una acción UI deba iniciar el trabajo real del agente sin
-abrir o enfocar la barra lateral. Esto todavía crea un hilo/ejecución de chat normal,
-utiliza las herramientas/actions/contexto del agente y mantiene el trabajo observable durante
-la bandeja de ejecuciones; no es una llamada de modelo única y sin formato.
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` está diseñado para combinarse con `newTab`, por lo que el trabajo oculto no lo hace
-sobrescribe la conversación activa del usuario. Utilice el `tabId` devuelto si el UI
-necesita correlacionar el estado del seguimiento o establecer un vínculo profundo con la ejecución más adelante.
-
-### Mensaje de chat de agente {#agentchatmessage}
-
-| Opción                | Tipo        | Descripción                                                                        |
-| --------------------- | ----------- | ---------------------------------------------------------------------------------- |
-| `message`             | `string`    | El mensaje visible enviado al chat                                                 |
-| `context`             | `string?`   | Contexto oculto añadido (no se muestra en el chat UI)                              |
-| `submit`              | `boolean?`  | true = envío automático, false = solo precompletar                                 |
-| `newTab`              | `boolean?`  | Crea un hilo de chat independiente para este mensaje                               |
-| `background`          | `boolean?`  | Con `newTab`, ejecutar sin enfocar la pestaña y mostrar la ejecución en `RunsTray` |
-| `openSidebar`         | `boolean?`  | Establezca falso para enviar/rellenar previamente sin abrir la barra lateral       |
-| `projectSlug`         | `string?`   | Slug de proyecto opcional para contexto estructurado                               |
-| `preset`              | `string?`   | Nombre preestablecido opcional para consumidores intermedios                       |
-| `referenceImagePaths` | `string[]?` | Rutas de imágenes de referencia opcionales                                         |
-
-## Estado del contexto del chat del agente (avanzado) {#agent-chat-context-state}
-
-Los API de estado de contexto son conexiones opcionales para UI que necesitan sincronización bidireccional con
-chips de contexto preparados: renderizando los elementos preparados actualmente fuera del compositor,
-reflejar si un elemento ya está adjunto o proporcionar información explícita
-eliminar/borrar controles.
-
-No recurra a estos ayudantes para simplemente "enviar esto al agente" o
-Flujos de "completar previamente este borrador para revisión". Utilice `sendToAgentChat()` con `context`
-y `submit` para esos.
-
-| API                               | Usar cuando                                                                               |
-| --------------------------------- | ----------------------------------------------------------------------------------------- |
-| `useAgentChatContext()`           | Un componente React necesita la lista de contexto preparada en vivo                       |
-| `setAgentChatContextItem(item)`   | El código imperativo debe presentar o reemplazar un elemento de contexto clave            |
-| `listAgentChatContext()`          | El código que no es React necesita una instantánea única del contexto preparado           |
-| `removeAgentChatContextItem(key)` | UI debería eliminar un elemento de contexto preparado por su `key` estable                |
-| `clearAgentChatContext()`         | UI debería borrar todo el contexto preparado, como después de un reinicio de vista o modo |
-| `refreshAgentChatContext()`       | El código imperativo debe volver a leer la última instantánea del contexto persistente    |
-
-`useAgentChatContext()` devuelve `{ items, set, remove, clear, refresh }`.
-
-## openAgentSettings(¿sección?) {#openagentsettings}
-
-Utilice `openAgentSettings()` cuando se abra la página de configuración de una aplicación o una tarjeta de configuración
-la pestaña Configuración de la barra lateral del agente. Pase una identificación de sección como `"llm"`, `"secrets"`,
-`"automations"`, `"voice"` o `"limits"` para abrir una sección específica.
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-Prefiera este ayudante a enviar `agent-panel:open-settings` directamente.
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` es para código imperativo que solo necesita inspeccionar el
-elementos preparados actualmente una vez. `clearAgentChatContext()` es intencionalmente amplio; utilizar
-`removeAgentChatContextItem(key)` cuando solo cambió una selección.
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| Opción        | Tipo       | Descripción                                                                             |
-| ------------- | ---------- | --------------------------------------------------------------------------------------- |
-| `key`         | `string`   | Identificador estable utilizado para reemplazar una pepita existente                    |
-| `title`       | `string`   | Etiqueta corta mostrada en el chip del compositor                                       |
-| `context`     | `string`   | Contexto oculto incluido en el siguiente mensaje enviado                                |
-| `openSidebar` | `boolean?` | El valor predeterminado es verdadero; pasar falso al contexto del escenario en silencio |
-
-## preguntar al usuario (opta) {#ask-user-question}
-
-Haga al usuario una pregunta de opción múltiple desde el código de la aplicación y muéstrela en línea en
-panel de agentes y **espera su respuesta**. Es el gemelo del lado del cliente de
-Herramienta `ask-question` incorporada del agente: escribe un `GuidedQuestionPayload` en
-Clave de estado de aplicación `"guided-questions"` (donde está montada
-`GuidedQuestionFlow` lo representa) y revela el panel del agente, por lo que la pregunta es
-visible. A diferencia de la herramienta del agente, cuya respuesta regresa al agente,
-`askUserQuestion()` **resuelve con la respuesta a la persona que llama**, por lo que el UI puede
-bifurcarse en él.
-
-Úselo cuando el UI necesite exactamente una pequeña decisión (2 a 4 opciones) antes de hacerlo
-inicia el trabajo del agente, en lugar de crear un modal personalizado. Alcanza el
-compositor para detalles de forma libre y un formulario/ventana emergente para entrada de múltiples campos.
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-Cada opción es `{ label, value?, description?, preview?, recommended? }`; `value`
-el valor predeterminado es `label`, y `preview` representa una pequeña maqueta/fragmento de código debajo del
-opción. La promesa se resuelve con el `value` seleccionado (o `value[]` cuando
-`allowMultiple`), la cadena de texto libre cuando el usuario elige "Otro", o `null`
-si se saltan, permanece pendiente hasta que el usuario responda. Requiere el panel de agente
-para montar (está en cada plantilla).
-
-El agente llega al mismo UI a través de su herramienta `ask-question`: prefiere dejar que
-el agente pregunta cuando _it_ llega a una bifurcación genuina que no puede resolver desde el contexto; utilizar
-`askUserQuestion()` cuando el _UI_ necesita activar una acción en una elección.
-
-## Puente de host de aplicaciones MCP {#mcp-app-host-bridge}
-
-Las rutas integradas como aplicaciones MCP deben ser URL primero: cargue el artefacto actual desde
-Parámetros de ruta/consulta, renderice la ruta React real o un componente compartido enfocado,
-y usar el puente de host solo para comportamientos propiedad del host. `@agent-native/core/client`
-exporta la llamada de rutas integradas de ayuda:
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()` lee la última instantánea del contexto del host enviado;
-`useMcpAppHostContext()` suscribe los componentes de React a los cambios. La petición
-ayudantes (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
-`updateMcpAppModelContext`) devuelve `false` fuera de un marco de aplicación MCP integrado, o
-`Promise<boolean>` dentro de un marco. `sendToAgentChat()` usa el mismo puente para
-solicitudes enviadas automáticamente desde rutas integradas.
-
-El puente en sí: los mensajes `ui/*` JSON-RPC, el `agentNative.mcpHost.*`
-retransmisión de contenedor, trasplante versus renderizado de fotograma controlado, contexto de host y
-solicitudes en modo de visualización: son propiedad de
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## Sugerencias dinámicas {#dynamic-suggestions}
-
-`<AgentSidebar>`, `<AgentPanel>` y `<AssistantChat>` combinan `suggestions` estático con sugerencias contextuales de forma predeterminada. El marco lee `navigation`, `selection`, `pending-selection-context` y el URL actual desde el estado de la aplicación mientras se ve un chat vacío y luego ofrece chips de aviso que coinciden con la pantalla actual.
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-Configure `dynamicSuggestions={false}` para mantener solo chips estáticos. Pase `getSuggestions` cuando una aplicación quiera chips deterministas específicos de dominio del mismo contexto de estado de aplicación.
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-Enganche React que incluye sendToAgentChat con seguimiento del estado de carga:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-`isGenerating` se vuelve verdadero cuando llamas a `send()` y se restablece automáticamente a falso cuando el agente termina de generar.
-
-## useDbSync(¿opciones?) {#usedbsync}
-
-Enganche React (anteriormente `useFileWatcher`) que escucha los cambios en la base de datos a través de SSE, recurre al sondeo e invalida los cachés de consultas del marco que mantienen el UI alineado con las escrituras del agente:
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### Opciones {#usedbsync-options}
-
-| Opción             | Tipo               | Descripción                                                                                                       |
-| ------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | Cliente de consulta React para invalidación de caché                                                              |
-| `queryKeys`        | `string[]?`        | Obsoleto e ignorado; conservado para sitios de llamadas antiguos                                                  |
-| `pollUrl`          | `string?`          | Punto final de encuesta URL. Predeterminado: `"/_agent-native/poll"`                                              |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                            |
-| `interval`         | `number?`          | Intervalo de sondeo en ms. Predeterminado: `2000`                                                                 |
-| `fallbackInterval` | `number?`          | Intervalo de sondeo alternativo cuando SSE no está disponible. Predeterminado: `15000`                            |
-| `pauseWhenHidden`  | `boolean?`         | Pausar el sondeo cuando la pestaña del navegador esté oculta. Predeterminado: `true`                              |
-| `ignoreSource`     | `string?`          | Fuente de solicitud por pestaña que se debe ignorar para que una pestaña no se recupere de sus propias escrituras |
-| `onEvent`          | `(data) => void`   | Devolución de llamada opcional cuando SSE/polling recibe un evento de cambio                                      |
-
-Para CRUD normal, prefiera `useActionQuery` y `useActionMutation`; La mutación actions emite `source: "action"` y esos ganchos se recuperan automáticamente.
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-El marco utiliza versiones de cambios para sincronizar los cachés de consultas React con los cambios realizados por agentes en segundo plano, trabajos cron u otros usuarios.
-
-Cuando ocurre cualquier mutación en la base de datos del lado del servidor, el servidor registra un evento de cambio con una clave `source` específica. El oyente `useDbSync` del cliente recibe estos eventos y activa el contador de versión de cambio local para esa fuente. Al incorporar el contador de versiones en sus claves de consulta React, las consultas se recuperan automáticamente cada vez que el backend notifica al cliente sobre una nueva actividad.
-
-- **`useChangeVersion(source: string): number`**: devuelve un contador que se incrementa cada vez que se muta el `source` especificado.
-- **`useChangeVersions(sources: readonly string[]): number`**: devuelve la suma de los contadores de versiones para múltiples fuentes.
-
-### Ejemplo: sincronizar una consulta sin formato con la base de datos
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### Modelos de latencia y comportamiento de invalidación
-
-- **Mutaciones iniciadas por UI:** Cuando ejecuta una acción desde UI usando `useActionMutation`, la mutación activa inmediatamente un evento local con `source: "action"` en caso de éxito. Esto activa una **rebusca instantánea y optimista** de todas las claves de consulta dependiendo de esa acción, evitando retrasos visuales.
-- **Mutaciones en segundo plano o del agente:** Cuando el agente de IA, un webhook o un trabajador en segundo plano muta los datos, la actualización se transmite al cliente. El `useDbSync` del cliente captura esto instantáneamente a través de SSE (Eventos enviados por el servidor) o recurre al **tic de sondeo de 2 segundos**. La versión de la clave de consulta luego cambia, lo que activa una nueva búsqueda en segundo plano.
-
-<Diagram id="doc-block-1lm4ior" title={"Dos caminos para una nueva recuperación"} summary={"Una mutación local invalida sus propios cachés instantáneamente; una escritura remota llega a esta pestaña a través de SSE, o el tick de sondeo como alternativa."}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">Esta pestaña</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">Agente · webhook · otra pestaña</span
-      ><strong>Escritura remota</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...entradas) {#cn}
-
-Utilidad para fusionar nombres de clases (clsx + tailwind-merge):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/es-ES/drop-in-agent.mdx b/packages/core/docs/content/locales/es-ES/drop-in-agent.mdx
index 7223f0e9ca..4e6aa8e39c 100644
--- a/packages/core/docs/content/locales/es-ES/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/es-ES/drop-in-agent.mdx
@@ -225,7 +225,7 @@ seguimiento. Simplemente no roba el foco del estado actual de la barra lateral d
 
 Cuando la misma ruta está integrada como una aplicación MCP, enviada
 Las llamadas `sendToAgentChat()` se reenvían al chat del anfitrión cuando sea compatible; ver
-[Client](/docs/client#sendtoagentchat) para el comportamiento del puente de la aplicación MCP.
+[Chat del Agent](/docs/client-agent-chat#sendtoagentchat) para el comportamiento del puente de la aplicación MCP.
 
 Si desea un estado de carga, utilice el gancho `useSendToAgentChat()`; devuelve tanto `send` como `isGenerating`:
 
diff --git a/packages/core/docs/content/locales/es-ES/notifications.mdx b/packages/core/docs/content/locales/es-ES/notifications.mdx
index 3e36ad8ae6..47cc4d850e 100644
--- a/packages/core/docs/content/locales/es-ES/notifications.mdx
+++ b/packages/core/docs/content/locales/es-ES/notifications.mdx
@@ -363,7 +363,7 @@ Las automatizaciones pueden encadenar esto, p. _"si se activa una notificación
 ## Cómo funciona {#internals}
 
 - **Alcance del propietario**: cada fila tiene una columna `owner`; cada consulta se filtra por él; cada ruta utiliza el correo electrónico de la sesión autenticada. Los usuarios nunca ven las notificaciones de los demás.
-- **Integración de encuesta**: cada mutación llama a `recordChange()`, por lo que las plantillas que utilizan [`useDbSync`](/docs/client) se invalidan automáticamente sin ningún cableado adicional.
+- **Integración de encuesta**: cada mutación llama a `recordChange()`, por lo que las plantillas que utilizan [`useDbSync`](/docs/client-data#usedbsync) se invalidan automáticamente sin ningún cableado adicional.
 - **Distribución con el mejor esfuerzo**: los errores de canal se detectan y registran; un canal que falla no bloquea otros ni la escritura en la bandeja de entrada.
 - **Disparar y olvidar**: `notify()` regresa después de que se completa la escritura en la bandeja de entrada; Los canales personalizados se ejecutan en segundo plano.
 
diff --git a/packages/core/docs/content/locales/es-ES/progress.mdx b/packages/core/docs/content/locales/es-ES/progress.mdx
index 105ed37be5..090069a8f8 100644
--- a/packages/core/docs/content/locales/es-ES/progress.mdx
+++ b/packages/core/docs/content/locales/es-ES/progress.mdx
@@ -233,7 +233,7 @@ Notificar me that run {{runId}} has failed.
 ## Cómo funciona {#internals}
 
 - **Alcance del propietario**: cada fila tiene una columna `owner`; cada consulta se filtra en él. Los usuarios solo ven sus propias ejecuciones.
-- **Integración de encuesta**: cada mutación llama a `recordChange()`, por lo que las plantillas que utilizan [`useDbSync`](/docs/client) se invalidan automáticamente sin ningún cableado adicional.
+- **Integración de encuesta**: cada mutación llama a `recordChange()`, por lo que las plantillas que utilizan [`useDbSync`](/docs/client-data#usedbsync) se invalidan automáticamente sin ningún cableado adicional.
 - **Nombre de la tabla**: el marco también tiene una tabla `agent_runs` para el seguimiento interno del ciclo de vida del turno del chat del agente. La primitiva de progreso usa `progress_runs` para mantener las dos preocupaciones separadas.
 - **Porcentaje de fijación**: los valores se fijan en `[0, 100]` y se redondean a un número entero al escribir.
 
@@ -241,4 +241,4 @@ Notificar me that run {{runId}} has failed.
 
 - [**Notifications**](/docs/notifications): empareja con `manage-progress` (`action=complete`) para informar al usuario cuando finaliza el trabajo
 - [**Automations**](/docs/automations): el mecanismo de vigilancia se ejecuta lentamente a través de `run.progress.updated`
-- [**Client**](/docs/client) — `useDbSync` para invalidación de caché en tiempo real
+- [**Datos y sincronización**](/docs/client-data) — `useDbSync` para invalidación de caché en tiempo real
diff --git a/packages/core/docs/content/locales/es-ES/real-time-collaboration.mdx b/packages/core/docs/content/locales/es-ES/real-time-collaboration.mdx
index afcea63874..7dc26f407f 100644
--- a/packages/core/docs/content/locales/es-ES/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/es-ES/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ modelo de colaboración nativo del agente.
 Editar junto al agente es como trabajar en un editor colaborativo con
 un compañero de trabajo instantáneo e incansable:
 
-Si solo necesita que el UI se actualice cuando el agente u otro usuario escribe en SQL, no necesita nada de esto: use [`useDbSync`](/docs/client). Esta página es para la coedición a nivel de carácter de un único documento de texto enriquecido (cursores compartidos, fusión sin conflictos). Ambos utilizan el mismo canal `/_agent-native/poll`.
+Si solo necesita que el UI se actualice cuando el agente u otro usuario escribe en SQL, no necesita nada de esto: use [`useDbSync`](/docs/client-data#usedbsync). Esta página es para la coedición a nivel de carácter de un único documento de texto enriquecido (cursores compartidos, fusión sin conflictos). Ambos utilizan el mismo canal `/_agent-native/poll`.
 
 Esto se basa en tres tecnologías probadas en batalla: **Yjs** (CRDT para fusión sin conflictos), **TipTap** (editor de texto enriquecido) y **sincronización basada en encuestas** (funciona en todos los entornos de implementación, incluidos los sin servidor y perimetrales).
 
@@ -778,7 +778,7 @@ capas encima del mismo estado de conciencia.
 
 ## Documentos relacionados {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync): el `useDbSync` + `useChangeVersion`
+- [Sincronización interna](/docs/client-sync-internals): el `useDbSync` + `useChangeVersion`
   sistema que ofrece la conciliación del editor de conducción de golpes `updatedAt`.
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   y `assertAccess` para la colaboración con alcance de recurso.
diff --git a/packages/core/docs/content/locales/es-ES/routing.mdx b/packages/core/docs/content/locales/es-ES/routing.mdx
deleted file mode 100644
index 75fa9b3b38..0000000000
--- a/packages/core/docs/content/locales/es-ES/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "Enrutamiento"
-description: "Enrutamiento basado en archivos para aplicaciones nativas del agente con React Router v8: páginas, parámetros dinámicos y navegación."
----
-
-# Enrutamiento
-
-Las aplicaciones nativas del agente utilizan **React Router v8** con enrutamiento basado en archivos a través de `flatRoutes()` desde `@react-router/fs-routes`. Cada archivo en `app/routes/` se convierte en un URL. Las plantillas utilizan la convención de notación de puntos: los puntos separan los segmentos URL dentro de un único nombre de archivo.
-
-## Enrutamiento basado en archivos {#file-based-routing}
-
-### Archivo → Mapeo URL
-
-| Archivo               | URL                | Notas                                           |
-| --------------------- | ------------------ | ----------------------------------------------- |
-| `_index.tsx`          | `/`                | Ruta de índice                                  |
-| `settings.tsx`        | `/settings`        | Página sencilla                                 |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | Punto = `/`, `$` = parámetro dinámico           |
-| `_app.tsx`            | (sin segmento URL) | Diseño sin rutas: prefijo con `_`               |
-| `inbox/route.tsx`     | `/inbox`           | Formulario de carpeta: `route.tsx` es el índice |
-
-Prefije un segmento con `$` para un parámetro dinámico. Prefije `_` para que sea una ruta de diseño sin ruta (sin segmento URL). Las plantillas usan `flatRoutes()`: el archivo de notación de puntos anterior es principal; el formato de carpeta anidada `inbox/route.tsx` también funciona.
-
-<Diagram id="doc-block-oocqxt" title={"El diseño sin camino envuelve las páginas."} summary={"Un diseño _app.tsx (sin segmento URL) representa el shell compartido una vez; las páginas coincidentes se muestran dentro de su <Outlet/>, por lo que la barra lateral del agente nunca se vuelve a montar durante la navegación."}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >layout sin ruta · shell persistente + barra del agente</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## Agregar una nueva página {#adding-a-page}
-
-Cree el archivo y exporte un componente predeterminado:
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-Eso es todo: el enrutador React lo detecta automáticamente, no es necesario registrarse.
-
-## Parámetros dinámicos {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## Navegación {#navigation}
-
-Utilice `<Link>` para navegación del lado del cliente y `useNavigate()` para navegación programática:
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## ¿Qué sigue?
-
-- [**Client**](/docs/client): utilidades y ganchos del navegador nativo del agente
-- [**Server**](/docs/server): rutas de servidor basadas en archivos y el espacio de nombres `/_agent-native/`
diff --git a/packages/core/docs/content/locales/fr-FR/client-advanced.mdx b/packages/core/docs/content/locales/fr-FR/client-advanced.mdx
new file mode 100644
index 0000000000..4167843a32
--- /dev/null
+++ b/packages/core/docs/content/locales/fr-FR/client-advanced.mdx
@@ -0,0 +1,195 @@
+---
+title: "Avancé"
+description: "Primitives et échappatoires de bas niveau de app/ : accès direct à l'état de l'application, envois de chat en arrière-plan, puces de suggestion personnalisées, et le pont hôte MCP App."
+---
+
+# Avancé
+
+Vue d'ensemble, Données et synchronisation, Chat de l'Agent, et Routage couvrent le cas typique : les hooks et assistants dont la plupart des pages ont besoin. Cette page couvre les primitives de plus bas niveau et les échappatoires plus étroites qui se trouvent dessous. La plupart des applications n'y touchent jamais directement. Recourez-y lorsque vous construisez quelque chose de plus personnalisé que ce que les hooks par défaut prennent en charge, comme une synchronisation de sélection personnalisée ou une MCP App intégrée. Pour synchroniser un `useQuery` brut avec une clé faite à la main, voir plutôt [Synchronisation interne](/docs/client-sync-internals).
+
+## État de l'application {#application-state}
+
+`application_state` est le magasin clé/valeur adossé à SQL que l'agent lit pour savoir ce que l'UI regarde actuellement, y compris la navigation, la sélection, et d'autres contextes d'objet ciblé (voir [Conscience du contexte](/docs/context-awareness)). `useAgentRouteState` et `useSemanticNavigationState` (également couverts dans Conscience du contexte) enveloppent déjà ces primitives pour le cas courant de navigation. Recourez directement aux primitives ci-dessous lorsque vous synchronisez quelque chose qu'elles ne couvrent pas, comme une sélection personnalisée, ou une écriture depuis l'extérieur du rendu d'un composant.
+
+### readClientAppState {#read-client-app-state}
+
+Lit la valeur actuelle d'une clé. Se résout avec ce qui a été écrit en dernier pour cette clé, ou `null` si la clé n'a jamais été écrite.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+Écrit une valeur pour une clé. Contrairement à `setClientAppState` ci-dessous, elle écrit toujours, même si vous transmettez `null`. Transmettre `undefined` lève une exception à la place, puisque `undefined` n'est pas du JSON valide. Utilisez `setClientAppState(key, undefined)` ou `deleteClientAppState()` pour effacer une clé.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+Le wrapper de convenance auquel la plupart du code UI devrait recourir : écrit la valeur, ou supprime la clé lorsque vous transmettez `null`/`undefined`. Utilisez ceci plutôt que `writeClientAppState` sauf si un site d'appel a véritablement besoin de « toujours écrire, jamais supprimer ».
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+Supprime entièrement une clé.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+Lit plusieurs clés en une seule requête. Renvoie `{ values, missing }`. `values` contient une entrée pour chaque clé pour laquelle le serveur a une ligne, y compris une clé explicitement écrite comme `null`. `missing` liste les clés qui n'ont jamais été écrites du tout. C'est ainsi que « jamais écrit » reste distinguable de « écrit comme null ».
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+Les requêtes de plus de 100 clés sont automatiquement fragmentées. `readClientAppState()` lui-même est construit sur cette base : les appels émis dans le même tick sont regroupés en une seule requête groupée en coulisses, donc l'appeler plusieurs fois dans une seule passe de rendu coûte un aller-retour, pas un par appel.
+
+### Options {#application-state-options}
+
+`signal` est accepté par les cinq fonctions ci-dessus, pour annuler un appel en cours. `requestSource` et `keepalive` ne s'appliquent qu'aux trois fonctions d'écriture, puisqu'elles ne signifient rien pour une lecture.
+
+| Option          | Type           | S'applique à                                                       | Description                                                                                                                        |
+| --------------- | -------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Marque l'écriture avec un id afin qu'un `useDbSync({ ignoreSource })` correspondant puisse ignorer de la relancer                  |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Permet à la requête de survivre au déchargement de la page. À utiliser pour les écritures de nettoyage comme effacer une sélection |
+| `signal`        | `AbortSignal?` | les cinq fonctions                                                 | Annule la requête                                                                                                                  |
+
+### Comportement en cas d'échec {#failure-behavior}
+
+Les cinq fonctions lèvent une exception en cas d'échec de la requête, de réponse non-2xx, ou de corps qui ne peut pas être analysé. L'`Error` levée porte une propriété `.status` lorsque le serveur a répondu, afin qu'un appelant puisse effectuer une branche selon le statut HTTP si nécessaire. Enveloppez un appel dans `try`/`catch`, ou laissez-le se propager vers une limite d'erreur, comme n'importe quel autre appel réseau.
+
+### Ce qu'est TAB_ID {#tab-id}
+
+`requestSource` est couramment défini sur `TAB_ID`, une constante simple que chaque modèle exporte depuis `app/lib/tab-id.ts` : une courte chaîne aléatoire qui reste la même pendant la durée de vie d'un onglet et diffère entre les onglets. Associer `requestSource: TAB_ID` sur une écriture avec `useDbSync({ ignoreSource: TAB_ID })` côté lecture est la façon dont un onglet évite de relancer sa propre écriture tout en continuant à réagir à tout le reste. Voir [Conscience du contexte](/docs/context-awareness#jitter-prevention) pour le parcours complet.
+
+## sendToAgentChat : envois en arrière-plan {#background-send}
+
+Utilisez `background: true` lorsqu'une action UI doit lancer un véritable travail
+d'agent sans ouvrir ni focaliser la barre latérale. Cela crée toujours un fil de
+discussion/une exécution normale, utilise les outils/actions/contexte de l'agent,
+et garde le travail observable via le plateau des exécutions. Ce n'est pas un
+appel de modèle brut et ponctuel.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` est destiné à être associé à `newTab` afin que le travail caché
+n'écrase pas la conversation active de l'utilisateur. Utilisez le `tabId`
+renvoyé si l'UI a besoin de corréler un suivi de statut ou de créer un lien
+profond vers l'exécution plus tard.
+
+Quelques options supplémentaires d'`AgentChatMessage` existent au-delà de celles couvertes dans [Chat de l’Agent](/docs/client-agent-chat#agentchatmessage), surtout pour des cas d'intégration ou d'intégration en aval :
+
+| Option                | Type        | Description                                                                           |
+| --------------------- | ----------- | ------------------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | Avec `newTab`, exécute sans focaliser l'onglet et affiche l'exécution dans `RunsTray` |
+| `projectSlug`         | `string?`   | Slug de projet facultatif pour un contexte structuré                                  |
+| `preset`              | `string?`   | Nom de préréglage facultatif pour les consommateurs en aval                           |
+| `referenceImagePaths` | `string[]?` | Chemins d'images de référence facultatifs                                             |
+
+## Pont hôte MCP App {#mcp-app-host-bridge}
+
+Les routes intégrées comme MCP Apps doivent être URL-first : charger l'artefact
+actuel depuis les paramètres de chemin/requête, afficher la véritable route
+React ou un composant partagé ciblé, et n'utiliser le pont hôte que pour le
+comportement appartenant à l'hôte. `@agent-native/core/client` exporte les
+assistants que les routes intégrées appellent :
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` lit le dernier instantané de contexte hôte poussé.
+`useMcpAppHostContext()` abonne les composants React aux changements. Les
+assistants de requête (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) renvoient `false` hors d'une frame MCP App
+intégrée, ou `Promise<boolean>` à l'intérieur d'une frame.
+
+`sendToAgentChat()` (voir [Chat de l’Agent](/docs/client-agent-chat#sendtoagentchat)) utilise le même pont pour les prompts auto-soumis depuis les routes intégrées. À l'intérieur d'une intégration MCP App créée avec `embedApp()`, les messages auto-soumis (`submit` omis ou `true`) sont transmis au pont, qui demande à l'hôte conteneur d'ajouter du contexte masqué et d'envoyer le tour visible de l'utilisateur. `context` reste visible pour le modèle sans être publié comme chat visible pour l'utilisateur. `submit: false` conserve le comportement local de préremplissage/révision puisque les MCP Apps ne définissent pas d'API standard de préremplissage de brouillon. En interne, ceci est le chemin de chat soumis parfois exposé comme `agentNative.submitChat`. Le code de l'application devrait toujours appeler `sendToAgentChat()` plutôt que de publier cet événement directement.
+
+Le pont lui-même, les messages JSON-RPC `ui/*`, le relais wrapper
+`agentNative.mcpHost.*`, le rendu par transplantation vs. frame contrôlée, le
+contexte hôte, et les requêtes de mode d'affichage, sont pris en charge par
+[Agents externes](/docs/external-agents#mcp-app-bridge). Voir [MCP Apps](/docs/mcp-apps) pour le protocole complet.
+
+## Puces de suggestion personnalisées {#custom-suggestions}
+
+Le `dynamicSuggestions` de `<AgentSidebar>` (voir [Chat de l’Agent](/docs/client-agent-chat#dynamic-suggestions)) fusionne déjà les `suggestions` statiques avec l'heuristique propre au framework, consciente du contexte. Transmettez `getSuggestions` à la place lorsqu'une application veut des puces déterministes, spécifiques à son domaine, calculées à partir du même contexte `application_state` plutôt qu'à partir de l'heuristique par défaut du framework.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` reçoit le même instantané `navigation`/`selection`/`pending-selection-context` que l'heuristique intégrée lit, afin qu'une implémentation personnalisée puisse réagir exactement au même état que celui lu par l'implémentation par défaut, simplement avec des règles spécifiques à l'application plutôt que génériques.
+
+## Quelle est la prochaine étape
+
+- [**Vue d’ensemble**](/docs/client-overview) — la disposition des répertoires `app/` et `public/` dans laquelle vivent ces primitives
+- [**Données et synchronisation**](/docs/client-data) — les hooks d'action par défaut et `useDbSync` que la plupart des pages devraient utiliser à la place
+- [**Synchronisation interne**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` et les deux chemins de latence qu'une relance peut prendre
+- [**Chat de l’Agent**](/docs/client-agent-chat) — les assistants par défaut `sendToAgentChat`/`askUserQuestion` que la plupart des UI devraient utiliser à la place, et les API d'état de contexte de chat agent en attente
+- [**Points d'entrée**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` et la personnalisation du streaming SSR
+- [**Conscience du contexte**](/docs/context-awareness) — la sémantique `navigation`/`selection` construite sur `application_state`, et le parcours `TAB_ID`/prévention de l'instabilité
+- [**Generative UI**](/docs/generative-ui) — des contrôles de chat en ligne plus riches au-delà de `askUserQuestion`
+- [**Agents externes**](/docs/external-agents#mcp-app-bridge) — les détails internes complets du pont hôte MCP App
diff --git a/packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx b/packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx
new file mode 100644
index 0000000000..bc11abff64
--- /dev/null
+++ b/packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx
@@ -0,0 +1,317 @@
+---
+title: "Chat de l’Agent"
+description: "Points d'entrée côté client dans le chat de l'agent : sendToAgentChat, openAgentSettings, askUserQuestion, suggestions dynamiques, useAgentChatGenerating, et état de contexte de chat agent en attente."
+---
+
+# Chat de l’Agent
+
+Le client de votre application peut parler à l'agent via un petit ensemble d'assistants côté client. Ceux-ci couvrent l'envoi d'un prompt, la mise en attente de contexte masqué, la pose d'une question bloquante à l'utilisateur, et l'ouverture du panneau de l'agent.
+
+Dans l'exemple ci-dessous, un bouton **Draft response** invite l'agent à poser une question à l'utilisateur. Une fois que l'utilisateur a répondu, l'agent se met à rédiger une réponse en tenant compte du contexte de la page actuelle et de la réponse de l'utilisateur.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="Capture d'écran de l'application Dispatch montrant la barre latérale d'historique des exécutions"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="La barre latérale d'historique des exécutions de Dispatch."
+/>
+
+## Comment ça marche
+
+En utilisant les méthodes d'assistant client fournies par Agent-Native, votre UI peut inviter l'agent à interagir avec l'utilisateur de diverses manières. Le diagramme ci-dessous montre comment un bouton « Draft response » peut être cliqué par l'utilisateur, ce qui invite ensuite l'agent à interagir avec l'utilisateur avant de générer une réponse.
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="Diagramme de séquence « qui possède chaque étape » avec trois lignes de vie : App Code, UI et Agent. Un clic sur « draft response » déclenche askUserQuestion() (rendu en ligne dans le panneau de l'agent). Après la réponse, sendDraftRequest() appelle draft-ticket-reply et renvoie une réponse au composeur de l'UI."
+  align="full"
+  width={600}
+  caption="Diagramme de séquence visualisant le flux d'un bouton « Draft response »."
+/>
+
+L'expérience utilisateur est la suivante :
+
+1. L'utilisateur clique sur le bouton **Draft response**, ce qui déclenche l'appel de la fonction `askUserQuestion()`. La question est répondue en ligne dans le panneau de l'agent.
+
+1. L'utilisateur choisit **Offer a refund**, ce qui déclenche `sendDraftRequest()` pour envoyer le prompt et le contexte du ticket à l'agent.
+
+1. L'agent appelle l'[action](/docs/actions) `draft-ticket-reply`, et la réponse rédigée apparaît dans le composeur de réponse.
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description:
+        "La question, ses options, et comment elle doit se comporter.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "La question complète. Claire, spécifique, se termine par un point d'interrogation.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'Puce/en-tête très court, environ 12 caractères, par ex. `"Response"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2 à 4 options distinctes. Chacune est `{ label, value?, description?, preview?, recommended? }`. `value` a par défaut la valeur de `label`.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            'Ajoute une option de texte libre "Other" dans laquelle le représentant peut taper.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Sélection multiple plutôt que sélection unique.",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description:
+            "Clé d'état d'application que le panneau de l'agent interroge.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      "La `value` choisie (ou `value[]` avec `allowMultiple`), le texte « Other » tapé par le représentant, ou `null` s'il passe la question. Reste en attente jusqu'à sa réponse. Nécessite que le panneau de l'agent soit monté, ce qui est le cas dans chaque modèle.",
+  }}
+/>
+
+Cette fonction pose à l'utilisateur une question à choix multiples depuis le code de l'application, l'affiche en ligne dans le panneau de l'agent, et attend sa réponse. Utilisez-la lorsque l'UI a besoin d'exactement une petite décision avec deux à quatre options avant de lancer le travail de l'agent, au lieu de construire un modal personnalisé.
+
+Dans l'exemple ci-dessous, un bouton « Draft Response » sur une page de ticket demande au représentant comment il souhaite répondre avant d'envoyer quoi que ce soit à l'agent :
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "Un tuple `[isGenerating, send]`. `isGenerating` est `true` dès que `send()` est appelé jusqu'à ce que l'exécution du chat de l'agent signale qu'elle s'est arrêtée. `send(opts)` a la même signature que `sendToAgentChat()`, et renvoie l'id d'onglet vers lequel il a envoyé.",
+  }}
+/>
+
+Ce hook React enveloppe `sendToAgentChat()` avec un suivi d'état de chargement.
+
+1. Le premier argument, `isGenerating`, passe à true lorsque vous l'appelez, puis revient à false lorsque l'agent termine la génération.
+
+2. Le second argument, `send()`, reflète la fonction `sendToAgentChat()`.
+
+`isGenerating` ne se réinitialise que lorsqu'une exécution démarre réellement et signale qu'elle s'est arrêtée. Un appel avec `submit: false` pré-remplit un brouillon sans démarrer d'exécution, donc `isGenerating` reste `true` pour toujours après un tel appel. Utilisez ce hook uniquement pour les envois avec `submit: true` ; appelez `sendToAgentChat()` directement pour ceux qui ne font que du préremplissage.
+
+Combiner ceci avec l'exemple `askUserQuestion()` ci-dessus complète le gestionnaire du bouton :
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="Compléter le gestionnaire de Draft Response"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "État de chargement + envoi, ensemble",
+      note: "`useAgentChatGenerating()` renvoie la même forme de tuple qu'un simple appel à `sendToAgentChat()`, mais ajoute `isDrafting` afin que le bouton puisse se désactiver lui-même tant que la requête est en cours.",
+    },
+    {
+      lines: "10-17",
+      label: "Réutilise l'étape de question",
+      note: "C'est exactement l'appel `askUserQuestion()` de la section ci-dessus, désormais à l'intérieur du gestionnaire propre du bouton.",
+    },
+    {
+      lines: "18",
+      label: "Affiner avant d'utiliser la réponse",
+      note: "Le type de retour autorise toujours un `string[]` provenant de `allowMultiple`, donc cette vérification est nécessaire même si cet appel ne l'active jamais.",
+    },
+    {
+      lines: "20-25",
+      label: "Transformer le choix en phrase",
+      note: "Associe la valeur sélectionnée, ou le texte tapé par le représentant lui-même, à la phrase que le prompt ci-dessous lit naturellement.",
+    },
+    {
+      lines: "27-32",
+      label: "Nommer l'action et l'intention",
+      note: "Le message indique à l'agent exactement quelle action appeler (`draft-ticket-reply`) et lui rappelle de ne pas envoyer la réponse directement. `openSidebar: true` garantit que la réponse rédigée est visible même si la barre latérale était fermée.",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting pilote le bouton",
+      note: "Désactivé et relibellé uniquement tant que `sendDraftRequest()` est en cours. Le bouton reste cliquable tant que `askUserQuestion()` attend le représentant, puisque cela se produit avant que `sendDraftRequest()` ne soit jamais appelé.",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Envoie un message au chat de l'agent via `postMessage`. C'est la primitive de plus bas niveau que `useAgentChatGenerating()` ci-dessus enveloppe, utile lorsqu'une interaction UI n'a pas besoin de son propre suivi d'état de chargement. Transmettez `context` pour un détail supplémentaire que le message seul ne porte pas. Il est ajouté au même message visible, entouré de balises `<context>`. Il n'est pas masqué à l'utilisateur. Transmettez `submit: true` pour envoyer immédiatement, ou `submit: false` pour pré-remplir un brouillon que l'utilisateur examine d'abord.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| Option        | Type       | Description                                                                                                 |
+| ------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | Le prompt envoyé au chat. `context`, si défini, est ajouté à ce même message visible                        |
+| `context`     | `string?`  | Détail supplémentaire ajouté au message visible, entouré de balises `<context>`. Pas masqué à l'utilisateur |
+| `submit`      | `boolean?` | true = envoi automatique, false = préremplissage uniquement                                                 |
+| `newTab`      | `boolean?` | Crée un fil de discussion distinct pour ce prompt                                                           |
+| `openSidebar` | `boolean?` | Définir sur false pour envoyer/préremplir sans ouvrir la barre latérale                                     |
+
+Exécuter ceci depuis l'intérieur d'une intégration MCP App, ou mettre l'exécution en arrière-plan sans ouvrir la barre latérale, sont tous les deux couverts dans [Avancé](/docs/client-advanced#background-send).
+
+## Suggestions dynamiques {#dynamic-suggestions}
+
+Avant qu'une conversation ne démarre, `<AgentSidebar>`, `<AgentPanel>`, et `<AssistantChat>` affichent des puces de prompt sur le chat vide. Par défaut, celles-ci ne sont pas seulement votre liste fixe de `suggestions` : le framework lit `navigation`, `selection`, `pending-selection-context`, et l'URL actuelle depuis l'état de l'application, et fusionne des puces qui correspondent à ce qui est réellement à l'écran.
+
+Il procède avec deux vérifications. Si quelque chose est sélectionné, il ajoute des puces génériques comme « Summarize this selection ». Séparément, il examine `navigation` à la recherche de noms de champs déjà courants dans les applications existantes, comme `threadId`/`emailId` pour un fil d'e-mail ou `dashboardId`/`chartId` pour un graphique, et ajoute des puces adaptées à ce type d'écran, comme « Draft a reply » pour un fil ou « Find anomalies in this data » pour un graphique. Ce qu'il produit est fusionné avec vos `suggestions` statiques, dédupliqué, et plafonné à `max`.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+Si l'écran actuel ne correspond à rien que l'heuristique reconnaît et que rien n'est sélectionné, elle ne fournit aucune puce, et le chat vide retombe uniquement sur vos `suggestions` statiques. Définissez `dynamicSuggestions={false}` pour ne conserver que les puces statiques. Si la forme de navigation de votre application ne correspond pas à l'heuristique intégrée, ou si vous voulez des puces spécifiques à l'application entièrement déterministes, voir [Avancé](/docs/client-advanced#custom-suggestions).
+
+## openAgentSettings(section?) {#openagentsettings}
+
+Utilisez `openAgentSettings()` lorsqu'une page de paramètres d'application ou une carte
+de configuration doit ouvrir l'onglet Paramètres du panneau latéral de l'agent.
+Transmettez un identifiant de section tel que `"llm"`, `"secrets"`,
+`"automations"`, `"voice"`, ou `"limits"` pour ouvrir une section spécifique.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Préférez cet assistant à l'envoi direct de `agent-panel:open-settings`.
+
+## État de contexte du chat de l'agent {#agent-chat-context-state}
+
+Les API d'état de contexte sont une plomberie facultative pour l'UI qui a besoin d'une synchronisation bidirectionnelle avec les puces de contexte préparées : afficher les éléments actuellement préparés hors du composeur, refléter si un élément est déjà attaché, ou fournir des contrôles explicites de suppression/effacement.
+
+Ne recourez pas à ces assistants pour les flux simples de « envoyer ceci à l'agent » ou « pré-remplir ce brouillon pour révision ». Utilisez [`sendToAgentChat()`](#sendtoagentchat) avec `context` et `submit` pour ceux-là.
+
+| API                               | Utiliser quand                                                                                       |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | Un composant React a besoin de la liste de contexte préparée en direct                               |
+| `setAgentChatContextItem(item)`   | Du code impératif doit préparer ou remplacer un élément de contexte à clé                            |
+| `listAgentChatContext()`          | Du code non-React a besoin d'un instantané ponctuel du contexte préparé                              |
+| `removeAgentChatContextItem(key)` | L'UI doit supprimer un élément de contexte préparé par sa `key` stable                               |
+| `clearAgentChatContext()`         | L'UI doit effacer tout le contexte préparé, par exemple après une réinitialisation de vue ou de mode |
+| `refreshAgentChatContext()`       | Du code impératif doit relire le dernier instantané de contexte persisté                             |
+
+`useAgentChatContext()` renvoie `{ items, set, remove, clear, refresh }`.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` est destiné au code impératif qui doit seulement inspecter les éléments actuellement préparés une fois. `clearAgentChatContext()` est volontairement large. Utilisez `removeAgentChatContextItem(key)` lorsqu'une seule sélection a changé.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| Option        | Type       | Description                                                             |
+| ------------- | ---------- | ----------------------------------------------------------------------- |
+| `key`         | `string`   | Identifiant stable utilisé pour remplacer un élément existant           |
+| `title`       | `string`   | Court libellé affiché dans la puce du composeur                         |
+| `context`     | `string`   | Contexte masqué inclus avec le prochain prompt envoyé                   |
+| `openSidebar` | `boolean?` | Vrai par défaut. Passez false pour préparer le contexte silencieusement |
+
+## Quelle est la prochaine étape
+
+- [**Vue d’ensemble**](/docs/client-overview) — où ces assistants s'intègrent dans `app/`
+- [**Données et synchronisation**](/docs/client-data) — les hooks d'action et `useDbSync` qui maintiennent l'UI elle-même à jour
+- [**Agent sans rendez-vous**](/docs/drop-in-agent) — monter `<AgentSidebar>`/`<AgentPanel>` afin que ces assistants aient un endroit où s'afficher
+- [**Avancé**](/docs/client-advanced) — envois en arrière-plan, puces de suggestion personnalisées, et le pont hôte MCP App
+- [**Generative UI**](/docs/generative-ui) — construire des contrôles de chat en ligne plus riches au-delà de `askUserQuestion`
diff --git a/packages/core/docs/content/locales/fr-FR/client-data.mdx b/packages/core/docs/content/locales/fr-FR/client-data.mdx
new file mode 100644
index 0000000000..910023fa23
--- /dev/null
+++ b/packages/core/docs/content/locales/fr-FR/client-data.mdx
@@ -0,0 +1,436 @@
+---
+title: "Données et synchronisation"
+description: "Les hooks d'action que app/ utilise pour lire, écrire et rester synchronisé en direct avec les mêmes actions que celles appelées par l'agent."
+---
+
+# Données et synchronisation
+
+Le principal moyen de lire et d'écrire des données d'application depuis le client est d'utiliser les hooks d'[action](/docs/actions). En intégrant les requêtes dans des actions, votre client et votre agent peuvent tous deux interagir avec votre application de la même manière.
+
+Dans l'exemple ci-dessous, un ticket est assigné à l'utilisateur actuel manuellement via une liste déroulante, puis via l'agent de chat. L'UI et l'agent accèdent tous deux à la même action.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="Exemple d'une action UI et d'une action agent produisant le même résultat."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Exemple d'une action UI et d'une action agent produisant le même résultat."
+/>
+
+## Récupérer et muter des données {#fetching-mutating}
+
+Une application typique construit sa propre couche API et l'appelle avec des requêtes `fetch` écrites à la main. Une application native d'agent se passe de cette couche : `app/` appelle les mêmes actions que celles que l'agent possède déjà comme outils, via les hooks ci-dessous.
+
+<Diagram id="doc-block-client-data-fm-1" title="fetch typique vs. un hook d'action" summary="Un composant typique appelle une route que lui seul peut atteindre. Un composant natif d'agent appelle une action que l'agent peut aussi appeler.">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Typique</div>
+    <div class="diagram-node">Composant</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Votre route API</strong>
+      <small class="diagram-muted">seul le frontend peut l'appeler</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Base de données</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Composant</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">action get-lead</span>
+      <small class="diagram-muted">aussi un outil d'agent</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>base de données SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Hooks d'action {#action-hooks}
+
+Il y a deux hooks d'action que vous êtes le plus susceptible d'utiliser : `useActionQuery()` et `useActionMutation()`. Ces deux hooks donnent accès aux actions de votre application.
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "Le nom enregistré de l'action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "L'entrée de l'action, typée à partir de son schéma `defineAction()`.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "Tout ce qui vient des [options de useQuery](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) sauf `queryKey` et `queryFn`, que le hook définit lui-même.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      'Mis en cache sous `["action", name, params]`. Se relance automatiquement chaque fois qu\'une action de mutation se termine, sans invalidation manuelle nécessaire.',
+  }}
+/>
+
+Ce hook est destiné à être utilisé pour les actions en lecture seule. C'est un wrapper léger autour de la fonction [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).
+
+Dans l'exemple ci-dessous, l'action `list-tickets` est appelée. C'est similaire à effectuer une requête GET pour tous les tickets.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+L'exemple suivant montre une requête pour récupérer un seul ticket, via l'action `get-ticket`. Un `ticketId` est fourni pour restreindre la requête à un ticket spécifique. L'option supplémentaire `enabled` est fournie pour garantir que la requête ne s'exécute pas automatiquement, et ne s'exécute que lorsqu'un `ticketId` est présent.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "Le nom enregistré de l'action.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "Tout ce qui vient des [options de useMutation](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) sauf `mutationFn`, que le hook définit lui-même.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Remplace la méthode de requête par défaut.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Désactive le rafraîchissement automatique du cache en cas de succès.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'En cas de succès, émet un événement de changement avec `source: "action"`, afin que chaque `useActionQuery()` lisant les données affectées se relance automatiquement. Aucune invalidation manuelle n\'est nécessaire.',
+  }}
+/>
+
+Ce hook est destiné à être utilisé pour les actions qui modifient des données, comme la création, la mise à jour ou l'envoi de quelque chose. C'est un wrapper léger autour de la fonction [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation).
+
+Contrairement à `useActionQuery()`, l'entrée de l'action n'est pas transmise au hook lui-même. Elle est transmise à `mutate()` ou `mutateAsync()` lorsque vous êtes prêt à exécuter la mutation.
+
+Dans l'exemple ci-dessous, l'action `send-ticket-reply` est appelée pour publier une réponse à un ticket. Appelez `mutate()` depuis un gestionnaire d'événement, comme l'`onClick` d'un bouton.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+L'exemple suivant montre la même mutation avec une option `onSuccess`. L'invalidation du cache se produit automatiquement après chaque mutation, donc `onSuccess` n'est nécessaire que pour des effets de bord locaux, comme vider le composeur de réponse une fois la réponse envoyée.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "Le nom enregistré de l'action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "L'entrée de l'action, typée à partir de son schéma `defineAction()`.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "Tout ce qui suit est facultatif.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Remplace la méthode de requête par défaut.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "Annule la requête.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Remplace le délai d'expiration par défaut de 60 secondes, pour les actions qui prennent légitimement plus de temps.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "Contrairement aux hooks ci-dessus, il n'y a ni cache ni relance automatique. Associez-le à une invalidation manuelle si d'autres éléments de l'UI dépendent du résultat.",
+  }}
+/>
+
+Cette fonction est destinée aux appels d'action impératifs ponctuels hors d'un flux de rendu React, comme un simple gestionnaire d'événement, un script, ou tout autre chemin de code non React. Elle renvoie directement une promesse plutôt qu'un résultat de hook.
+
+Dans l'exemple ci-dessous, l'action `update-ticket` est appelée depuis un gestionnaire de raccourci clavier hors du flux de rendu de React, pour assigner le ticket à un représentant.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+L'exemple suivant montre le même appel avec une option `timeoutMs`, utile pour les actions qui prennent légitimement plus de temps que le délai d'expiration par défaut de 60 secondes.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+Chaque requête `useActionQuery()`, `useActionMutation()`, et `callAction()` est limitée par un délai d'expiration de 60 secondes, et les délais d'expiration apparaissent comme des erreurs plutôt que de relancer silencieusement. `useActionQuery()` annule aussi automatiquement les requêtes remplacées, en utilisant le signal d'abandon de React Query.
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "Chaque champ est facultatif.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description:
+            "Client React Query utilisé pour l'invalidation du cache.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "URL du point de terminaison d'interrogation.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "URL du point de terminaison SSE. Passez `false` pour n'utiliser que l'interrogation.",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "Intervalle d'interrogation en ms.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Intervalle d'interrogation tant que SSE est connecté, comme secours au cas où un événement serait manqué. Un onglet déconnecté interroge à la cadence plus rapide `interval` (ou une cadence d'inactivité fixe) à la place.",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Suspend l'interrogation lorsque l'onglet du navigateur est masqué. Les onglets masqués gardent SSE connecté et n'interrogent pas plus vite que toutes les 10 s tant qu'ils sont actifs, 60 s une fois inactifs.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "Source de requête par onglet à ignorer, afin qu'un onglet ne se relance pas à partir de ses propres écritures.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "Callback facultatif lorsque SSE ou l'interrogation reçoit un événement de changement.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "Filtre l'invalidation large qu'un événement d'action déclenche. Rarement nécessaire. Utilisez-le pour garder une requête active coûteuse sur une sémantique de rafraîchissement explicite, alors que les requêtes normales à version de source continuent de réagir via `useChangeVersion`.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "Noms d'actions dont les événements de synchronisation ne doivent pas invalider toutes les requêtes d'action. Uniquement pour les actions en arrière-plan à haut volume qui effectuent déjà leur propre invalidation restreinte.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description:
+            "Obsolète et ignoré. Conservé pour les anciens sites d'appel.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+Ce hook est destiné à maintenir l'UI synchronisée avec les changements de base de données qui se produisent en dehors de vos propres actions, comme une écriture de l'agent, un webhook, ou un changement effectué depuis un autre onglet du navigateur. Il écoute les changements via des événements envoyés par le serveur, et revient à l'interrogation lorsque les événements envoyés par le serveur ne sont pas disponibles.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+Pour les CRUD normaux, préférez `useActionQuery()` et `useActionMutation()`. Les actions de mutation émettent `source: "action"`, donc ces hooks se relancent immédiatement. Les changements provenant de l'agent, d'un webhook, ou d'un autre onglet arrivent via `useDbSync()` à la place, via SSE ou le secours par interrogation. Si un appel `useQuery()` brut a besoin de se synchroniser sur une clé personnalisée, voir [Synchronisation interne](/docs/client-sync-internals). Si vous avez besoin d'écrire directement dans `application_state`, voir [Avancé](/docs/client-advanced).
+
+## Quelle est la prochaine étape
+
+- [**Vue d’ensemble**](/docs/client-overview) — la disposition des répertoires `app/` et `public/` dans laquelle vivent les hooks de cette page
+- [**Chat de l’Agent**](/docs/client-agent-chat) — envoyer des prompts et préparer du contexte pour l'agent
+- [**Actions**](/docs/actions) — la surface `defineAction` derrière chaque hook de cette page
+- [**Avancé**](/docs/client-advanced) — accès direct à `application_state`
+- [**Synchronisation interne**](/docs/client-sync-internals) — synchroniser un `useQuery` brut avec `useChangeVersion`
+- [**Synchronisation en direct**](/docs/key-concepts#polling-sync) — comment `useDbSync` maintient l'UI à jour
diff --git a/packages/core/docs/content/locales/fr-FR/client-entry-points.mdx b/packages/core/docs/content/locales/fr-FR/client-entry-points.mdx
new file mode 100644
index 0000000000..350e9e1af7
--- /dev/null
+++ b/packages/core/docs/content/locales/fr-FR/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "Points d'entrée"
+description: "app/entry.client.tsx et app/entry.server.tsx : les wrappers légers d'hydratation et de bootstrap SSR, et quand personnaliser le comportement de streaming."
+---
+
+# Points d'entrée
+
+`app/entry.client.tsx` hydrate le HTML rendu côté serveur dans le navigateur, et `app/entry.server.tsx` rend ce HTML sur le serveur. Les deux sont des wrappers légers générés par React Router. Vous avez rarement besoin de les modifier.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+Recourez à ces fichiers uniquement pour une personnalisation SSR avancée, par exemple changer le comportement de streaming. Les pages, la mise en page et les données ordinaires n'ont pas besoin de changements ici. Voir [Routage](/docs/client-routing) pour ajouter des pages à la place.
+
+## Quelle est la prochaine étape
+
+- [**Vue d’ensemble**](/docs/client-overview) — où ces fichiers se situent dans `app/`
+- [**Routage**](/docs/client-routing) — ajouter des pages, la façon normale d'étendre `app/`
+- [**Avancé**](/docs/client-advanced) — les autres primitives et échappatoires de bas niveau du client
diff --git a/packages/core/docs/content/locales/fr-FR/client-overview.mdx b/packages/core/docs/content/locales/fr-FR/client-overview.mdx
new file mode 100644
index 0000000000..3543c0a1e4
--- /dev/null
+++ b/packages/core/docs/content/locales/fr-FR/client-overview.mdx
@@ -0,0 +1,205 @@
+---
+title: "Vue d’ensemble"
+description: "Les répertoires app/ et public/ : où vous construisez l'affichage d'une application native d'agent, et les API navigateur qu'elle utilise pour rester synchronisée avec l'agent."
+---
+
+# Vue d’ensemble
+
+`app/` est l'endroit où vous construisez l'affichage réel d'une application native d'agent : pages, mise en page, composants, styles. `public/` contient les ressources statiques servies à côté — icônes, manifeste, marques. Il s'agit d'une application React Router v8 typique, pas d'une surface réservée à l'agent, et c'est là que va la majeure partie du temps de développement.
+
+L'unique différence architecturale par rapport à un frontend typique : cette couche n'a pas de backend-for-frontend propre. Elle lit et écrit des données via les mêmes actions que celles appelées par l'agent, donc tout ce qui est câblé ici est automatiquement quelque chose que l'agent peut aussi faire.
+
+<Diagram id="doc-block-client-overview-1" title="Frontend traditionnel vs. Agent Native" summary="Un frontend traditionnel appelle sa propre couche API, que lui seul peut atteindre. Dans Agent Native, app/ et l'agent appellent tous deux les mêmes actions, donc chaque fonctionnalité construite ici est appelable par l'agent gratuitement.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Traditionnel</div>
+    <div class="diagram-node">app/ (frontend React)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Couche API</strong>
+      <small class="diagram-muted">seul le frontend l'appelle</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Base de données</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (frontend React)</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">partenaires égaux, mêmes opérations</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>base de données SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Où s'intègre le Client {#role}
+
+Les requêtes du navigateur, la boucle de l'agent et les clients API externes aboutissent tous aux mêmes actions et à la même base de données SQL — il n'existe pas de « backend d'application » séparé auquel cette couche parle et que l'agent ne pourrait pas aussi atteindre. Construire une fonctionnalité ici signifie construire une UI au-dessus d'une opération que l'agent possède déjà, ou définir une nouvelle action et obtenir une UI pour elle en même temps. Voir [Actions](/docs/actions) pour le côté opération de ce contrat.
+
+Cette page couvre les répertoires dans lesquels vous construisez et les éléments du runtime navigateur que rien d'autre ne documente (`root.tsx`, `public/`). Les hooks React qui connectent vos composants aux actions et à l'agent vivent sur leurs propres pages dédiées :
+
+| Page                                                       | Ce qu'elle couvre                                                                                                               |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| **[Données et synchronisation](/docs/client-data)**        | `useActionQuery`, `useActionMutation`, `callAction`, et `useDbSync`                                                             |
+| **[Chat de l’Agent](/docs/client-agent-chat)**             | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, suggestions dynamiques, et état de contexte de chat agent en attente |
+| **[Avancé](/docs/client-advanced)**                        | Accès direct à `application_state`, envois de chat en arrière-plan, puces de suggestion personnalisées, et le pont hôte MCP App |
+| **[Synchronisation interne](/docs/client-sync-internals)** | `useChangeVersion`/`useChangeVersions` pour synchroniser un `useQuery` brut                                                     |
+| **[Points d'entrée](/docs/client-entry-points)**           | `app/entry.client.tsx`/`app/entry.server.tsx` et la personnalisation SSR                                                        |
+
+## Le contenu de app/ et public/ {#project-directories}
+
+| Chemin                                              | Ce qu'il couvre                                                                                                                                            |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | Le shell HTML et la pile de providers — voir [Le shell du navigateur](#app-shell) ci-dessous                                                               |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Bootstrap d'hydratation et SSR — voir [Points d'entrée](/docs/client-entry-points)                                                                         |
+| **`app/routes.ts` + `app/routes/`**                 | Pages basées sur des fichiers et navigation — voir [Routage](/docs/client-routing)                                                                         |
+| **`app/components/`**                               | Votre UI : primitives de style shadcn plus des composants spécifiques à l'application — voir [shadcn/ui](/docs/shadcn-ui)                                  |
+| **`app/hooks/`**                                    | Hooks de données, de synchronisation et de chat agent — voir [Données et synchronisation](/docs/client-data) et [Chat de l’Agent](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | Utilitaires client partagés (config de l'application, id d'onglet, `cn`) — voir [Utilitaires](#utilities) ci-dessous                                       |
+| **`app/design-system.ts`**                          | Adaptateur de système de design personnalisé facultatif — voir [Systèmes de conception personnalisés](/docs/custom-design-system)                          |
+| **`app/i18n/`**                                     | Catalogues de traduction UI localisés — voir [Internationalisation](/docs/internationalization)                                                            |
+| **`app/global.css`**                                | Styles de base et point d'entrée Tailwind                                                                                                                  |
+| **`public/`**                                       | Ressources statiques servies telles quelles — voir [Ressources statiques](#public-directory) ci-dessous                                                    |
+
+## Le shell du navigateur : root.tsx et AppProviders {#app-shell}
+
+`app/root.tsx` est le sommet de l'arborescence React : le shell du document HTML (`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`) plus la pile de providers dans laquelle chaque route s'affiche.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` est le wrapper unique qui met en place :
+
+- Le client React Query utilisé par `useActionQuery`/`useActionMutation` (voir [Données et synchronisation](/docs/client-data#fetching-mutating)).
+- Le catalogue i18n transmis en tant que `i18n.catalog` (voir [Internationalisation](/docs/internationalization)).
+- Les contrôles de session côté client : sur un chemin privé, un visiteur anonyme est redirigé vers la connexion avant qu'aucune UI privée ne se monte. Transmettez `isPublicPath` pour les routes publiques/SEO, ou `sessionBypass` pour une surface qui s'authentifie d'une autre manière, comme un jeton d'intégration MCP. Voir [Authentication](/docs/authentication).
+
+La plupart des applications montent aussi `<AgentSidebar>` ou `<AgentPanel>` ici afin que chaque route bénéficie gratuitement du panneau d'agent. Voir [Agent sans rendez-vous](/docs/drop-in-agent#sidebar).
+
+## Ressources statiques : public/ {#public-directory}
+
+Tout ce qui se trouve dans `public/` est servi tel quel à la racine du site, non traité par le build. Chaque modèle inclut :
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+`manifest.json` contrôle ce qui s'affiche si un visiteur installe l'application sur un écran d'accueil ou un dock — nom, nom court, couleur de thème/arrière-plan, et l'ensemble d'icônes :
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+Rebrandez une application en remplaçant ces fichiers et en mettant à jour `manifest.json` ainsi que les balises `<link rel="icon">`/`<link rel="apple-touch-icon">` dans `root.tsx` qui les référencent — il n'y a pas d'étape d'enregistrement séparée. Pour récupérer un système de marque complet (couleurs, polices, favicon) à partir d'un site existant au lieu de modifier ces fichiers à la main, voir [Brand Systems and Figma](/docs/template-design-brand-and-figma).
+
+## Utilitaires : cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` fusionne les noms de classe (clsx + tailwind-merge) et constitue la méthode standard pour composer des classes Tailwind conditionnelles dans `app/components/`.
+
+## Quelle est la prochaine étape
+
+- [**Données et synchronisation**](/docs/client-data) — les hooks d'action et `useDbSync`
+- [**Chat de l’Agent**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion`, et les suggestions dynamiques
+- [**Avancé**](/docs/client-advanced) — l'état de l'application, les envois de chat en arrière-plan, et le pont hôte MCP App
+- [**Synchronisation interne**](/docs/client-sync-internals) — `useChangeVersion` pour synchroniser un `useQuery` brut
+- [**Routage**](/docs/client-routing) — pages basées sur des fichiers, paramètres dynamiques, et navigation
+- [**Actions**](/docs/actions) — la surface `defineAction` derrière chaque hook de données
+- [**Custom Design Systems**](/docs/custom-design-system) — remplacer votre propre bibliothèque de composants via `app/design-system.ts`
+- [**Authentication**](/docs/authentication) — les contrôles de session que `AppProviders` exécute sur les chemins privés
diff --git a/packages/core/docs/content/locales/fr-FR/client-routing.mdx b/packages/core/docs/content/locales/fr-FR/client-routing.mdx
new file mode 100644
index 0000000000..91af8aef8a
--- /dev/null
+++ b/packages/core/docs/content/locales/fr-FR/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "Routage"
+description: "Routage basé sur des fichiers pour les applications natives d'agent avec React Router v8 : pages, paramètres dynamiques, et navigation."
+---
+
+# Routage
+
+Les applications natives d'agent utilisent **React Router v8** avec un routage basé sur des fichiers via `flatRoutes()` de `@react-router/fs-routes`. Chaque fichier dans `app/routes/` devient une URL. Les modèles utilisent la convention de notation par points. Les points séparent les segments d'URL à l'intérieur d'un seul nom de fichier.
+
+Cette page couvre les routes client, les pages rendues dans le navigateur à partir de `app/routes/`. Les routes serveur sont un système distinct : les fichiers de routes Nitro sous `server/routes/`, plus les points de terminaison propres au framework `/_agent-native/*`. Ceux-ci vivent sur la page [Routes](/docs/server-routes). Les deux ne partagent ni répertoire, ni convention de nommage, ni routeur, donc un fichier de `server/routes/` ne devient jamais une page ici et un fichier de `app/routes/` ne devient jamais un point de terminaison serveur.
+
+<Diagram id="doc-block-client-routing-1" title="Nom de fichier → URL" summary="Chaque fichier dans app/routes/ devient une URL. Les points deviennent des barres obliques, et un segment $ devient un paramètre dynamique.">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Routage basé sur des fichiers {#file-based-routing}
+
+### Mappage fichier → URL
+
+| Fichier                    | URL                    | Remarques                                                                          |
+| -------------------------- | ---------------------- | ---------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | Route d'index                                                                      |
+| `dashboard.tsx`            | `/dashboard`           | Page simple                                                                        |
+| `extensions.$id.tsx`       | `/extensions/:id`      | S'imbrique dans le `<Outlet/>` de `extensions.tsx`. `$` est un paramètre dynamique |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | Le `_` final évite l'imbrication sous `dashboard.tsx`, donc c'est sa propre page   |
+| `_app.tsx`                 | (pas de segment URL)   | Mise en page sans chemin. Préfixe avec `_`                                         |
+| `inbox/route.tsx`          | `/inbox`               | Forme dossier. `route.tsx` est l'index                                             |
+
+Préfixez un segment avec `$` pour un paramètre dynamique. Préfixez avec `_` pour en faire une route de mise en page sans chemin (pas de segment URL), ou ajoutez un `_` final avant un point pour qu'un chemin d'apparence imbriquée renonce à l'imbrication sous la mise en page de son parent. Les modèles utilisent `flatRoutes()`. Le fichier en notation par points ci-dessus est la forme principale. La forme en dossier imbriqué `inbox/route.tsx` fonctionne aussi.
+
+## Ajouter une nouvelle page {#adding-a-page}
+
+Créez le fichier et exportez un composant par défaut :
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+C'est tout. React Router le récupère automatiquement, aucun enregistrement n'est nécessaire.
+
+## Paramètres dynamiques {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+Le `_` final avant le point évite que cette page ne s'imbrique dans le `<Outlet/>` de `dashboard.tsx`, elle s'affiche donc comme sa propre page complète à `/dashboard/:ticketId` au lieu d'apparaître dans la mise en page de la file d'attente de tickets.
+
+## Navigation {#navigation}
+
+Utilisez `<Link>` pour la navigation côté client et `useNavigate()` pour la navigation par programmation :
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+Aucun des deux n'informe l'agent de lui-même de ce que l'utilisateur regarde. C'est une préoccupation distincte, prise en charge par `useAgentRouteState()` qui écrit la route actuelle dans l'état de l'application. Voir [Conscience du contexte](/docs/context-awareness).
+
+## Quelle est la prochaine étape
+
+- [**Vue d’ensemble**](/docs/client-overview) — où `app/routes/` s'intègre parmi le reste de `app/` et `public/`
+- [**Données et synchronisation**](/docs/client-data) — lire et écrire des données depuis une route
+- [**Chat de l’Agent**](/docs/client-agent-chat) — envoyer des prompts et préparer du contexte depuis une route
+- [**Routes**](/docs/server-routes) — le système de routage serveur distinct : les fichiers de routes sous `server/routes/` et l'espace de noms `/_agent-native/` du framework
+- [**Conscience du contexte**](/docs/context-awareness) — comment l'agent apprend la route et la sélection actuelles
diff --git a/packages/core/docs/content/locales/fr-FR/client-sync-internals.mdx b/packages/core/docs/content/locales/fr-FR/client-sync-internals.mdx
new file mode 100644
index 0000000000..b5a77561f3
--- /dev/null
+++ b/packages/core/docs/content/locales/fr-FR/client-sync-internals.mdx
@@ -0,0 +1,127 @@
+---
+title: "Synchronisation interne"
+description: "Le mécanisme de version de changement derrière useDbSync : useChangeVersion/useChangeVersions pour synchroniser un useQuery brut, et les deux chemins de latence qu'une relance peut prendre."
+---
+
+# Synchronisation interne
+
+[Synchronisation en direct](/docs/key-concepts#polling-sync) couvre le modèle mental : une écriture de l'agent devient un événement de changement, `useDbSync()` le capte, et les requêtes affectées se relancent. Cette page couvre le mécanisme sous-jacent que la plupart des applications ne touchent jamais directement : les compteurs de version de changement que `useDbSync()` incrémente, et comment les intégrer dans un appel `useQuery()` brut qui ne passe pas par `useActionQuery()`.
+
+`useActionQuery()` se relance déjà automatiquement lorsqu'une action de mutation se termine (voir [Données et synchronisation](/docs/client-data#fetching-mutating)). Recourez à `useChangeVersion()`/`useChangeVersions()` uniquement lorsque vous synchronisez un appel `useQuery()` brut hors de ce chemin, comme un assistant client de bas niveau lisant un statut d'intégration.
+
+## Comment fonctionnent les versions de changement {#how-it-works}
+
+Lorsqu'une mutation de base de données côté serveur se produit, le serveur enregistre un événement de changement marqué avec une clé `source`. `useDbSync()` reçoit cet événement et incrémente un compteur local pour cette source. Intégrer le compteur dans une clé de requête React Query fait que la requête se relance automatiquement chaque fois que le backend signale une nouvelle activité pour cette source.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description:
+        'La source d\'événement de changement à surveiller, par ex. `"dashboards"`.',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description:
+      "Un compteur qui s'incrémente chaque fois que la source donnée est mutée.",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description:
+        "Plusieurs sources d'événements de changement à surveiller à la fois.",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "La somme des compteurs de version pour chaque source donnée.",
+  }}
+/>
+
+Dans l'exemple ci-dessous, un appel `useQuery()` brut lit directement un tableau de bord, en intégrant le compteur de version de la source `"dashboards"` dans sa clé de requête afin qu'il se relance chaque fois que cette source change :
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` garde les données précédentes affichées pendant la relance, afin que la vue ne clignote pas vers un état de chargement.
+
+## Deux chemins vers une relance {#latency-models}
+
+Une mutation atteint l'UI d'une des deux façons, et elles ont des latences différentes.
+
+Une mutation locale, celle qu'un appel `useActionMutation()` propre vient de faire, déclenche un événement `source: "action"` dès qu'elle réussit. Chaque requête dépendant de cette action se relance immédiatement. Il n'y a pas de délai d'aller-retour, puisque l'onglet qui a fait l'écriture la connaît déjà.
+
+Une mutation distante, provenant de l'agent, d'un webhook, d'un autre onglet, ou d'un autre utilisateur, doit atteindre cet onglet d'abord. `useDbSync()` la capte via SSE presque immédiatement, ou via le secours par interrogation en environ deux secondes si SSE n'est pas disponible. Ce n'est qu'une fois cet événement arrivé que le compteur de version pertinent s'incrémente et que la requête se relance en arrière-plan.
+
+<Diagram id="doc-block-client-sync-internals-3" title="Deux chemins vers une relance" summary="Une mutation locale invalide instantanément ses propres caches. Une écriture distante atteint cet onglet via SSE, ou le tick d'interrogation en secours.">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">Cet onglet</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >déclenche source: "action" en cas de succès &rarr; relance locale
+        instantanée</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">Agent · webhook · autre onglet</span
+      ><strong>Écriture distante</strong
+      ><small class="diagram-muted"
+        >push SSE, ou le tick d'interrogation ~2 s en secours &rarr; le compteur
+        de version augmente &rarr; relance en arrière-plan</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## Quelle est la prochaine étape
+
+- [**Synchronisation en direct**](/docs/key-concepts#polling-sync) — le modèle mental conceptuel sous lequel se trouve cette page
+- [**Données et synchronisation**](/docs/client-data) — `useActionQuery`/`useDbSync`, que la plupart des pages devraient utiliser à la place de ces primitives
+- [**Avancé**](/docs/client-advanced) — les autres primitives et échappatoires de bas niveau du client
diff --git a/packages/core/docs/content/locales/fr-FR/client.mdx b/packages/core/docs/content/locales/fr-FR/client.mdx
deleted file mode 100644
index 094bda4caa..0000000000
--- a/packages/core/docs/content/locales/fr-FR/client.mdx
+++ /dev/null
@@ -1,472 +0,0 @@
----
-title: "Client"
-description: "Hooks et utilitaires React pour les applications natives d'agent : sendToAgentChat, état de contexte de discussion d'agent facultatif, useDbSync, useAgentChatGenerating et cn."
----
-
-# Client
-
-`@agent-native/core` fournit des hooks et des utilitaires React pour le côté navigateur des applications natives d'agent.
-
-Ces clients/React API sont exportés à partir de `@agent-native/core` et `@agent-native/core/client`. Importez-les depuis `@agent-native/core/client` (l'entrée du navigateur) pour plus de clarté et un regroupement correct, car la racine nue `@agent-native/core` est résolue par défaut en la version Node.
-
-Pour le routage basé sur des fichiers (ajout de pages, de paramètres dynamiques et de navigation), voir [Routing](/docs/routing).
-
-## Récupération et mutation de données {#fetching-mutating}
-
-Le principal moyen de lire et d'écrire des données d'application à partir du navigateur consiste à utiliser les crochets d'action. N'écrivez jamais manuellement les appels `fetch` vers les routes `/_agent-native/*` ; utilisez plutôt les assistants nommés (voir [Actions](/docs/actions)).
-
-<Diagram id="doc-block-u8e2p3" title={"La boucle de données du navigateur"} summary={"Les hooks lisent et écrivent via des actions ; useDbSync surveille la base de données afin que les écritures de l'agent et en arrière-plan récupèrent automatiquement les mêmes caches."}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough>
-    <strong>base de données SQL</strong>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat (opts) {#sendtoagentchat}
-
-Envoyez un message au chat de l'agent via postMessage : le moyen courant de déléguer une tâche d'IA à partir d'une interaction UI. Transmettez `context` pour le contexte de modèle masqué et `submit: true` pour l'envoyer immédiatement, ou `submit: false` pour pré-remplir un brouillon que l'utilisateur examine en premier.
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-Dans une application MCP intégrée créée avec `embedApp()`, messages soumis automatiquement
-(`submit` omis ou `true`) sont transmis au pont hôte de l'application MCP, qui
-demande à l'hôte conteneur d'ajouter un contexte masqué et d'envoyer le tour de l'utilisateur visible.
-`context` reste visible par le modèle sans être publié en tant que chat face à l'utilisateur.
-`submit: false` conserve le comportement local de pré-remplissage/révision, car les applications MCP ne le font pas
-définir un brouillon-pré-remplissage standard API. En interne, il s'agit du chemin de discussion soumis
-apparaissait parfois sous le nom de `agentNative.submitChat` ; le code de l'application devrait appeler
-`sendToAgentChat()` plutôt que de publier cet événement directement.
-
-### Envois en arrière-plan silencieux {#background-send}
-
-Utilisez `background: true` lorsqu'une action UI devrait lancer le travail d'un agent réel sans
-ouvrir ou focaliser la barre latérale. Cela crée toujours un fil de discussion/une exécution normale,
-utilise les outils/actions/context de l'agent et maintient le travail observable tout au long
-le plateau des courses ; il ne s'agit pas d'un appel de modèle brut et unique.
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` est destiné à être associé à `newTab` afin que le travail caché ne le soit pas
-écraser la conversation active de l'utilisateur. Utilisez le `tabId` renvoyé si le UI
-doit corréler l'état du suivi ou créer un lien profond vers l'exécution ultérieure.
-
-### Message de discussion d'agent {#agentchatmessage}
-
-| Options               | Tapez       | Description                                                                             |
-| --------------------- | ----------- | --------------------------------------------------------------------------------------- |
-| `message`             | `string`    | L'invite visible envoyée au chat                                                        |
-| `context`             | `string?`   | Contexte masqué ajouté (non affiché dans le chat UI)                                    |
-| `submit`              | `boolean?`  | true = soumission automatique, false = pré-remplissage uniquement                       |
-| `newTab`              | `boolean?`  | Créez un fil de discussion distinct pour cette invite                                   |
-| `background`          | `boolean?`  | Avec `newTab`, exécutez sans focaliser l'onglet et affichez l'exécution dans `RunsTray` |
-| `openSidebar`         | `boolean?`  | Définissez false pour soumettre/préremplir sans ouvrir la barre latérale                |
-| `projectSlug`         | `string?`   | Slug de projet facultatif pour un contexte structuré                                    |
-| `preset`              | `string?`   | Nom prédéfini facultatif pour les consommateurs en aval                                 |
-| `referenceImagePaths` | `string[]?` | Chemins d'image de référence facultatifs                                                |
-
-## État du contexte de discussion de l'agent (avancé) {#agent-chat-context-state}
-
-Les API à état de contexte sont une plomberie facultative pour UI qui nécessite une synchronisation bidirectionnelle avec
-puces de contexte mis en scène : rendu des éléments mis en scène actuels en dehors du compositeur,
-reflétant si un élément est déjà joint ou fournissant une information explicite
-supprimer/effacer les contrôles.
-
-Ne contactez pas ces assistants pour simplement "envoyer ceci à l'agent" ou
-flux « préremplir ce brouillon pour révision ». Utiliser `sendToAgentChat()` avec `context`
-et `submit` pour ceux-là.
-
-| API                               | Utiliser quand                                                                                               |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `useAgentChatContext()`           | Un composant React a besoin de la liste de contextes préparées en direct                                     |
-| `setAgentChatContextItem(item)`   | Le code impératif doit mettre en scène ou remplacer un élément de contexte à clé                             |
-| `listAgentChatContext()`          | Le code non-React nécessite un instantané unique du contexte intermédiaire                                   |
-| `removeAgentChatContextItem(key)` | UI devrait supprimer un élément de contexte intermédiaire par son `key` stable                               |
-| `clearAgentChatContext()`         | UI doit effacer tous les contextes intermédiaires, par exemple après une vue ou une réinitialisation de mode |
-| `refreshAgentChatContext()`       | Le code impératif doit relire le dernier instantané de contexte persistant                                   |
-
-`useAgentChatContext()` renvoie `{ items, set, remove, clear, refresh }`.
-
-## openAgentSettings(section?) {#openagentsettings}
-
-Utilisez `openAgentSettings()` lorsqu'une page de paramètres d'application ou une carte de configuration doit s'ouvrir
-onglet Paramètres de la barre latérale de l'agent. Transmettez un identifiant de section tel que `"llm"`, `"secrets"`,
-`"automations"`, `"voice"` ou `"limits"` pour ouvrir une section spécifique.
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-Préférez cette aide à l’envoi direct de `agent-panel:open-settings`.
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` est destiné au code impératif qui doit uniquement inspecter le
-éléments en cours de préparation une fois. `clearAgentChatContext()` est intentionnellement large ; utiliser
-`removeAgentChatContextItem(key)` lorsqu'une seule sélection a été modifiée.
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| Options       | Tapez      | Description                                                                  |
-| ------------- | ---------- | ---------------------------------------------------------------------------- |
-| `key`         | `string`   | Identifiant stable utilisé pour remplacer un nugget existant                 |
-| `title`       | `string`   | Étiquette courte affichée dans la puce du compositeur                        |
-| `context`     | `string`   | Contexte masqué inclus dans la prochaine invite soumise                      |
-| `openSidebar` | `boolean?` | La valeur par défaut est true ; passer false au contexte de scène en silence |
-
-## question à l'utilisateur (opt) {#ask-user-question}
-
-Posez à l'utilisateur une question à choix multiples à partir du code de l'application, affichez-la en ligne dans le
-panneau d'agents et **attendez leur réponse**. C'est le jumeau côté client du
-outil `ask-question` intégré à l'agent : il écrit un `GuidedQuestionPayload` dans le
-Clé d'état de l'application `"guided-questions"` (où le monté
-`GuidedQuestionFlow` le restitue) et révèle le panneau des agents, la question est donc
-visible. Contrairement à l'outil d'agent — dont la réponse revient à l'agent —
-`askUserQuestion()` **se résout avec la réponse à l'appelant**, donc le UI peut
-branchez-vous dessus.
-
-Utilisez-le lorsque le UI a besoin d'exactement une petite décision (2 à 4 options) avant lui
-lance le travail des agents — au lieu de créer un modal personnalisé. Atteignez le
-compositeur pour les détails de forme libre et un formulaire/popover pour la saisie multi-champs.
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-Chaque option est `{ label, value?, description?, preview?, recommended? }` ; `value`
-par défaut, `label` et `preview` affiche une petite maquette/extrait de code sous le
-options. La promesse se résout avec le `value` sélectionné (ou `value[]` lorsque
-`allowMultiple`), la chaîne de texte libre lorsque l'utilisateur sélectionne "Autre" ou `null`
-s'ils sautent, cela reste en attente jusqu'à ce que l'utilisateur réponde. Nécessite le panneau d'agent
-à monter (c'est dans chaque modèle).
-
-L'agent accède au même UI grâce à son outil `ask-question` : préférez laisser le
-l'agent demande quand _il_ atteint un véritable fork qu'il ne peut pas résoudre à partir du contexte ; utiliser
-`askUserQuestion()` lorsque le _UI_ doit lancer une action sur un choix.
-
-## Pont hôte d'application MCP {#mcp-app-host-bridge}
-
-Les itinéraires intégrés en tant qu'applications MCP doivent être URL en premier : charger l'artefact actuel à partir de
-Paramètres de chemin/requête, restituent la véritable route React ou un composant partagé ciblé,
-et utilisez le pont hôte uniquement pour le comportement appartenant à l'hôte. `@agent-native/core/client`
-exporte l'appel des routes intégrées des assistants :
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()` lit le dernier instantané de contexte d'hôte poussé ;
-`useMcpAppHostContext()` abonne les composants React aux modifications. La demande
-assistants (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
-`updateMcpAppModelContext`) renvoie `false` en dehors d'un cadre d'application MCP intégré, ou
-`Promise<boolean>` à l'intérieur d'un cadre. `sendToAgentChat()` utilise le même pont pour
-Invites soumises automatiquement à partir des itinéraires intégrés.
-
-Le pont lui-même : les messages `ui/*` JSON-RPC, les messages `agentNative.mcpHost.*`
-relais wrapper, transplantation ou rendu à image contrôlée, contexte hôte et
-Requêtes en mode d'affichage – appartient à
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## Suggestions dynamiques {#dynamic-suggestions}
-
-`<AgentSidebar>`, `<AgentPanel>` et `<AssistantChat>` fusionnent par défaut les `suggestions` statiques avec des suggestions contextuelles. Le framework lit `navigation`, `selection`, `pending-selection-context` et le URL actuel à partir de l'état de l'application tandis qu'une discussion vide est visible, puis propose des puces d'invite qui correspondent à l'écran actuel.
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-Définissez `dynamicSuggestions={false}` pour conserver uniquement les puces statiques. Transmettez `getSuggestions` lorsqu'une application souhaite des puces déterministes spécifiques à un domaine à partir du même contexte d'état d'application.
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-Hook React qui encapsule sendToAgentChat avec le suivi de l'état de chargement :
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-`isGenerating` devient vrai lorsque vous appelez `send()` et se réinitialise automatiquement sur faux lorsque l'agent termine la génération.
-
-## useDbSync(options ?) {#usedbsync}
-
-Hook React (anciennement `useFileWatcher`) qui écoute les modifications de la base de données sur SSE, revient à l'interrogation et invalide les caches de requêtes du framework qui maintiennent le UI aligné avec les écritures de l'agent :
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### Options {#usedbsync-options}
-
-| Option             | Tapez              | Description                                                                                                     |
-| ------------------ | ------------------ | --------------------------------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | Client de requête React pour l'invalidation du cache                                                            |
-| `queryKeys`        | `string[]?`        | Obsolète et ignoré ; conservé pour les anciens sites d'appel                                                    |
-| `pollUrl`          | `string?`          | Interroger le point de terminaison URL. Par défaut : `"/_agent-native/poll"`                                    |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                          |
-| `interval`         | `number?`          | Intervalle d'interrogation en ms. Par défaut : `2000`                                                           |
-| `fallbackInterval` | `number?`          | Intervalle d'interrogation de secours lorsque SSE n'est pas disponible. Par défaut : `15000`                    |
-| `pauseWhenHidden`  | `boolean?`         | Suspendre l'interrogation lorsque l'onglet du navigateur est masqué. Par défaut : `true`                        |
-| `ignoreSource`     | `string?`          | Source de requête par onglet à ignorer afin qu'un onglet ne soit pas récupéré à partir de ses propres écritures |
-| `onEvent`          | `(data) => void`   | Rappel facultatif lorsque SSE/polling reçoit un événement de changement                                         |
-
-Pour les CRUD normaux, préférez les `useActionQuery` et `useActionMutation` ; la mutation actions émet `source: "action"` et ces hooks sont récupérés automatiquement.
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-Le framework utilise des versions modifiées pour synchroniser les caches de requêtes React avec les modifications apportées par les agents en arrière-plan, les tâches cron ou d'autres utilisateurs.
-
-Lorsqu'une mutation de base de données côté serveur se produit, le serveur enregistre un événement de modification avec une clé `source` spécifique. L'écouteur `useDbSync` du client reçoit ces événements et augmente le compteur de version de modification locale pour cette source. En intégrant le compteur de versions dans vos clés de requête React, les requêtes sont automatiquement récupérées chaque fois que le backend informe le client d'une nouvelle activité.
-
-- **`useChangeVersion(source: string): number`** — renvoie un compteur qui s'incrémente chaque fois que le `source` spécifié est muté.
-- **`useChangeVersions(sources: readonly string[]): number`** : renvoie la somme des compteurs de versions pour plusieurs sources.
-
-### Exemple : Synchroniser une requête brute avec la base de données
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### Modèles de latence et comportement d'invalidation
-
-- **Mutations initiées par UI :** Lorsque vous exécutez une action à partir du UI à l'aide de `useActionMutation`, la mutation déclenche immédiatement un événement local avec `source: "action"` en cas de succès. Cela déclenche une **récupération instantanée et optimiste** de toutes les clés de requête en fonction de cette action, évitant ainsi tout retard visuel.
-- **Mutations en arrière-plan ou par agent :** Lorsque l'agent IA, un webhook ou un travailleur en arrière-plan mute les données, la mise à jour est diffusée au client. Le `useDbSync` du client capture cela instantanément via SSE (événements envoyés par le serveur) ou revient au **tic d'interrogation de 2 secondes**. La version de la clé de requête est ensuite modifiée, déclenchant une récupération en arrière-plan.
-
-<Diagram id="doc-block-sbx9k7" title={"Deux chemins pour une récupération"} summary={"Une mutation locale invalide instantanément ses propres caches ; une écriture à distance atteint cet onglet via SSE, ou la coche d'interrogation comme solution de secours."}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">Cet onglet</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">Agent · webhook · autre onglet</span
-      ><strong>Écriture distante</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...entrées) {#cn}
-
-Utilitaire de fusion des noms de classes (clsx + tailwind-merge) :
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/fr-FR/drop-in-agent.mdx b/packages/core/docs/content/locales/fr-FR/drop-in-agent.mdx
index 9abe9ef9cd..3e4960d658 100644
--- a/packages/core/docs/content/locales/fr-FR/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/fr-FR/drop-in-agent.mdx
@@ -225,7 +225,7 @@ suivi. Cela ne détourne tout simplement pas le focus de l'état actuel de la ba
 
 Lorsque le même itinéraire est intégré en tant qu'application MCP, soumis
 Les appels `sendToAgentChat()` sont transférés vers le chat hôte lorsque cela est pris en charge ; voir
-[Client](/docs/client#sendtoagentchat) pour le comportement du pont de l'application MCP.
+[Chat de l’Agent](/docs/client-agent-chat#sendtoagentchat) pour le comportement du pont de l'application MCP.
 
 Si vous souhaitez un état de chargement, utilisez le hook `useSendToAgentChat()` : il renvoie à la fois `send` et `isGenerating` :
 
diff --git a/packages/core/docs/content/locales/fr-FR/notifications.mdx b/packages/core/docs/content/locales/fr-FR/notifications.mdx
index 74e48314e1..5af6af4b64 100644
--- a/packages/core/docs/content/locales/fr-FR/notifications.mdx
+++ b/packages/core/docs/content/locales/fr-FR/notifications.mdx
@@ -363,7 +363,7 @@ Les automatisations peuvent enchaîner cela – par ex. _"si une notification
 ## Comment ça marche {#internals}
 
 - **Portée du propriétaire** — chaque ligne a une colonne `owner` ; chaque requête est filtrée dessus ; chaque itinéraire utilise l'e-mail de la session authentifiée. Les utilisateurs ne voient jamais les notifications des autres.
-- **Intégration de sondage** — chaque mutation appelle `recordChange()` afin que les modèles utilisant [`useDbSync`](/docs/client) s'invalident automatiquement sans aucun câblage supplémentaire.
+- **Intégration de sondage** — chaque mutation appelle `recordChange()` afin que les modèles utilisant [`useDbSync`](/docs/client-data#usedbsync) s'invalident automatiquement sans aucun câblage supplémentaire.
 - **Distribution au mieux** : les erreurs de canal sont détectées et enregistrées ; un canal défaillant ne bloque pas les autres ni l'écriture dans la boîte de réception.
 - **Fire-and-forget** — `notify()` revient une fois l'écriture de la boîte de réception terminée ; les canaux personnalisés s'exécutent en arrière-plan.
 
diff --git a/packages/core/docs/content/locales/fr-FR/progress.mdx b/packages/core/docs/content/locales/fr-FR/progress.mdx
index 6d32f1f285..7ef5c05d4d 100644
--- a/packages/core/docs/content/locales/fr-FR/progress.mdx
+++ b/packages/core/docs/content/locales/fr-FR/progress.mdx
@@ -233,7 +233,7 @@ Notifier me that run {{runId}} has failed.
 ## Comment ça marche {#internals}
 
 - **Portée du propriétaire** : chaque ligne comporte une colonne `owner` ; chaque requête filtre dessus. Les utilisateurs voient uniquement leurs propres courses.
-- **Intégration de sondage** — chaque mutation appelle `recordChange()` afin que les modèles utilisant [`useDbSync`](/docs/client) s'invalident automatiquement sans aucun câblage supplémentaire.
+- **Intégration de sondage** — chaque mutation appelle `recordChange()` afin que les modèles utilisant [`useDbSync`](/docs/client-data#usedbsync) s'invalident automatiquement sans aucun câblage supplémentaire.
 - **Nom de la table** — le framework dispose également d'une table `agent_runs` pour le suivi interne du cycle de vie des tours de discussion des agents. La primitive de progression utilise `progress_runs` pour séparer les deux préoccupations.
 - **Pourcentage de serrage** : les valeurs sont limitées à `[0, 100]` et arrondies à un nombre entier lors de l'écriture.
 
@@ -241,4 +241,4 @@ Notifier me that run {{runId}} has failed.
 
 - [**Notifications**](/docs/notifications) : associez-le à `manage-progress` (`action=complete`) pour indiquer à l'utilisateur la fin du travail
 - [**Automations**](/docs/automations) – fonctionnement lent du chien de garde via `run.progress.updated`
-- [**Client**](/docs/client) — `useDbSync` pour l'invalidation du cache en temps réel
+- [**Données et synchronisation**](/docs/client-data) — `useDbSync` pour l'invalidation du cache en temps réel
diff --git a/packages/core/docs/content/locales/fr-FR/real-time-collaboration.mdx b/packages/core/docs/content/locales/fr-FR/real-time-collaboration.mdx
index 182ff5a3c2..2d496bd3a1 100644
--- a/packages/core/docs/content/locales/fr-FR/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/fr-FR/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ modèle de collaboration agent-natif.
 Modifier aux côtés de l'agent, c'est comme travailler dans un éditeur collaboratif avec
 un collègue à la fois instantané et infatigable :
 
-Si vous avez simplement besoin d'actualiser le UI lorsque l'agent ou un autre utilisateur écrit sur SQL, vous n'avez pas besoin de tout cela : utilisez [`useDbSync`](/docs/client). Cette page est destinée à la co-édition au niveau des caractères d'un seul document en texte enrichi (curseurs partagés, fusion sans conflit). Les deux utilisent le même canal `/_agent-native/poll`.
+Si vous avez simplement besoin d'actualiser le UI lorsque l'agent ou un autre utilisateur écrit sur SQL, vous n'avez pas besoin de tout cela : utilisez [`useDbSync`](/docs/client-data#usedbsync). Cette page est destinée à la co-édition au niveau des caractères d'un seul document en texte enrichi (curseurs partagés, fusion sans conflit). Les deux utilisent le même canal `/_agent-native/poll`.
 
 Ceci s'appuie sur trois technologies éprouvées : **Yjs** (CRDT pour une fusion sans conflit), **TipTap** (éditeur de texte enrichi) et **synchronisation basée sur des sondages** (fonctionne dans tous les environnements de déploiement, y compris sans serveur et en périphérie).
 
@@ -777,7 +777,7 @@ couches au-dessus du même état de conscience.
 
 ## Documents associés {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) — le `useDbSync` + `useChangeVersion`
+- [Synchronisation interne](/docs/client-sync-internals) — le `useDbSync` + `useChangeVersion`
   système qui fournit la réconciliation de l'éditeur de conduite de bosses `updatedAt`.
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   et `assertAccess` pour la collaboration limitée à une ressource.
diff --git a/packages/core/docs/content/locales/fr-FR/routing.mdx b/packages/core/docs/content/locales/fr-FR/routing.mdx
deleted file mode 100644
index 2b3ef4bef0..0000000000
--- a/packages/core/docs/content/locales/fr-FR/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "Routage"
-description: "Routage basé sur des fichiers pour les applications natives d'agent avec React Router v8 : pages, paramètres dynamiques et navigation."
----
-
-# Routage
-
-Les applications natives d'agent utilisent le **routeur React v8** avec un routage basé sur des fichiers via `flatRoutes()` à partir de `@react-router/fs-routes`. Chaque fichier de `app/routes/` devient un URL. Les modèles utilisent la convention de notation par points : des points séparent les segments URL à l'intérieur d'un seul nom de fichier.
-
-## Routage basé sur des fichiers {#file-based-routing}
-
-### Fichier → Mappage URL
-
-| Fichier               | URL                  | Remarques                                       |
-| --------------------- | -------------------- | ----------------------------------------------- |
-| `_index.tsx`          | `/`                  | Indexer l'itinéraire                            |
-| `settings.tsx`        | `/settings`          | Page simple                                     |
-| `inbox.$threadId.tsx` | `/inbox/:threadId`   | Point = `/`, `$` = paramètre dynamique          |
-| `_app.tsx`            | (pas de segment URL) | Mise en page sans chemin – préfixe avec `_`     |
-| `inbox/route.tsx`     | `/inbox`             | Formulaire de dossier — `route.tsx` est l'index |
-
-Préfixez un segment avec `$` pour un paramètre dynamique. Préfixez `_` pour en faire un itinéraire de tracé sans chemin (pas de segment URL). Les modèles utilisent `flatRoutes()` — le fichier de notation par points ci-dessus est principal ; le formulaire de dossier imbriqué `inbox/route.tsx` fonctionne également.
-
-<Diagram id="doc-block-chuvll" title="La mise en page sans chemin enveloppe les pages" summary={"Une disposition _app.tsx (pas de segment URL) restitue le shell partagé une fois ; les pages correspondantes s'affichent dans son <Outlet/>, de sorte que la barre latérale de l'agent ne remonte jamais lors de la navigation."}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >layout sans chemin · shell persistant + barre agent</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## Ajout d'une nouvelle page {#adding-a-page}
-
-Créez le fichier et exportez un composant par défaut :
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-C'est tout – Le routeur React le récupère automatiquement, aucune inscription n'est nécessaire.
-
-## Paramètres dynamiques {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## Navigation {#navigation}
-
-Utilisez `<Link>` pour la navigation côté client et `useNavigate()` pour la navigation par programmation :
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## Quelle est la prochaine étape
-
-- [**Client**](/docs/client) — les hooks et utilitaires de navigateur natifs de l'agent
-- [**Server**](/docs/server) — routes de serveur basées sur des fichiers et espace de noms `/_agent-native/`
diff --git a/packages/core/docs/content/locales/hi-IN/client-advanced.mdx b/packages/core/docs/content/locales/hi-IN/client-advanced.mdx
new file mode 100644
index 0000000000..885237afd9
--- /dev/null
+++ b/packages/core/docs/content/locales/hi-IN/client-advanced.mdx
@@ -0,0 +1,192 @@
+---
+title: "उन्नत"
+description: "app/ के लोअर-लेवल प्रिमिटिव और एस्केप हैच: सीधी application-state एक्सेस, बैकग्राउंड चैट सेंड, कस्टम सुझाव चिप्स, और MCP App होस्ट ब्रिज।"
+---
+
+# उन्नत
+
+अवलोकन, डेटा और सिंक, एजेंट चैट, और रूटिंग सामान्य स्थिति को कवर करते हैं: वे हुक और हेल्पर जिनकी अधिकांश पेजों को आवश्यकता होती है। यह पेज उनके नीचे के लोअर-लेवल प्रिमिटिव और संकीर्ण एस्केप हैच को कवर करता है। अधिकांश ऐप्स इन्हें कभी सीधे नहीं छूते। जब आप डिफ़ॉल्ट हुक द्वारा समर्थित से अधिक कस्टम कुछ बना रहे हों, जैसे कोई कस्टम सिलेक्शन सिंक या कोई एम्बेडेड MCP App, तो इनमें से किसी एक तक पहुंचें। किसी कस्टम key के साथ कच्चे `useQuery` को सिंक करने के लिए, इसके बजाय [सिंक इंटरनल्स](/docs/client-sync-internals) देखें।
+
+## एप्लिकेशन स्थिति {#application-state}
+
+`application_state` एक SQL-समर्थित key/value स्टोर है जिसे एजेंट यह जानने के लिए पढ़ता है कि UI वर्तमान में क्या देख रहा है, जिसमें नेविगेशन, सिलेक्शन, और अन्य फ़ोकस्ड-ऑब्जेक्ट कॉन्टेक्स्ट शामिल है (देखें [Context Awareness](/docs/context-awareness))। `useAgentRouteState` और `useSemanticNavigationState` (Context Awareness में भी कवर किया गया) सामान्य नेविगेशन केस के लिए इन्हें पहले से रैप करते हैं। जब आप कुछ ऐसा सिंक कर रहे हों जिसे वे कवर नहीं करते, जैसे कोई कस्टम सिलेक्शन, या किसी घटक के रेंडर के बाहर से लिख रहे हों, तो सीधे नीचे दिए प्रिमिटिव तक पहुंचें।
+
+### readClientAppState {#read-client-app-state}
+
+किसी key के लिए वर्तमान वैल्यू पढ़ें। यह उस key के लिए आख़िरी बार लिखी गई चीज़ पर, या यदि key कभी नहीं लिखा गया है तो `null` पर रिज़ॉल्व होता है।
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+किसी key के लिए एक वैल्यू लिखें। नीचे दिए `setClientAppState` के विपरीत, यह हमेशा लिखता है, भले ही आप `null` पास करें। `undefined` पास करना throw करता है, क्योंकि `undefined` वैध JSON नहीं है। किसी key को साफ़ करने के लिए `setClientAppState(key, undefined)` या `deleteClientAppState()` का उपयोग करें।
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+वह सुविधाजनक रैपर जिसका उपयोग अधिकांश UI कोड को करना चाहिए: वैल्यू लिखता है, या जब आप `null`/`undefined` पास करते हैं तो key को हटा देता है। जब तक किसी कॉल साइट को वास्तव में "हमेशा लिखो, कभी न मिटाओ" की आवश्यकता न हो, `writeClientAppState` के बजाय इसका उपयोग करें।
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+किसी key को पूरी तरह से हटाएं।
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+एक ही रिक्वेस्ट में कई keys पढ़ें। `{ values, missing }` लौटाता है। `values` में हर उस key के लिए एक एंट्री होती है जिसके लिए सर्वर के पास एक पंक्ति है, जिसमें वह key भी शामिल है जो स्पष्ट रूप से `null` के रूप में लिखा गया था। `missing` उन keys को सूचीबद्ध करता है जो कभी बिल्कुल नहीं लिखे गए। इसी तरह "कभी नहीं लिखा गया" "null के रूप में लिखा गया" से अलग रहता है।
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+100 से अधिक keys वाली रिक्वेस्ट स्वचालित रूप से चंक की जाती हैं। `readClientAppState()` खुद इसी पर बनाया गया है: एक ही टिक में जारी किए गए कॉल पीछे से एक ही रिक्वेस्ट में समेकित किए जाते हैं, इसलिए एक ही रेंडर पास में इसे कई बार कॉल करने की लागत हर कॉल पर एक राउंड ट्रिप नहीं, बल्कि एक राउंड ट्रिप होती है।
+
+### विकल्प {#application-state-options}
+
+`signal` ऊपर दिए सभी पांच फ़ंक्शन द्वारा स्वीकार किया जाता है, किसी इन-फ़्लाइट कॉल को कैंसल करने के लिए। `requestSource` और `keepalive` केवल तीन राइट फ़ंक्शन पर लागू होते हैं, क्योंकि किसी रीड के लिए उनका कोई मतलब नहीं है।
+
+| विकल्प          | प्रकार         | किस पर लागू होता है                                                | विवरण                                                                                                          |
+| --------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | राइट को एक id के साथ टैग करता है ताकि कोई मैचिंग `useDbSync({ ignoreSource })` इसे रीफ़ेच करने से स्किप कर सके |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | रिक्वेस्ट को पेज अनलोड से बचने देता है। सिलेक्शन साफ़ करने जैसे क्लीनअप राइट्स के लिए उपयोग करें               |
+| `signal`        | `AbortSignal?` | सभी पांच फ़ंक्शन                                                   | रिक्वेस्ट को कैंसल करता है                                                                                     |
+
+### फ़ेलियर बिहेवियर {#failure-behavior}
+
+सभी पांच फ़ंक्शन किसी फेल रिक्वेस्ट, नॉन-2xx रिस्पॉन्स, या पार्स न हो सकने वाले बॉडी पर throw करते हैं। थ्रोन `Error` में एक `.status` प्रॉपर्टी होती है जब सर्वर ने रिस्पॉन्स दिया हो, इसलिए ज़रूरत पड़ने पर कॉलर HTTP स्टेटस पर ब्रांच कर सकता है। किसी कॉल को `try`/`catch` में रैप करें, या इसे किसी एरर बाउंड्री तक प्रोपेगेट होने दें, किसी अन्य नेटवर्क कॉल की तरह ही।
+
+### TAB_ID क्या है {#tab-id}
+
+`requestSource` आमतौर पर `TAB_ID` पर सेट किया जाता है, हर टेम्पलेट द्वारा `app/lib/tab-id.ts` से एक्सपोर्ट किया गया एक सादा कॉन्स्टेंट: एक छोटी रैंडम स्ट्रिंग जो किसी टैब के जीवनकाल के लिए एक जैसी रहती है और टैब्स के बीच अलग होती है। किसी राइट पर `requestSource: TAB_ID` को रीड साइड पर `useDbSync({ ignoreSource: TAB_ID })` के साथ जोड़ना ही यह है कि कोई टैब अपनी खुद की राइट को रीफ़ेच करने से कैसे बचता है जबकि सभी के प्रति फिर भी रिएक्ट करता है। पूरे वॉकथ्रू के लिए [Context Awareness](/docs/context-awareness#jitter-prevention) देखें।
+
+## sendToAgentChat: बैकग्राउंड सेंड {#background-send}
+
+`background: true` का उपयोग तब करें जब किसी UI एक्शन को साइडबार खोले या फोकस
+किए बिना वास्तविक एजेंट कार्य शुरू करना चाहिए। यह अभी भी एक सामान्य चैट थ्रेड/रन
+बनाता है, एजेंट के टूल/actions/कॉन्टेक्स्ट का उपयोग करता है, और काम को रन ट्रे के
+माध्यम से देखने योग्य रखता है। यह कोई कच्चा वन-शॉट मॉडल कॉल नहीं है।
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` को `newTab` के साथ जोड़े जाने का इरादा है ताकि छिपा हुआ काम उपयोगकर्ता
+की सक्रिय बातचीत को ओवरराइट न करे। यदि UI को फॉलो-अप स्टेटस को को-रिलेट करने या
+बाद में रन में डीप-लिंक करने की आवश्यकता है तो लौटाए गए `tabId` का उपयोग करें।
+
+[एजेंट चैट](/docs/client-agent-chat#agentchatmessage) में कवर किए गए के अलावा, कुछ और `AgentChatMessage` विकल्प मौजूद हैं, मुख्य रूप से एम्बेडेड या डाउनस्ट्रीम-इंटीग्रेशन केस के लिए:
+
+| विकल्प                | प्रकार      | विवरण                                                                   |
+| --------------------- | ----------- | ----------------------------------------------------------------------- |
+| `background`          | `boolean?`  | `newTab` के साथ, टैब को फोकस किए बिना चलाएं और `RunsTray` में रन दिखाएं |
+| `projectSlug`         | `string?`   | संरचित कॉन्टेक्स्ट के लिए वैकल्पिक प्रोजेक्ट स्लग                       |
+| `preset`              | `string?`   | डाउनस्ट्रीम उपभोक्ताओं के लिए वैकल्पिक प्रीसेट नाम                      |
+| `referenceImagePaths` | `string[]?` | वैकल्पिक संदर्भ इमेज पथ                                                 |
+
+## MCP App होस्ट ब्रिज {#mcp-app-host-bridge}
+
+MCP Apps के रूप में एम्बेड किए गए रूट्स को URL-फ़र्स्ट होना चाहिए: पथ/क्वेरी पैरामीटर से
+वर्तमान आर्टिफ़ैक्ट लोड करें, वास्तविक React रूट या किसी केंद्रित साझा घटक को रेंडर करें,
+और होस्ट ब्रिज का उपयोग केवल होस्ट-ओनड बिहेवियर के लिए करें। `@agent-native/core/client`
+वे हेल्पर एक्सपोर्ट करता है जिन्हें एम्बेडेड रूट्स कॉल करते हैं:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` नवीनतम पुश किए गए होस्ट कॉन्टेक्स्ट स्नैपशॉट को पढ़ता है।
+`useMcpAppHostContext()` React घटकों को बदलावों के लिए सब्सक्राइब करता है। रिक्वेस्ट
+हेल्पर्स (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) किसी एम्बेडेड MCP App फ्रेम के बाहर `false`, या
+किसी फ्रेम के भीतर `Promise<boolean>` लौटाते हैं।
+
+`sendToAgentChat()` (देखें [एजेंट चैट](/docs/client-agent-chat#sendtoagentchat)) ऑटो-सबमिटेड प्रॉम्प्ट्स के लिए एम्बेडेड रूट्स से इसी ब्रिज का उपयोग करता है। `embedApp()` से बनाए गए किसी MCP App एम्बेड के भीतर, ऑटो-सबमिटेड मैसेज (`submit` छोड़ा गया या `true`) ब्रिज को फ़ॉरवर्ड किए जाते हैं, जो कंटेनिंग होस्ट को छिपा हुआ कॉन्टेक्स्ट जोड़ने और दिखने वाला उपयोगकर्ता टर्न भेजने के लिए कहता है। `context` उपयोगकर्ता-सामना वाली चैट के रूप में पोस्ट किए बिना मॉडल-दृश्यमान रहता है। `submit: false` लोकल प्रीफिल/रिव्यू बिहेवियर को बनाए रखता है क्योंकि MCP Apps एक स्टैंडर्ड ड्राफ्ट-प्रीफिल API परिभाषित नहीं करते। आंतरिक रूप से यह सबमिटेड-चैट पथ है जो कभी-कभी `agentNative.submitChat` के रूप में सामने आता है। ऐप कोड को उस इवेंट को सीधे पोस्ट करने के बजाय फिर भी `sendToAgentChat()` को कॉल करना चाहिए।
+
+ब्रिज खुद, `ui/*` JSON-RPC मैसेज, `agentNative.mcpHost.*`
+रैपर रिले, ट्रांसप्लांट बनाम कंट्रोल्ड-फ़्रेम रेंडरिंग, होस्ट कॉन्टेक्स्ट, और
+डिस्प्ले-मोड रिक्वेस्ट का स्वामित्व
+[External Agents](/docs/external-agents#mcp-app-bridge) के पास है। पूरे प्रोटोकॉल के लिए [MCP Apps](/docs/mcp-apps) देखें।
+
+## कस्टम सुझाव चिप्स {#custom-suggestions}
+
+`<AgentSidebar>` का `dynamicSuggestions` (देखें [एजेंट चैट](/docs/client-agent-chat#dynamic-suggestions)) पहले से ही स्टैटिक `suggestions` को फ्रेमवर्क के अपने कॉन्टेक्स्ट-अवेयर हेयुरिस्टिक के साथ मर्ज करता है। जब कोई ऐप फ्रेमवर्क के डिफ़ॉल्ट हेयुरिस्टिक के बजाय उसी `application_state` कॉन्टेक्स्ट से कंप्यूट किए गए नियतात्मक, डोमेन-विशिष्ट चिप्स चाहता है तो इसके बजाय `getSuggestions` पास करें।
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` उसी `navigation`/`selection`/`pending-selection-context` स्नैपशॉट को प्राप्त करता है जिसे बिल्ट-इन हेयुरिस्टिक पढ़ता है, इसलिए कोई कस्टम इम्प्लीमेंटेशन उसी स्टेट के प्रति रिएक्ट कर सकता है जिसके प्रति डिफ़ॉल्ट करता है, बस सामान्य नियमों के बजाय ऐप-विशिष्ट नियमों के साथ।
+
+## आगे क्या
+
+- [**अवलोकन**](/docs/client-overview) - `app/` और `public/` डायरेक्टरी लेआउट जिसमें ये प्रिमिटिव रहते हैं
+- [**डेटा और सिंक**](/docs/client-data) - डिफ़ॉल्ट action हुक और `useDbSync` जिनका उपयोग अधिकांश पेजों को इसके बजाय करना चाहिए
+- [**सिंक इंटरनल्स**](/docs/client-sync-internals) - `useChangeVersion`/`useChangeVersions` और वे दो लेटेंसी पथ जो कोई रीफ़ेच ले सकता है
+- [**एजेंट चैट**](/docs/client-agent-chat) - डिफ़ॉल्ट `sendToAgentChat`/`askUserQuestion` हेल्पर जिनका उपयोग अधिकांश UI को इसके बजाय करना चाहिए, और स्टेज्ड एजेंट चैट कॉन्टेक्स्ट-स्टेट APIs
+- [**एंट्री पॉइंट्स**](/docs/client-entry-points) - `app/entry.client.tsx`/`app/entry.server.tsx` और SSR स्ट्रीमिंग कस्टमाइज़ेशन
+- [**Context Awareness**](/docs/context-awareness) - `application_state` पर बना `navigation`/`selection` सिमेंटिक्स, और `TAB_ID`/जिटर-प्रिवेंशन वॉकथ्रू
+- [**Generative UI**](/docs/generative-ui) - `askUserQuestion` से आगे रिचर इन-चैट कंट्रोल्स
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) - पूरा MCP App होस्ट ब्रिज इंटरनल्स
diff --git a/packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx b/packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx
new file mode 100644
index 0000000000..a94d6119d7
--- /dev/null
+++ b/packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx
@@ -0,0 +1,314 @@
+---
+title: "एजेंट चैट"
+description: "एजेंट चैट में क्लाइंट-साइड एंट्री पॉइंट: sendToAgentChat, openAgentSettings, askUserQuestion, डायनामिक सुझाव, useAgentChatGenerating, और स्टेज्ड एजेंट चैट कॉन्टेक्स्ट स्थिति।"
+---
+
+# एजेंट चैट
+
+आपके एप्लिकेशन का क्लाइंट क्लाइंट हेल्पर्स के एक छोटे सेट के माध्यम से एजेंट से बात कर सकता है। यह प्रॉम्प्ट भेजना, छिपा हुआ कॉन्टेक्स्ट स्टेज करना, उपयोगकर्ता से एक ब्लॉकिंग प्रश्न पूछना, और एजेंट पैनल खोलना कवर करता है।
+
+नीचे दिए गए उदाहरण में, एक **Draft response** बटन एजेंट को उपयोगकर्ता से एक प्रश्न पूछने के लिए प्रॉम्प्ट करता है। एक बार उपयोगकर्ता उत्तर दे देता है, एजेंट वर्तमान पेज कॉन्टेक्स्ट और उपयोगकर्ता के उत्तर को ध्यान में रखते हुए रिस्पॉन्स ड्राफ्ट करने लगता है।
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="Dispatch ऐप का स्क्रीनशॉट जो रन हिस्ट्री साइडबार दिखा रहा है"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Dispatch की रन हिस्ट्री साइडबार।"
+/>
+
+## यह कैसे काम करता है
+
+Agent-Native द्वारा प्रदान किए गए क्लाइंट हेल्पर मेथड का उपयोग करके, आपका UI एजेंट को उपयोगकर्ता के साथ विभिन्न तरीकों से इंटरैक्ट करने के लिए प्रॉम्प्ट कर सकता है। नीचे दिया गया डायग्राम दिखाता है कि उपयोगकर्ता द्वारा क्लिक किए गए "Draft response" बटन एजेंट को रिस्पॉन्स जनरेट करने से पहले उपयोगकर्ता के साथ इंटरैक्ट करने के लिए कैसे प्रॉम्प्ट कर सकता है।
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="'who owns each step' शीर्षक वाला सीक्वेंस डायग्राम, तीन लाइफलाइन: App Code, UI, और Agent। 'draft response' पर क्लिक askUserQuestion() ट्रिगर करता है (एजेंट पैनल में इनलाइन रेंडर होता है)। जवाब के बाद sendDraftRequest() draft-ticket-reply को कॉल करता है और UI कंपोज़र को रिप्लाई लौटाता है।"
+  align="full"
+  width={600}
+  caption="'Draft response' बटन फ्लो को विज़ुअलाइज़ करने वाला सीक्वेंस डायग्राम।"
+/>
+
+उपयोगकर्ता का अनुभव इस प्रकार है:
+
+1. उपयोगकर्ता **Draft response** बटन पर क्लिक करता है, जिससे `askUserQuestion()` फ़ंक्शन कॉल होता है। प्रश्न का उत्तर एजेंट पैनल में इनलाइन दिया जाता है।
+
+1. उपयोगकर्ता **Offer a refund** चुनता है, जिससे `sendDraftRequest()` प्रॉम्प्ट और टिकट कॉन्टेक्स्ट को एजेंट को भेजता है।
+
+1. एजेंट `draft-ticket-reply` [action](/docs/actions) को कॉल करता है, और ड्राफ्ट रिप्लाई रिप्लाई कंपोज़र में दिखाई देता है।
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "प्रश्न, इसके विकल्प, और इसे कैसे व्यवहार करना चाहिए।",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "पूरा प्रश्न। स्पष्ट, विशिष्ट, प्रश्न चिह्न के साथ समाप्त होता है।",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'बहुत छोटा चिप/शीर्षक, लगभग 12 अक्षर, जैसे `"Response"`।',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2-4 अलग-अलग विकल्प। हर एक `{ label, value?, description?, preview?, recommended? }` है। `value` डिफ़ॉल्ट रूप से `label` होता है।",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            'एक फ़्री-टेक्स्ट "Other" विकल्प जोड़ता है जिसमें रेप टाइप कर सकता है।',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "सिंगल-सिलेक्ट के बजाय मल्टी-सिलेक्ट।",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description: "एप्लिकेशन-स्टेट key जिसे एजेंट पैनल पोल करता है।",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'चुना गया `value` (या `allowMultiple` होने पर `value[]`), रेप का टाइप किया गया "Other" टेक्स्ट, या यदि वे स्किप करते हैं तो `null`। उनके उत्तर देने तक पेंडिंग रहता है। एजेंट पैनल को माउंट होना ज़रूरी है, जो हर टेम्पलेट में होता है।',
+  }}
+/>
+
+यह फ़ंक्शन ऐप कोड से उपयोगकर्ता से एक बहुविकल्पीय प्रश्न पूछता है, इसे एजेंट पैनल में इनलाइन रेंडर करता है, और उनके उत्तर की प्रतीक्षा करता है। इसका उपयोग तब करें जब UI को एजेंट का काम शुरू करने से पहले दो से चार विकल्पों के साथ एक छोटे निर्णय की आवश्यकता हो, कस्टम मॉडल बनाने के बजाय।
+
+नीचे दिए गए उदाहरण में, किसी टिकट पेज पर "Draft Response" बटन कुछ भी एजेंट को भेजने से पहले रेप से पूछता है कि वे कैसे जवाब देना चाहेंगे:
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "एक `[isGenerating, send]` ट्यूपल। `isGenerating` तब `true` होता है जब से `send()` कॉल किया जाता है जब तक एजेंट चैट रन यह रिपोर्ट नहीं कर देता कि वह रुक गया है। `send(opts)` का सिग्नेचर `sendToAgentChat()` जैसा ही है, और यह वह tab id लौटाता है जिसे उसने डिस्पैच किया।",
+  }}
+/>
+
+यह React हुक `sendToAgentChat()` को लोडिंग स्थिति ट्रैकिंग के साथ रैप करता है।
+
+1. पहला आर्ग्युमेंट, `isGenerating`, जब आप इसे कॉल करते हैं तो true हो जाता है, फिर जब एजेंट जनरेट करना समाप्त कर देता है तो false पर रीसेट हो जाता है।
+
+2. दूसरा आर्ग्युमेंट, `send()`, `sendToAgentChat()` फ़ंक्शन को दर्शाता है।
+
+`isGenerating` केवल तब रीसेट होता है जब कोई रन वास्तव में शुरू होता है और रिपोर्ट करता है कि वह रुक गया है। एक `submit: false` कॉल एक रन शुरू किए बिना एक ड्राफ्ट को प्रीफिल करता है, इसलिए एक के बाद `isGenerating` हमेशा के लिए `true` रहता है। इस हुक का उपयोग केवल `submit: true` सेंड के लिए करें; प्रीफिल-ओनली के लिए सीधे `sendToAgentChat()` को कॉल करें।
+
+ऊपर दिए गए `askUserQuestion()` उदाहरण के साथ इसे जोड़ने पर बटन का हैंडलर पूरा हो जाता है:
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="Draft Response हैंडलर को पूरा करना"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "लोडिंग स्थिति + सेंड, एक साथ",
+      note: "`useAgentChatGenerating()` एक बेयर `sendToAgentChat()` कॉल जैसा ही ट्यूपल आकार लौटाता है, लेकिन `isDrafting` जोड़ता है ताकि बटन रिक्वेस्ट के इन-फ़्लाइट रहते हुए खुद को डिसेबल कर सके।",
+    },
+    {
+      lines: "10-17",
+      label: "ask स्टेप का पुनः उपयोग",
+      note: "यह ऊपर दिए गए सेक्शन का वही `askUserQuestion()` कॉल है, अब बटन के अपने हैंडलर के भीतर।",
+    },
+    {
+      lines: "18",
+      label: "उत्तर का उपयोग करने से पहले नैरो करें",
+      note: "रिटर्न टाइप हमेशा `allowMultiple` से `string[]` की अनुमति देता है, इसलिए यह जांच आवश्यक है भले ही यह कॉल इसे कभी सेट नहीं करती।",
+    },
+    {
+      lines: "20-25",
+      label: "चुनाव को एक वाक्य बनाएं",
+      note: "चुने गए value, या रेप के अपने टाइप किए गए टेक्स्ट को, ऐसे वाक्यांश में मैप करता है जिसे नीचे दिया प्रॉम्प्ट स्वाभाविक रूप से पढ़ता है।",
+    },
+    {
+      lines: "27-32",
+      label: "action और इंटेंट को नाम दें",
+      note: "मैसेज एजेंट को बताता है कि किस action को कॉल करना है (`draft-ticket-reply`) और उसे याद दिलाता है कि रिप्लाई बिल्कुल न भेजे। `openSidebar: true` सुनिश्चित करता है कि ड्राफ्ट रिप्लाई दिखाई दे भले ही साइडबार बंद हो।",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting बटन को चलाता है",
+      note: "केवल `sendDraftRequest()` के इन-फ़्लाइट रहते हुए डिसेबल और रीलेबल किया जाता है। जब `askUserQuestion()` रेप का इंतज़ार कर रहा हो तो बटन क्लिक करने योग्य बना रहता है, क्योंकि यह `sendDraftRequest()` कॉल होने से पहले होता है।",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+`postMessage` के माध्यम से एजेंट चैट पर एक मैसेज भेजें। यह वह लोअर-लेवल प्रिमिटिव है जिसे ऊपर दिया `useAgentChatGenerating()` रैप करता है, यह उपयोगी है जब किसी UI इंटरैक्शन को खुद की लोडिंग-स्टेट ट्रैकिंग की आवश्यकता नहीं होती। अतिरिक्त विवरण के लिए `context` पास करें जो मैसेज खुद नहीं बताता। यह उसी दिखने वाले मैसेज में जुड़ जाता है, `<context>` टैग में रैप्ड। यह उपयोगकर्ता से छिपा नहीं है। तुरंत भेजने के लिए `submit: true` पास करें, या एक ड्राफ्ट प्रीफिल करने के लिए `submit: false` पास करें जिसे उपयोगकर्ता पहले रिव्यू करता है।
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| विकल्प        | प्रकार     | विवरण                                                                                            |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------ |
+| `message`     | `string`   | चैट पर भेजा गया प्रॉम्प्ट। यदि सेट है, तो `context` इसी दिखने वाले मैसेज में जुड़ जाता है        |
+| `context`     | `string?`  | दिखने वाले मैसेज में जुड़ा अतिरिक्त विवरण, `<context>` टैग में रैप्ड। उपयोगकर्ता से छिपा नहीं है |
+| `submit`      | `boolean?` | true = ऑटो-सबमिट, false = केवल प्रीफिल                                                           |
+| `newTab`      | `boolean?` | इस प्रॉम्प्ट के लिए एक अलग चैट थ्रेड बनाएं                                                       |
+| `openSidebar` | `boolean?` | साइडबार खोले बिना सबमिट/प्रीफिल करने के लिए false सेट करें                                       |
+
+इसी रूट को MCP App के रूप में एम्बेड करने से, या साइडबार खोले बिना रन को बैकग्राउंड में ले जाने से जुड़ी बातें [उन्नत](/docs/client-advanced#background-send) में कवर की गई हैं।
+
+## डायनामिक सुझाव {#dynamic-suggestions}
+
+किसी बातचीत के शुरू होने से पहले, `<AgentSidebar>`, `<AgentPanel>`, और `<AssistantChat>` खाली चैट पर प्रॉम्प्ट चिप्स दिखाते हैं। डिफ़ॉल्ट रूप से वे केवल आपकी फ़िक्स्ड `suggestions` सूची नहीं हैं: फ्रेमवर्क एप्लिकेशन स्टेट से `navigation`, `selection`, `pending-selection-context`, और वर्तमान URL पढ़ता है, और स्क्रीन पर वास्तव में जो है उससे मेल खाने वाले चिप्स मर्ज करता है।
+
+यह इसे दो जांचों के साथ करता है। यदि कुछ चुना गया है, तो यह सामान्य चिप्स जैसे "Summarize this selection" जोड़ता है। अलग से, यह `navigation` में उन कॉमन फ़ील्ड नामों को देखता है जिनका उपयोग ऐप्स पहले से करते हैं, जैसे किसी ईमेल थ्रेड के लिए `threadId`/`emailId` या किसी चार्ट के लिए `dashboardId`/`chartId`, और उस तरह की स्क्रीन के अनुरूप चिप्स जोड़ता है, जैसे थ्रेड के लिए "Draft a reply" या चार्ट के लिए "Find anomalies in this data"। यह जो भी लेकर आता है वह आपकी स्टैटिक `suggestions` के साथ मर्ज किया जाता है, डिडुप्लिकेट किया जाता है, और `max` पर कैप्ड किया जाता है।
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+यदि वर्तमान स्क्रीन बिल्ट-इन हेयुरिस्टिक की पहचान की गई किसी चीज़ से मेल नहीं खाती और कुछ भी चुना नहीं गया है, तो यह कोई चिप्स नहीं जोड़ता, और खाली चैट केवल आपकी स्टैटिक `suggestions` पर वापस आ जाती है। केवल स्टैटिक चिप्स रखने के लिए `dynamicSuggestions={false}` सेट करें। यदि आपके ऐप की नेविगेशन शेप बिल्ट-इन हेयुरिस्टिक से मेल नहीं खाती, या आप पूरी तरह से नियतात्मक ऐप-विशिष्ट चिप्स चाहते हैं, तो [उन्नत](/docs/client-advanced#custom-suggestions) देखें।
+
+## openAgentSettings(section?) {#openagentsettings}
+
+`openAgentSettings()` का उपयोग तब करें जब किसी ऐप सेटिंग्स पेज या सेटअप कार्ड को
+एजेंट साइडबार का Settings टैब खोलना चाहिए। किसी विशिष्ट सेक्शन को खोलने के लिए
+`"llm"`, `"secrets"`, `"automations"`, `"voice"`, या `"limits"` जैसा एक सेक्शन id पास करें।
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+सीधे `agent-panel:open-settings` डिस्पैच करने के बजाय इस हेल्पर को प्राथमिकता दें।
+
+## एजेंट चैट कॉन्टेक्स्ट स्थिति {#agent-chat-context-state}
+
+कॉन्टेक्स्ट-स्टेट APIs स्टेज्ड कॉन्टेक्स्ट चिप्स के साथ दो-तरफ़ा सिंक की आवश्यकता वाले UI के लिए वैकल्पिक प्लंबिंग हैं: कंपोज़र के बाहर वर्तमान स्टेज्ड आइटम को रेंडर करना, यह दर्शाना कि कोई आइटम पहले से अटैच है या नहीं, या स्पष्ट रिमूव/क्लियर कंट्रोल प्रदान करना।
+
+सरल "इसे एजेंट को भेजें" या "इस ड्राफ्ट को रिव्यू के लिए प्रीफिल करें" फ्लो के लिए इन हेल्पर्स तक न पहुंचें। उनके लिए `context` और `submit` के साथ [`sendToAgentChat()`](#sendtoagentchat) का उपयोग करें।
+
+| API                               | कब उपयोग करें                                                                     |
+| --------------------------------- | --------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | एक React घटक को लाइव स्टेज्ड कॉन्टेक्स्ट सूची की आवश्यकता है                      |
+| `setAgentChatContextItem(item)`   | इंपेरेटिव कोड को एक keyed कॉन्टेक्स्ट आइटम को स्टेज या रिप्लेस करना चाहिए         |
+| `listAgentChatContext()`          | नॉन-React कोड को स्टेज्ड कॉन्टेक्स्ट के एक बार के स्नैपशॉट की आवश्यकता है         |
+| `removeAgentChatContextItem(key)` | UI को अपने स्थिर `key` से एक स्टेज्ड कॉन्टेक्स्ट आइटम हटा देना चाहिए              |
+| `clearAgentChatContext()`         | UI को सभी स्टेज्ड कॉन्टेक्स्ट साफ़ करना चाहिए, जैसे किसी व्यू या मोड रीसेट के बाद |
+| `refreshAgentChatContext()`       | इंपेरेटिव कोड को नवीनतम परसिस्टेड कॉन्टेक्स्ट स्नैपशॉट को फिर से पढ़ना चाहिए      |
+
+`useAgentChatContext()`, `{ items, set, remove, clear, refresh }` लौटाता है।
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` उस इंपेरेटिव कोड के लिए है जिसे केवल वर्तमान स्टेज्ड आइटम को एक बार निरीक्षण करने की आवश्यकता है। `clearAgentChatContext()` जानबूझकर व्यापक है। जब केवल एक सिलेक्शन बदला हो तो `removeAgentChatContextItem(key)` का उपयोग करें।
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| विकल्प        | प्रकार     | विवरण                                                                           |
+| ------------- | ---------- | ------------------------------------------------------------------------------- |
+| `key`         | `string`   | मौजूदा नगेट को रिप्लेस करने के लिए उपयोग किया जाने वाला स्थिर पहचानकर्ता        |
+| `title`       | `string`   | कंपोज़र चिप में दिखाया गया छोटा लेबल                                            |
+| `context`     | `string`   | अगले सबमिट किए गए प्रॉम्प्ट के साथ शामिल छिपा हुआ कॉन्टेक्स्ट                   |
+| `openSidebar` | `boolean?` | डिफ़ॉल्ट रूप से true। कॉन्टेक्स्ट को साइलेंटली स्टेज करने के लिए false पास करें |
+
+## आगे क्या
+
+- [**अवलोकन**](/docs/client-overview) - `app/` में यह हेल्पर्स कहां फिट होते हैं
+- [**डेटा और सिंक**](/docs/client-data) - action हुक और `useDbSync` जो खुद UI को करेंट रखते हैं
+- [**ड्रॉप-इन एजेंट**](/docs/drop-in-agent) - `<AgentSidebar>`/`<AgentPanel>` माउंट करना ताकि इन हेल्पर्स के पास रेंडर करने के लिए कुछ हो
+- [**उन्नत**](/docs/client-advanced) - बैकग्राउंड सेंड, कस्टम सुझाव चिप्स, और MCP App होस्ट ब्रिज
+- [**Generative UI**](/docs/generative-ui) - `askUserQuestion` से आगे इन-चैट कंट्रोल्स बनाना
diff --git a/packages/core/docs/content/locales/hi-IN/client-data.mdx b/packages/core/docs/content/locales/hi-IN/client-data.mdx
new file mode 100644
index 0000000000..2f1488aa3b
--- /dev/null
+++ b/packages/core/docs/content/locales/hi-IN/client-data.mdx
@@ -0,0 +1,435 @@
+---
+title: "डेटा और सिंक"
+description: "वे action हुक जिनका उपयोग app/ पढ़ने, लिखने, और उन्हीं actions के साथ लाइव-सिंक रहने के लिए करता है जिन्हें एजेंट कॉल करता है।"
+---
+
+# डेटा और सिंक
+
+क्लाइंट एप्लिकेशन से ऐप डेटा पढ़ने और लिखने का प्राथमिक तरीका [action](/docs/actions) हुक के माध्यम से है। रिक्वेस्ट को actions में एम्बेड करके, आपका क्लाइंट और एजेंट दोनों आपके एप्लिकेशन के साथ एक ही तरीके से इंटरैक्ट कर सकते हैं।
+
+नीचे दिए गए उदाहरण में, एक टिकट को वर्तमान उपयोगकर्ता को पहले मैन्युअल रूप से एक ड्रॉपडाउन के माध्यम से असाइन किया जाता है, और फिर चैट एजेंट के माध्यम से। UI और एजेंट दोनों एक ही action का उपयोग करते हैं।
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="एक UI action और एक एजेंट action का एक ही परिणाम होने का उदाहरण।"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="एक UI action और एक एजेंट action का एक ही परिणाम होने का उदाहरण।"
+/>
+
+## डेटा फ़ेच और म्यूटेट करें {#fetching-mutating}
+
+एक सामान्य ऐप अपनी खुद की API लेयर बनाता है और उसे हाथ से लिखे `fetch` रिक्वेस्ट के साथ कॉल करता है। एक एजेंट-नेटिव ऐप उस लेयर को छोड़ देता है: `app/` उन्हीं actions को कॉल करता है जो एजेंट के पास नीचे दिए गए हुक के माध्यम से टूल के रूप में पहले से हैं।
+
+<Diagram id="doc-block-client-data-fm-1" title="सामान्य fetch बनाम एक action हुक" summary="एक सामान्य घटक एक रूट को कॉल करता है जिसे केवल वही पहुंच सकता है। एक एजेंट-नेटिव घटक एक ऐसी action को कॉल करता है जिसे एजेंट भी कॉल कर सकता है।">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">सामान्य</div>
+    <div class="diagram-node">घटक</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>आपका API रूट</strong>
+      <small class="diagram-muted">केवल फ्रंटएंड इसे कॉल कर सकता है</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>डेटाबेस</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">बनाम</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">घटक</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead action</span>
+      <small class="diagram-muted">एक एजेंट टूल भी है</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL डेटाबेस</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Action हुक {#action-hooks}
+
+दो action हुक हैं जिनका उपयोग करने की सबसे अधिक संभावना है: `useActionQuery()` और `useActionMutation()`। ये दो हुक आपके ऐप की actions तक एक्सेस प्रदान करते हैं।
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "action का रजिस्टर्ड नाम।",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "action का इनपुट, इसके `defineAction()` स्कीमा से टाइप किया गया।",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "[useQuery options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) से सब कुछ, `queryKey` और `queryFn` को छोड़कर, जिन्हें हुक स्वयं सेट करता है।",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      '`["action", name, params]` के अंतर्गत कैश किया गया। किसी भी म्यूटेटिंग action के पूरा होने पर स्वचालित रूप से रीफ़ेच होता है, बिना किसी मैन्युअल इनवैलिडेशन की आवश्यकता के।',
+  }}
+/>
+
+यह हुक केवल-पढ़ने योग्य actions के लिए उपयोग किए जाने का इरादा है। यह [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) फ़ंक्शन के इर्द-गिर्द एक पतला रैपर है।
+
+नीचे दिए गए उदाहरण में, `list-tickets` action को कॉल किया जाता है। यह सभी टिकट के लिए GET रिक्वेस्ट बनाने जैसा है।
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+निम्नलिखित उदाहरण `get-ticket` action के माध्यम से एक ही टिकट को फ़ेच करने के लिए एक रिक्वेस्ट दिखाता है। क्वेरी को केवल एक विशिष्ट टिकट लौटाने के लिए स्कोप करने के लिए एक `ticketId` प्रदान किया जाता है। अतिरिक्त `enabled` विकल्प यह सुनिश्चित करने के लिए प्रदान किया गया है कि क्वेरी स्वचालित रूप से नहीं चलती है, और केवल तब चलती है जब कोई `ticketId` मौजूद हो।
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "action का रजिस्टर्ड नाम।",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "[useMutation options](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) से सब कुछ, `mutationFn` को छोड़कर, जिसे हुक स्वयं सेट करता है।",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "डिफ़ॉल्ट रिक्वेस्ट मेथड को ओवरराइड करता है।",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "सफलता पर स्वचालित कैश रीफ्रेश से बाहर निकलता है।",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'सफलता पर, `source: "action"` के साथ एक चेंज इवेंट उत्सर्जित करता है, इसलिए प्रभावित डेटा पढ़ने वाला हर `useActionQuery()` स्वचालित रूप से रीफ़ेच होता है। किसी मैन्युअल इनवैलिडेशन की आवश्यकता नहीं है।',
+  }}
+/>
+
+यह हुक उन actions के लिए उपयोग किए जाने का इरादा है जो डेटा बदलती हैं, जैसे बनाना, अपडेट करना, या कुछ भेजना। यह [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) फ़ंक्शन के इर्द-गिर्द एक पतला रैपर है।
+
+`useActionQuery()` के विपरीत, action का इनपुट हुक को स्वयं पास नहीं किया जाता है। इसे `mutate()` या `mutateAsync()` को पास किया जाता है जब आप म्यूटेशन चलाने के लिए तैयार हों।
+
+नीचे दिए गए उदाहरण में, `send-ticket-reply` action को किसी टिकट पर रिप्लाई पोस्ट करने के लिए कॉल किया जाता है। किसी इवेंट हैंडलर से, जैसे किसी बटन के `onClick` से, `mutate()` कॉल करें।
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+निम्नलिखित उदाहरण एक `onSuccess` विकल्प के साथ वही म्यूटेशन दिखाता है। कैश इनवैलिडेशन हर म्यूटेशन के बाद स्वचालित रूप से होता है, इसलिए `onSuccess` की आवश्यकता केवल लोकल साइड इफ़ेक्ट के लिए होती है, जैसे रिप्लाई भेजने के बाद रिप्लाई कंपोज़र को साफ़ करना।
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "action का रजिस्टर्ड नाम।",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "action का इनपुट, इसके `defineAction()` स्कीमा से टाइप किया गया।",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "नीचे सब कुछ वैकल्पिक है।",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "डिफ़ॉल्ट रिक्वेस्ट मेथड को ओवरराइड करता है।",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "रिक्वेस्ट को कैंसल करता है।",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "उन actions के लिए डिफ़ॉल्ट 60 सेकंड टाइमआउट को ओवरराइड करता है जो वैध रूप से अधिक समय लेती हैं।",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "ऊपर दिए गए हुक के विपरीत, यहां कोई कैश और कोई स्वचालित रीफ़ेच नहीं है। यदि अन्य UI परिणाम पर निर्भर है तो इसे मैन्युअल इनवैलिडेशन के साथ जोड़ें।",
+  }}
+/>
+
+यह फ़ंक्शन React रेंडर फ्लो के बाहर इंपेरेटिव वन-ऑफ़ action कॉल के लिए है, जैसे कोई सादा इवेंट हैंडलर, एक स्क्रिप्ट, या कोई अन्य नॉन-React कोड पथ। यह एक हुक परिणाम के बजाय सीधे एक प्रॉमिस लौटाता है।
+
+नीचे दिए गए उदाहरण में, `update-ticket` action को एक कीबोर्ड शॉर्टकट हैंडलर से React के रेंडर फ्लो के बाहर कॉल किया जाता है, जो टिकट को एक रेप को असाइन करता है।
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+निम्नलिखित उदाहरण `timeoutMs` विकल्प के साथ वही कॉल दिखाता है, जो उन actions के लिए उपयोगी है जो वैध रूप से डिफ़ॉल्ट 60 सेकंड टाइमआउट से अधिक समय लेती हैं।
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+हर `useActionQuery()`, `useActionMutation()`, और `callAction()` रिक्वेस्ट 60 सेकंड के टाइमआउट से बंधी है, और टाइमआउट बिना साइलेंट रीट्राई के त्रुटियों के रूप में सामने आते हैं। `useActionQuery()` React Query के एबॉर्ट सिग्नल का उपयोग करते हुए सुपरसीडेड रिक्वेस्ट को भी स्वचालित रूप से कैंसल करता है।
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "हर फ़ील्ड वैकल्पिक है।",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description:
+            "कैश इनवैलिडेशन के लिए उपयोग किया जाने वाला React Query क्लाइंट।",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "पोल एंडपॉइंट URL।",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "SSE एंडपॉइंट URL। केवल पोलिंग उपयोग करने के लिए `false` पास करें।",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "मिलीसेकंड में पोलिंग इंटरवल।",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "SSE कनेक्टेड रहते हुए पोल इंटरवल, बैकअप के रूप में यदि कोई इवेंट मिस हो जाए। एक डिस्कनेक्टेड टैब इसके बजाय तेज़ `interval` (या एक फ़िक्स्ड इडल कैडेंस) पर पोल करता है।",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "ब्राउज़र टैब छिपे होने पर पोलिंग रोकें। छिपे टैब SSE को कनेक्टेड रखते हैं और सक्रिय रहते हुए हर 10 सेकंड में, इडल होने पर 60 सेकंड में एक बार से ज़्यादा तेज़ी से पोल नहीं करते।",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "अनदेखा करने के लिए प्रति-टैब रिक्वेस्ट सोर्स, ताकि कोई टैब अपने ही राइट्स से रीफ़ेच न करे।",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "जब SSE या पोलिंग को कोई चेंज इवेंट मिले तो वैकल्पिक कॉलबैक।",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "किसी action इवेंट द्वारा ट्रिगर किए गए व्यापक इनवैलिडेशन को फ़िल्टर करता है। शायद ही कभी आवश्यक होता है। किसी महंगी सक्रिय क्वेरी को एक्सप्लिसिट-रिफ्रेश सिमेंटिक्स पर रखने के लिए उपयोग करें जबकि सामान्य सोर्स-वर्ज़न वाली क्वेरीज़ फिर भी `useChangeVersion` के माध्यम से रिएक्ट करती रहें।",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "उन action नामों की सूची जिनके सिंक इवेंट को सभी action क्वेरीज़ को इनवैलिडेट नहीं करना चाहिए। केवल उन हाई-वॉल्यूम बैकग्राउंड actions के लिए जो पहले से अपना खुद का संकीर्ण इनवैलिडेशन करते हैं।",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description:
+            "डेप्रीकेटेड और अनदेखा किया गया। पुराने कॉल साइट्स के लिए रखा गया।",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+यह हुक UI को उन डेटाबेस बदलावों के साथ सिंक में रखने के लिए है जो आपकी अपनी actions के बाहर होते हैं, जैसे कोई एजेंट राइट, कोई वेबहुक, या किसी अन्य ब्राउज़र टैब से किया गया बदलाव। यह सर्वर-सेंट इवेंट पर बदलावों को सुनता है, और सर्वर-सेंट इवेंट उपलब्ध न होने पर पोलिंग पर वापस आ जाता है।
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+सामान्य CRUD के लिए, `useActionQuery()` और `useActionMutation()` को प्राथमिकता दें। म्यूटेटिंग actions `source: "action"` उत्सर्जित करती हैं, इसलिए वे हुक तुरंत रीफ़ेच होते हैं। एजेंट, किसी वेबहुक, या किसी अन्य टैब से आने वाले बदलाव इसके बजाय `useDbSync()` के माध्यम से आते हैं, SSE या पोलिंग फ़ॉलबैक पर। यदि किसी कस्टम key पर कच्चे `useQuery()` कॉल को सिंक करने की आवश्यकता है, तो [सिंक इंटरनल्स](/docs/client-sync-internals) देखें। यदि आपको सीधे `application_state` पर लिखने की आवश्यकता है, तो [उन्नत](/docs/client-advanced) देखें।
+
+## आगे क्या
+
+- [**अवलोकन**](/docs/client-overview) - `app/` और `public/` डायरेक्टरी लेआउट जिसमें इस पेज के हुक रहते हैं
+- [**एजेंट चैट**](/docs/client-agent-chat) - एजेंट के लिए प्रॉम्प्ट भेजना और कॉन्टेक्स्ट स्टेज करना
+- [**Actions**](/docs/actions) - इस पेज के हर हुक के पीछे `defineAction` सतह
+- [**उन्नत**](/docs/client-advanced) - सीधी `application_state` एक्सेस
+- [**सिंक इंटरनल्स**](/docs/client-sync-internals) - `useChangeVersion` के साथ कच्चे `useQuery` को सिंक करना
+- [**रीयल-टाइम सिंक**](/docs/key-concepts#polling-sync) - `useDbSync` UI को कैसे करेंट रखता है
diff --git a/packages/core/docs/content/locales/hi-IN/client-entry-points.mdx b/packages/core/docs/content/locales/hi-IN/client-entry-points.mdx
new file mode 100644
index 0000000000..10aef7d009
--- /dev/null
+++ b/packages/core/docs/content/locales/hi-IN/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "एंट्री पॉइंट्स"
+description: "app/entry.client.tsx और app/entry.server.tsx: पतले हाइड्रेशन और SSR बूटस्ट्रैप रैपर, और स्ट्रीमिंग बिहेवियर को कब कस्टमाइज़ करें।"
+---
+
+# एंट्री पॉइंट्स
+
+`app/entry.client.tsx` सर्वर-रेंडर किए गए HTML को ब्राउज़र में हाइड्रेट करता है, और `app/entry.server.tsx` वह HTML सर्वर पर रेंडर करता है। दोनों React Router द्वारा जनरेट किए गए पतले रैपर हैं। आपको इन्हें एडिट करने की शायद ही कभी आवश्यकता होती है।
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+इन्हें केवल एडवांस्ड SSR कस्टमाइज़ेशन के लिए एक्सेस करें, उदाहरण के लिए स्ट्रीमिंग बिहेवियर बदलने के लिए। सामान्य पेज, लेआउट, और डेटा को यहां किसी बदलाव की आवश्यकता नहीं है। इसके बजाय पेज जोड़ने के लिए [रूटिंग](/docs/client-routing) देखें।
+
+## आगे क्या
+
+- [**अवलोकन**](/docs/client-overview) - `app/` में ये फ़ाइलें कहां बैठती हैं
+- [**रूटिंग**](/docs/client-routing) - पेज जोड़ना, `app/` को बढ़ाने का सामान्य तरीका
+- [**उन्नत**](/docs/client-advanced) - अन्य लोअर-लेवल क्लाइंट प्रिमिटिव और एस्केप हैच
diff --git a/packages/core/docs/content/locales/hi-IN/client-overview.mdx b/packages/core/docs/content/locales/hi-IN/client-overview.mdx
new file mode 100644
index 0000000000..ee7bdda082
--- /dev/null
+++ b/packages/core/docs/content/locales/hi-IN/client-overview.mdx
@@ -0,0 +1,205 @@
+---
+title: "अवलोकन"
+description: "app/ और public/ डायरेक्टरी: जहां आप एजेंट-नेटिव ऐप का डिस्प्ले बनाते हैं, और वे ब्राउज़र APIs जिनका उपयोग यह एजेंट के साथ सिंक रहने के लिए करता है।"
+---
+
+# अवलोकन
+
+`app/` वह जगह है जहां आप एजेंट-नेटिव ऐप का वास्तविक डिस्प्ले बनाते हैं: पेज, लेआउट, घटक, स्टाइल। `public/` इसके साथ परोसी जाने वाली स्टैटिक एसेट्स रखता है - आइकन, मैनिफेस्ट, ब्रांड मार्क। यह एक सामान्य React Router v8 ऐप है, कोई विशेष एजेंट-ओनली सतह नहीं, और यहीं अधिकांश डेवलपमेंट समय व्यतीत होता है।
+
+एक सामान्य फ्रंटएंड से यही वास्तुशिल्प अंतर है: इस लेयर का अपना कोई बैकएंड-फॉर-फ्रंटएंड नहीं है। यह उन्हीं actions के माध्यम से डेटा पढ़ता और लिखता है जिन्हें एजेंट कॉल करता है, इसलिए यहां वायर की गई कोई भी क्षमता स्वचालित रूप से वह चीज़ बन जाती है जो एजेंट भी कर सकता है।
+
+<Diagram id="doc-block-client-overview-1" title="सामान्य फ्रंटएंड बनाम Agent Native" summary="एक सामान्य फ्रंटएंड अपनी खुद की API लेयर को कॉल करता है, जिसे केवल वही पहुंच सकता है। Agent Native में, app/ और एजेंट दोनों एक ही actions को कॉल करते हैं, इसलिए यहां बनाई गई हर क्षमता मुफ़्त में एजेंट-कॉल करने योग्य है।">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">सामान्य</div>
+    <div class="diagram-node">app/ (React फ्रंटएंड)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API लेयर</strong>
+      <small class="diagram-muted">केवल फ्रंटएंड इसे कॉल करता है</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>डेटाबेस</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">बनाम</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React फ्रंटएंड)</div>
+      <div class="diagram-node">एजेंट</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">समान भागीदार, समान ऑपरेशन</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL डेटाबेस</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## क्लाइंट कहां फिट होता है {#role}
+
+ब्राउज़र रिक्वेस्ट, एजेंट लूप, और बाहरी API क्लाइंट सभी एक ही actions और एक ही SQL डेटाबेस पर रिज़ॉल्व होते हैं - यहां कोई अलग "ऐप बैकएंड" नहीं है जिससे यह लेयर बात करती हो और जिसे एजेंट न पहुंच सके। यहां कोई फ़ीचर बनाने का मतलब है ऐसे ऑपरेशन के ऊपर UI बनाना जो एजेंट के पास पहले से है, या एक नई action परिभाषित करना और उसके लिए एक साथ UI पाना। उस कॉन्ट्रैक्ट के ऑपरेशन साइड के लिए [Actions](/docs/actions) देखें।
+
+यह पेज उन डायरेक्टरी को कवर करता है जिनमें आप बनाते हैं और ब्राउज़र रनटाइम के उन हिस्सों को जिन्हें कोई और डॉक्यूमेंट नहीं करता (`root.tsx`, `public/`)। वे React हुक जो आपके घटकों को actions और एजेंट से जोड़ते हैं, अपने-अपने केंद्रित पेजों पर रहते हैं:
+
+| पेज                                              | यह क्या कवर करता है                                                                                                |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| **[डेटा और सिंक](/docs/client-data)**            | `useActionQuery`, `useActionMutation`, `callAction`, और `useDbSync`                                                |
+| **[एजेंट चैट](/docs/client-agent-chat)**         | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, डायनामिक सुझाव, और स्टेज्ड एजेंट चैट कॉन्टेक्स्ट स्थिति |
+| **[उन्नत](/docs/client-advanced)**               | सीधी `application_state` एक्सेस, बैकग्राउंड चैट सेंड, कस्टम सुझाव चिप्स, और MCP App होस्ट ब्रिज                    |
+| **[सिंक इंटरनल्स](/docs/client-sync-internals)** | कच्चे `useQuery` को सिंक करने के लिए `useChangeVersion`/`useChangeVersions`                                        |
+| **[एंट्री पॉइंट्स](/docs/client-entry-points)**  | `app/entry.client.tsx`/`app/entry.server.tsx` और SSR कस्टमाइज़ेशन                                                  |
+
+## app/ और public/ में क्या है {#project-directories}
+
+| पथ                                                  | यह क्या कवर करता है                                                                                            |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | HTML शेल और प्रोवाइडर स्टैक - नीचे [ब्राउज़र शेल](#app-shell) देखें                                            |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | हाइड्रेशन और SSR बूटस्ट्रैप - [एंट्री पॉइंट्स](/docs/client-entry-points) देखें                                |
+| **`app/routes.ts` + `app/routes/`**                 | फ़ाइल-आधारित पेज और नेविगेशन - [रूटिंग](/docs/client-routing) देखें                                            |
+| **`app/components/`**                               | आपका UI: shadcn-स्टाइल प्रिमिटिव प्लस ऐप-विशिष्ट घटक - [shadcn/ui](/docs/shadcn-ui) देखें                      |
+| **`app/hooks/`**                                    | डेटा, सिंक, और एजेंट-चैट हुक - [डेटा और सिंक](/docs/client-data) और [एजेंट चैट](/docs/client-agent-chat) देखें |
+| **`app/lib/`**                                      | साझा क्लाइंट यूटिलिटीज़ (ऐप कॉन्फिग, टैब आईडी, `cn`) - नीचे [यूटिलिटीज़](#utilities) देखें                     |
+| **`app/design-system.ts`**                          | वैकल्पिक कस्टम डिज़ाइन सिस्टम एडाप्टर - [कस्टम डिज़ाइन सिस्टम](/docs/custom-design-system) देखें               |
+| **`app/i18n/`**                                     | लोकलाइज़्ड UI कॉपी कैटलॉग - [Internationalization](/docs/internationalization) देखें                           |
+| **`app/global.css`**                                | बेस स्टाइल और Tailwind एंट्री पॉइंट                                                                            |
+| **`public/`**                                       | स्टैटिक एसेट्स जैसी हैं वैसी ही परोसी जाती हैं - नीचे [स्टैटिक एसेट्स](#public-directory) देखें                |
+
+## ब्राउज़र शेल: root.tsx और AppProviders {#app-shell}
+
+`app/root.tsx` React ट्री का शीर्ष है: HTML डॉक्यूमेंट शेल (`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`) प्लस वह प्रोवाइडर स्टैक जिसके अंदर हर रूट रेंडर होता है।
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` एक ही रैपर है जो इसे वायर करता है:
+
+- वह React Query क्लाइंट जिसका उपयोग `useActionQuery`/`useActionMutation` करते हैं (देखें [डेटा और सिंक](/docs/client-data#fetching-mutating))।
+- `i18n.catalog` के रूप में पास किया गया i18n कैटलॉग (देखें [Internationalization](/docs/internationalization))।
+- क्लाइंट-साइड सेशन जांच: किसी प्राइवेट पथ पर, एक अनाम विज़िटर को किसी भी प्राइवेट UI माउंट होने से पहले साइन-इन पर रीडायरेक्ट किया जाता है। पब्लिक/SEO रूट्स के लिए `isPublicPath` पास करें, या ऐसी सतह के लिए `sessionBypass` जो किसी और तरीके से प्रमाणित होती है, जैसे MCP एम्बेड टोकन। देखें [Authentication](/docs/authentication)।
+
+अधिकांश ऐप्स यहां `<AgentSidebar>` या `<AgentPanel>` भी माउंट करते हैं ताकि हर रूट को मुफ़्त में एजेंट पैनल मिल जाए। देखें [ड्रॉप-इन एजेंट](/docs/drop-in-agent#sidebar)।
+
+## स्टैटिक एसेट्स: public/ {#public-directory}
+
+`public/` में सब कुछ जैसा है वैसा ही साइट रूट पर परोसा जाता है, बिल्ड द्वारा प्रोसेस नहीं किया जाता। हर टेम्पलेट यह शिप करता है:
+
+```text
+public/
+  favicon.svg           -> ब्राउज़र टैब आइकन
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> manifest.json से रेफ़र किए गए PWA आइकन
+  manifest.json          -> वेब ऐप मैनिफेस्ट (नाम, थीम रंग, आइकन)
+  *-logo-*.svg, *-icon-*.svg -> डिफ़ॉल्ट UI में उपयोग किए गए ब्रांड मार्क
+```
+
+`manifest.json` यह नियंत्रित करता है कि यदि कोई विज़िटर ऐप को होम स्क्रीन या ऐप डॉक में इंस्टॉल करता है तो क्या दिखता है - नाम, शॉर्ट नेम, थीम/बैकग्राउंड रंग, और आइकन सेट:
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+इन फ़ाइलों को बदलकर और `root.tsx` में इन्हें रेफ़र करने वाले `manifest.json` और `<link rel="icon">`/`<link rel="apple-touch-icon">` टैग को अपडेट करके किसी ऐप को रीब्रांड करें - कोई अलग रजिस्ट्रेशन स्टेप नहीं है। किसी मौजूदा साइट से पूरा ब्रांड सिस्टम (रंग, फ़ॉन्ट, फ़ेविकॉन) खींचने के लिए, इन फ़ाइलों को हाथ से एडिट करने के बजाय, देखें [Brand Systems and Figma](/docs/template-design-brand-and-figma)।
+
+## यूटिलिटीज़: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` क्लास नामों को मर्ज करता है (clsx + tailwind-merge) और `app/components/` में कंडीशनल Tailwind क्लासेस को कंपोज़ करने का स्टैंडर्ड तरीका है।
+
+## आगे क्या
+
+- [**डेटा और सिंक**](/docs/client-data) - action हुक और `useDbSync`
+- [**एजेंट चैट**](/docs/client-agent-chat) - `sendToAgentChat`, `askUserQuestion`, और डायनामिक सुझाव
+- [**उन्नत**](/docs/client-advanced) - एप्लिकेशन स्थिति, बैकग्राउंड चैट सेंड, और MCP App होस्ट ब्रिज
+- [**सिंक इंटरनल्स**](/docs/client-sync-internals) - कच्चे `useQuery` को सिंक करने के लिए `useChangeVersion`
+- [**रूटिंग**](/docs/client-routing) - फ़ाइल-आधारित पेज, डायनामिक पैरामीटर, और नेविगेशन
+- [**Actions**](/docs/actions) - हर data हुक के पीछे `defineAction` सतह
+- [**कस्टम डिज़ाइन सिस्टम**](/docs/custom-design-system) - `app/design-system.ts` के माध्यम से अपनी खुद की घटक लाइब्रेरी स्वैप करना
+- [**Authentication**](/docs/authentication) - सेशन जांच जो `AppProviders` प्राइवेट पथों पर चलाता है
diff --git a/packages/core/docs/content/locales/hi-IN/client-routing.mdx b/packages/core/docs/content/locales/hi-IN/client-routing.mdx
new file mode 100644
index 0000000000..1c9e488160
--- /dev/null
+++ b/packages/core/docs/content/locales/hi-IN/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "रूटिंग"
+description: "React Router v8 के साथ एजेंट-नेटिव ऐप्स के लिए फ़ाइल-आधारित रूटिंग: पेज, डायनामिक पैरामीटर, और नेविगेशन।"
+---
+
+# रूटिंग
+
+एजेंट-नेटिव ऐप्स `@react-router/fs-routes` से `flatRoutes()` के माध्यम से फ़ाइल-आधारित रूटिंग के साथ **React Router v8** का उपयोग करते हैं। `app/routes/` में हर फ़ाइल एक URL बन जाती है। टेम्पलेट डॉट-नोटेशन कन्वेंशन का उपयोग करते हैं। डॉट्स एक ही फ़ाइलनेम के भीतर URL सेगमेंट को अलग करते हैं।
+
+यह पेज क्लाइंट रूट्स को कवर करता है, वे पेज जो `app/routes/` से ब्राउज़र में रेंडर होते हैं। सर्वर रूट्स एक अलग सिस्टम हैं: `server/routes/` के अंतर्गत Nitro फ़ाइल रूट्स, प्लस फ्रेमवर्क के अपने `/_agent-native/*` एंडपॉइंट। वे [Routes](/docs/server-routes) पेज पर रहते हैं। दोनों कोई डायरेक्टरी, कोई नामकरण कन्वेंशन, या कोई राउटर साझा नहीं करते, इसलिए `server/routes/` की कोई फ़ाइल यहां कभी पेज नहीं बनती और `app/routes/` की कोई फ़ाइल कभी सर्वर एंडपॉइंट नहीं बनती।
+
+<Diagram id="doc-block-client-routing-1" title="फ़ाइल नाम → URL" summary="app/routes/ में हर फ़ाइल एक URL बन जाती है। डॉट्स स्लैश बन जाते हैं, और एक $ सेगमेंट एक डायनामिक पैरामीटर बन जाता है।">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## फ़ाइल-आधारित रूटिंग {#file-based-routing}
+
+### फ़ाइल → URL मैपिंग
+
+| फ़ाइल                      | URL                    | नोट्स                                                                              |
+| -------------------------- | ---------------------- | ---------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | इंडेक्स रूट                                                                        |
+| `dashboard.tsx`            | `/dashboard`           | सरल पेज                                                                            |
+| `extensions.$id.tsx`       | `/extensions/:id`      | `extensions.tsx` के `<Outlet/>` के भीतर नेस्ट होता है। `$` एक डायनामिक पैरामीटर है |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | ट्रेलिंग `_` नेस्टिंग को स्किप करता है, इसलिए यह अपना खुद का पेज है                |
+| `_app.tsx`                 | (कोई URL सेगमेंट नहीं) | पाथलेस लेआउट। `_` के साथ प्रीफ़िक्स करें                                           |
+| `inbox/route.tsx`          | `/inbox`               | फ़ोल्डर फॉर्म। `route.tsx` इंडेक्स है                                              |
+
+डायनामिक पैरामीटर के लिए किसी सेगमेंट को `$` से प्रीफ़िक्स करें। इसे पाथलेस लेआउट रूट (कोई URL सेगमेंट नहीं) बनाने के लिए `_` से प्रीफ़िक्स करें, या नेस्टेड-दिखने वाले पथ को उसके पैरेंट के लेआउट के अंतर्गत नेस्टिंग से बाहर करने के लिए किसी डॉट से पहले ट्रेलिंग `_` जोड़ें। टेम्पलेट `flatRoutes()` का उपयोग करते हैं। ऊपर दिया डॉट-नोटेशन फ़ाइल फॉर्म प्राइमरी है। नेस्टेड-फ़ोल्डर फॉर्म `inbox/route.tsx` भी काम करता है।
+
+## एक नया पेज जोड़ना {#adding-a-page}
+
+फ़ाइल बनाएं और एक डिफ़ॉल्ट घटक एक्सपोर्ट करें:
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+बस इतना ही। React Router इसे स्वचालित रूप से उठा लेता है, किसी रजिस्ट्रेशन की आवश्यकता नहीं है।
+
+## डायनामिक पैरामीटर {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+डॉट से पहले ट्रेलिंग `_` इस पेज को `dashboard.tsx` के `<Outlet/>` के भीतर नेस्ट होने से रोकता है, इसलिए यह टिकट क्यू के लेआउट के भीतर दिखने के बजाय `/dashboard/:ticketId` पर अपने खुद के पूरे पेज के रूप में रेंडर होता है।
+
+## नेविगेशन {#navigation}
+
+क्लाइंट-साइड नेविगेशन के लिए `<Link>` और प्रोग्रामेटिक नेविगेशन के लिए `useNavigate()` का उपयोग करें:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+इनमें से कोई भी अपने आप एजेंट को यह नहीं बताता कि उपयोगकर्ता क्या देख रहा है। वह एक अलग चिंता है, जिसे `useAgentRouteState()` द्वारा वर्तमान रूट को एप्लिकेशन स्टेट में लिखकर संभाला जाता है। देखें [Context Awareness](/docs/context-awareness)।
+
+## आगे क्या
+
+- [**अवलोकन**](/docs/client-overview) - `app/routes/` `app/` और `public/` के बाकी हिस्सों में कहां फिट होता है
+- [**डेटा और सिंक**](/docs/client-data) - किसी रूट के भीतर से डेटा पढ़ना और लिखना
+- [**एजेंट चैट**](/docs/client-agent-chat) - किसी रूट से प्रॉम्प्ट भेजना और कॉन्टेक्स्ट स्टेज करना
+- [**Routes**](/docs/server-routes) - अलग सर्वर-रूटिंग सिस्टम: `server/routes/` के अंतर्गत फ़ाइल रूट्स और फ्रेमवर्क का `/_agent-native/` नेमस्पेस
+- [**Context Awareness**](/docs/context-awareness) - एजेंट वर्तमान रूट और सिलेक्शन को कैसे जानता है
diff --git a/packages/core/docs/content/locales/hi-IN/client-sync-internals.mdx b/packages/core/docs/content/locales/hi-IN/client-sync-internals.mdx
new file mode 100644
index 0000000000..f62e8fda6f
--- /dev/null
+++ b/packages/core/docs/content/locales/hi-IN/client-sync-internals.mdx
@@ -0,0 +1,124 @@
+---
+title: "सिंक इंटरनल्स"
+description: "useDbSync के पीछे का चेंज-वर्ज़न मेकैनिज़्म: कच्चे useQuery को सिंक करने के लिए useChangeVersion/useChangeVersions, और वे दो लेटेंसी पथ जो कोई रीफ़ेच ले सकता है।"
+---
+
+# सिंक इंटरनल्स
+
+[लाइव सिंक](/docs/key-concepts#polling-sync) मेंटल मॉडल को कवर करता है: एक एजेंट राइट एक चेंज इवेंट बन जाती है, `useDbSync()` उसे उठाता है, और प्रभावित क्वेरीज़ रीफ़ेच होती हैं। यह पेज उसके नीचे के मेकैनिज़्म को कवर करता है जिसे अधिकांश ऐप्स कभी सीधे नहीं छूते: वे चेंज-वर्ज़न काउंटर जिन्हें `useDbSync()` बंप करता है, और उन्हें कच्चे `useQuery()` कॉल में कैसे फ़ोल्ड करें जो `useActionQuery()` से नहीं गुज़रता।
+
+`useActionQuery()` किसी म्यूटेटिंग action के पूरा होने पर स्वचालित रूप से रीफ़ेच होता है (देखें [डेटा और सिंक](/docs/client-data#fetching-mutating))। `useChangeVersion()`/`useChangeVersions()` तक केवल तभी पहुंचें जब आप उस पथ के बाहर किसी कच्चे `useQuery()` कॉल को सिंक कर रहे हों, जैसे इंटीग्रेशन स्टेटस पढ़ने वाला कोई लो-लेवल क्लाइंट हेल्पर।
+
+## चेंज वर्ज़न कैसे काम करते हैं {#how-it-works}
+
+जब कोई सर्वर-साइड डेटाबेस म्यूटेशन होता है, तो सर्वर एक `source` key के साथ टैग किया गया चेंज इवेंट रिकॉर्ड करता है। `useDbSync()` उस इवेंट को प्राप्त करता है और उस source के लिए एक लोकल काउंटर बंप करता है। काउंटर को किसी React Query key में फ़ोल्ड करने से क्वेरी स्वचालित रूप से रीफ़ेच होती है जब भी बैकएंड उस source के लिए नई गतिविधि रिपोर्ट करता है।
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description: 'देखने के लिए चेंज-इवेंट source, जैसे `"dashboards"`।',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description:
+      "एक काउंटर जो हर बार दिए गए source के म्यूटेट होने पर बढ़ता है।",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "एक साथ देखने के लिए कई चेंज-इवेंट sources।",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "दिए गए हर source के लिए वर्ज़न काउंटरों का योग।",
+  }}
+/>
+
+नीचे दिए उदाहरण में, एक कच्चा `useQuery()` कॉल सीधे किसी डैशबोर्ड को पढ़ता है, `"dashboards"` source के वर्ज़न काउंटर को अपनी query key में फ़ोल्ड करते हुए ताकि यह उस source के बदलने पर रीफ़ेच हो:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` रीफ़ेच के दौरान पिछले डेटा को स्क्रीन पर रखता है, ताकि व्यू लोडिंग स्टेट पर फ़्लिकर न करे।
+
+## रीफ़ेच के दो पथ {#latency-models}
+
+एक म्यूटेशन UI तक दो तरीकों में से एक से पहुंचती है, और उनकी लेटेंसी अलग होती है।
+
+एक लोकल म्यूटेशन, जो आपके अपने `useActionMutation()` कॉल ने बस बनाया है, सफल होने पर तुरंत `source: "action"` इवेंट फायर करती है। उस action पर निर्भर हर क्वेरी तुरंत रीफ़ेच होती है। कोई राउंड-ट्रिप डिले नहीं है, क्योंकि जिस टैब ने राइट किया वह पहले से इसे जानता है।
+
+एक रिमोट म्यूटेशन, एजेंट से, किसी वेबहुक से, किसी अन्य टैब से, या किसी अन्य उपयोगकर्ता से, को पहले इस टैब तक पहुंचना होता है। `useDbSync()` इसे SSE पर लगभग तुरंत उठाता है, या SSE उपलब्ध न होने पर लगभग दो सेकंड के भीतर पोलिंग फ़ॉलबैक पर। केवल उस इवेंट के आने पर संबंधित वर्ज़न काउंटर बंप होता है और क्वेरी बैकग्राउंड में रीफ़ेच होती है।
+
+<Diagram id="doc-block-client-sync-internals-3" title="रीफ़ेच के दो पथ" summary="एक लोकल म्यूटेशन तुरंत अपने खुद के कैश को इनवैलिडेट करता है। एक रिमोट राइट SSE पर, या फ़ॉलबैक के रूप में पोलिंग टिक पर इस टैब तक पहुंचता है।">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">यह टैब</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >सफलता पर source: "action" फायर करता है &rarr; तुरंत लोकल रीफ़ेच</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">एजेंट · वेबहुक · अन्य टैब</span
+      ><strong>रिमोट राइट</strong
+      ><small class="diagram-muted"
+        >SSE पुश, या फ़ॉलबैक के रूप में ~2s पोलिंग टिक &rarr; वर्ज़न बंप &rarr;
+        बैकग्राउंड रीफ़ेच</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## आगे क्या
+
+- [**लाइव सिंक**](/docs/key-concepts#polling-sync) - वह कॉन्सेप्चुअल मेंटल मॉडल जिसके नीचे यह पेज जाता है
+- [**डेटा और सिंक**](/docs/client-data) - `useActionQuery`/`useDbSync`, जिनका उपयोग अधिकांश पेजों को इन प्रिमिटिव के बजाय करना चाहिए
+- [**उन्नत**](/docs/client-advanced) - अन्य लोअर-लेवल क्लाइंट प्रिमिटिव और एस्केप हैच
diff --git a/packages/core/docs/content/locales/hi-IN/client.mdx b/packages/core/docs/content/locales/hi-IN/client.mdx
deleted file mode 100644
index 3b68897fde..0000000000
--- a/packages/core/docs/content/locales/hi-IN/client.mdx
+++ /dev/null
@@ -1,470 +0,0 @@
----
-title: "क्लाइंट"
-description: "एजेंट-नेटिव ऐप्स के लिए React हुक और उपयोगिताएँ: sentToAgentChat, वैकल्पिक एजेंट चैट संदर्भ स्थिति, useDbSync, useAgentChatGenerating, और cn।"
----
-
-# ग्राहक
-
-`@agent-native/core` एजेंट-नेटिव ऐप्स के ब्राउज़र-साइड के लिए React हुक और उपयोगिताएँ प्रदान करता है।
-
-ये क्लाइंट/React APIs `@agent-native/core` और `@agent-native/core/client` दोनों से निर्यात किए जाते हैं। स्पष्टता और सही बंडलिंग के लिए उन्हें `@agent-native/core/client` (ब्राउज़र प्रविष्टि) से आयात करें, क्योंकि नंगे `@agent-native/core` रूट डिफ़ॉल्ट रूप से नोड बिल्ड का समाधान करता है।
-
-फ़ाइल-आधारित रूटिंग के लिए - पेज, डायनामिक पैरामीटर और नेविगेशन जोड़ना - [Routing](/docs/routing) देखें।
-
-## डेटा लाना और परिवर्तित करना {#fetching-mutating}
-
-ब्राउज़र से ऐप डेटा को पढ़ने और लिखने का प्राथमिक तरीका एक्शन हुक के माध्यम से है। `/_agent-native/*` मार्गों पर `fetch` कॉल को कभी भी हाथ से न लिखें - इसके बजाय नामित सहायकों का उपयोग करें ([Actions](/docs/actions) देखें)।
-
-<Diagram id="doc-block-f248eh" title={"ब्राउज़र डेटा लूप"} summary={"हुक क्रियाओं के माध्यम से पढ़ते और लिखते हैं; useDbSync डेटाबेस पर नज़र रखता है इसलिए एजेंट और बैकग्राउंड स्वचालित रूप से समान कैश पुनः प्राप्त करते हैं।"}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>SQL डेटाबेस</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(opts) {#sendtoagentchat}
-
-पोस्टमैसेज के माध्यम से एजेंट चैट को एक संदेश भेजें - UI इंटरैक्शन से AI कार्य सौंपने का सामान्य तरीका। छिपे हुए मॉडल संदर्भ के लिए `context` और तुरंत भेजने के लिए `submit: true` पास करें, या उपयोगकर्ता द्वारा पहले समीक्षा किए गए ड्राफ्ट को प्रीफिल करने के लिए `submit: false` पास करें।
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-`embedApp()` के साथ बनाए गए MCP ऐप एम्बेड के अंदर, स्वचालित रूप से सबमिट किए गए संदेश
-(`submit` छोड़ा गया या `true`) MCP ऐप होस्ट ब्रिज पर अग्रेषित किया जाता है, जो
-शामिल होस्ट को छिपा हुआ संदर्भ जोड़ने और दृश्यमान उपयोगकर्ता को भेजने के लिए कहता है।
-`context` उपयोगकर्ता-सामना वाली चैट के रूप में पोस्ट किए बिना मॉडल-दृश्यमान रहता है।
-`submit: false` स्थानीय प्रीफ़िल/समीक्षा व्यवहार को बनाए रखता है क्योंकि MCP ऐप्स ऐसा नहीं करते हैं
-एक मानक ड्राफ्ट-प्रीफिल API को परिभाषित करें। आंतरिक रूप से यह सबमिट-चैट पथ
-कभी-कभी `agentNative.submitChat` के रूप में सामने आता है; ऐप कोड को कॉल करना चाहिए
-उस ईवेंट को सीधे पोस्ट करने के बजाय `sendToAgentChat()`।
-
-### साइलेंट बैकग्राउंड भेजता है {#background-send}
-
-`background: true` का उपयोग तब करें जब UI कार्रवाई के बिना वास्तविक एजेंट का काम शुरू हो जाए
-साइडबार को खोलना या फोकस करना। यह अभी भी एक सामान्य चैट थ्रेड/रन बनाता है,
-एजेंट के टूल/actions/संदर्भ का उपयोग करता है, और कार्य को इसके माध्यम से देखने योग्य रखता है
-रन ट्रे; यह कोई कच्चा वन-शॉट मॉडल कॉल नहीं है।
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` को `newTab` के साथ जोड़ा जाना है ताकि छिपा हुआ काम न हो
-overwrite the user's active conversation. Use the returned `tabId` if the UI
-अनुवर्ती स्थिति को सहसंबंधित करने या बाद में चलने वाले डीप-लिंक की आवश्यकता है।
-
-### एजेंटचैटमैसेज {#agentchatmessage}
-
-| विकल्प                | प्रकार      | विवरण                                                                             |
-| --------------------- | ----------- | --------------------------------------------------------------------------------- |
-| `message`             | `string`    | चैट पर दृश्यमान संकेत भेजा गया                                                    |
-| `context`             | `string?`   | छिपा हुआ संदर्भ जोड़ा गया (चैट UI में नहीं दिखाया गया)                            |
-| `submit`              | `boolean?`  | सही = स्वतः-सबमिट, गलत = केवल पूर्व-भरण                                           |
-| `newTab`              | `boolean?`  | इस प्रॉम्प्ट के लिए एक अलग चैट थ्रेड बनाएं                                        |
-| `background`          | `boolean?`  | `newTab` के साथ, टैब पर ध्यान केंद्रित किए बिना चलाएं और `RunsTray` में रन दिखाएं |
-| `openSidebar`         | `boolean?`  | साइडबार खोले बिना सबमिट/प्रीफ़िल करने के लिए गलत सेट करें                         |
-| `projectSlug`         | `string?`   | संरचित संदर्भ के लिए वैकल्पिक प्रोजेक्ट स्लग                                      |
-| `preset`              | `string?`   | डाउनस्ट्रीम उपभोक्ताओं के लिए वैकल्पिक पूर्व निर्धारित नाम                        |
-| `referenceImagePaths` | `string[]?` | वैकल्पिक संदर्भ छवि पथ                                                            |
-
-## एजेंट चैट संदर्भ स्थिति (उन्नत) {#agent-chat-context-state}
-
-संदर्भ-स्थिति API, UI के लिए वैकल्पिक प्लंबिंग है जिसके साथ दो-तरफ़ा समन्वयन की आवश्यकता होती है
-मंचित संदर्भ चिप्स: कंपोजर के बाहर वर्तमान स्टेज्ड आइटम को प्रस्तुत करना,
-यह दर्शाता है कि क्या कोई आइटम पहले से ही संलग्न है, या स्पष्ट रूप से प्रदान कर रहा है
-नियंत्रण हटाएं/साफ़ करें।
-
-सरल "इसे एजेंट को भेजें" या
-"prefill this draft for review" flows. Use `sendToAgentChat()` with `context`
-और उनके लिए `submit`.
-
-| API                               | कब उपयोग करें                                                                   |
-| --------------------------------- | ------------------------------------------------------------------------------- |
-| `useAgentChatContext()`           | एक React घटक को लाइव चरणबद्ध संदर्भ सूची की आवश्यकता है                         |
-| `setAgentChatContextItem(item)`   | अनिवार्य कोड को एक कुंजी वाले संदर्भ आइटम को चरणबद्ध या प्रतिस्थापित करना चाहिए |
-| `listAgentChatContext()`          | गैर-React कोड को चरणबद्ध संदर्भ के एक बार के स्नैपशॉट की आवश्यकता है            |
-| `removeAgentChatContextItem(key)` | UI को अपने स्थिर `key` द्वारा एक चरणबद्ध संदर्भ आइटम को हटा देना चाहिए          |
-| `clearAgentChatContext()`         | UI को सभी चरणबद्ध संदर्भ साफ़ करना चाहिए, जैसे दृश्य या मोड रीसेट के बाद        |
-| `refreshAgentChatContext()`       | अनिवार्य कोड को नवीनतम जारी संदर्भ स्नैपशॉट को फिर से पढ़ना चाहिए               |
-
-`useAgentChatContext()`, `{ items, set, remove, clear, refresh }` लौटाता है।
-
-## openAgentSettings(अनुभाग?) {#openagentsettings}
-
-जब ऐप सेटिंग पेज या सेटअप कार्ड खुलना चाहिए तो `openAgentSettings()` का उपयोग करें
-एजेंट साइडबार का सेटिंग टैब। एक सेक्शन आईडी जैसे `"llm"`, `"secrets"`,
-किसी विशिष्ट अनुभाग को खोलने के लिए `"automations"`, `"voice"`, या `"limits"`।
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-सीधे `agent-panel:open-settings` भेजने के बजाय इस सहायक को प्राथमिकता दें।
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` अनिवार्य कोड के लिए है जिसे केवल निरीक्षण करने की आवश्यकता है
-वर्तमान चरणबद्ध आइटम एक बार। `clearAgentChatContext()` जानबूझकर व्यापक है; उपयोग करें
-`removeAgentChatContextItem(key)` जब केवल एक चयन बदला गया।
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| विकल्प        | प्रकार     | विवरण                                                              |
-| ------------- | ---------- | ------------------------------------------------------------------ |
-| `key`         | `string`   | मौजूदा नगेट को बदलने के लिए स्थिर पहचानकर्ता का उपयोग किया जाता है |
-| `title`       | `string`   | कंपोज़र चिप में दिखाया गया संक्षिप्त लेबल                          |
-| `context`     | `string`   | अगले सबमिट किए गए संकेत के साथ छिपा हुआ संदर्भ शामिल है            |
-| `openSidebar` | `boolean?` | डिफ़ॉल्ट सत्य पर; मंच के सन्दर्भ को चुपचाप पास करें                |
-
-## askUserQuestion(opts) {#ask-user-question}
-
-उपयोगकर्ता से ऐप कोड से बहुविकल्पीय प्रश्न पूछें, इसे इनलाइन में प्रस्तुत करें
-एजेंट पैनल, और **उनके उत्तर की प्रतीक्षा करें**। यह
-एजेंट का अंतर्निहित `ask-question` टूल: यह एक `GuidedQuestionPayload` लिखता है
-`"guided-questions"` एप्लिकेशन-स्टेट कुंजी (जहां माउंट किया गया है
-`GuidedQuestionFlow` इसे प्रस्तुत करता है) और एजेंट पैनल का खुलासा करता है इसलिए प्रश्न है
-दृश्यमान. एजेंट टूल के विपरीत - जिसका उत्तर एजेंट के पास वापस प्रवाहित होता है -
-`askUserQuestion()` **कॉल करने वाले के उत्तर के साथ समाधान करता है**, इसलिए UI कर सकता है
-उस पर शाखा.
-
-इसका उपयोग तब करें जब UI को इससे पहले ठीक एक छोटे निर्णय (2-4 विकल्प) की आवश्यकता हो
-कस्टम मोडल बनाने के बजाय एजेंट का काम शुरू करता है। के लिए पहुंचें
-फ्रीफॉर्म विवरण के लिए कंपोजर, और मल्टी-फील्ड इनपुट के लिए एक फॉर्म/पॉपओवर।
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-प्रत्येक विकल्प `{ label, value?, description?, preview?, recommended? }` है; `value`
-`label` पर डिफ़ॉल्ट होता है, और `preview` के अंतर्गत एक छोटा मॉकअप/कोड स्निपेट प्रस्तुत करता है
-विकल्प। वादा चयनित `value` (या `value[]` जब
-`allowMultiple`), जब उपयोगकर्ता "अन्य", या `null` चुनता है तो फ्री-टेक्स्ट स्ट्रिंग
-यदि वे छोड़ देते हैं - यह तब तक लंबित रहता है जब तक उपयोगकर्ता उत्तर नहीं देता। एजेंट पैनल की आवश्यकता है
-माउंट किया जाना है (यह हर टेम्पलेट में है)।
-
-एजेंट अपने `ask-question` टूल के माध्यम से उसी UI तक पहुंचता है: इसे देना पसंद करें
-एजेंट पूछता है कि जब _it_ वास्तविक कांटे से टकराता है तो यह संदर्भ से हल नहीं हो पाता है; उपयोग करें
-`askUserQuestion()` जब _UI_ को किसी विकल्प पर कार्रवाई करने की आवश्यकता होती है।
-
-## MCP ऐप होस्ट ब्रिज {#mcp-app-host-bridge}
-
-MCP ऐप्स के रूप में एम्बेड किए गए रूट URL-पहले होने चाहिए: वर्तमान आर्टिफैक्ट को यहां से लोड करें
-पथ/क्वेरी पैरामीटर, वास्तविक React मार्ग या एक केंद्रित साझा घटक प्रस्तुत करें,
-और होस्ट ब्रिज का उपयोग केवल होस्ट-स्वामित्व वाले व्यवहार के लिए करें। `@agent-native/core/client`
-सहायक एम्बेडेड रूट कॉल निर्यात करता है:
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()` नवीनतम पुश किए गए होस्ट संदर्भ स्नैपशॉट को पढ़ता है;
-`useMcpAppHostContext()` परिवर्तनों के लिए React घटकों की सदस्यता लेता है। अनुरोध
-सहायक (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
-`updateMcpAppModelContext`) एम्बेडेड MCP ऐप फ्रेम के बाहर `false` लौटाएं, या
-एक फ्रेम के अंदर `Promise<boolean>`। `sendToAgentChat()`
-एम्बेडेड मार्गों से स्वतः सबमिट किए गए संकेत।
-
-पुल स्वयं - `ui/*` JSON-RPC संदेश, `agentNative.mcpHost.*`
-रैपर रिले, ट्रांसप्लांट बनाम नियंत्रित-फ़्रेम रेंडरिंग, होस्ट संदर्भ, और
-डिस्प्ले-मोड अनुरोध - स्वामित्व
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## गतिशील सुझाव {#dynamic-suggestions}
-
-`<AgentSidebar>`, `<AgentPanel>`, और `<AssistantChat>` डिफ़ॉल्ट रूप से संदर्भ-जागरूक सुझावों के साथ स्थिर `suggestions` को मर्ज करते हैं। फ्रेमवर्क एप्लिकेशन स्थिति से `navigation`, `selection`, `pending-selection-context` और वर्तमान URL को पढ़ता है, जबकि एक खाली चैट दिखाई देती है, फिर वर्तमान स्क्रीन से मेल खाने वाले त्वरित चिप्स प्रदान करता है।
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-केवल स्थिर चिप्स रखने के लिए `dynamicSuggestions={false}` सेट करें। जब कोई ऐप समान एप्लिकेशन-स्टेट संदर्भ से नियतात्मक डोमेन-विशिष्ट चिप्स चाहता है तो `getSuggestions` पास करें।
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-React हुक जो लोडिंग स्थिति ट्रैकिंग के साथ sentToAgentChat को लपेटता है:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-जब आप `send()` पर कॉल करते हैं तो `isGenerating` सत्य हो जाता है और जब एजेंट जनरेट करना समाप्त कर देता है तो स्वचालित रूप से गलत पर रीसेट हो जाता है।
-
-## useDbSync(विकल्प?) {#usedbsync}
-
-React हुक (पूर्व में `useFileWatcher`) जो SSE पर डेटाबेस परिवर्तनों को सुनता है, पोलिंग पर वापस आ जाता है, और फ्रेमवर्क क्वेरी कैश को अमान्य कर देता है जो UI को एजेंट राइट्स के साथ संरेखित रखता है:
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### विकल्प {#usedbsync-options}
-
-| विकल्प             | प्रकार             | विवरण                                                                                      |
-| ------------------ | ------------------ | ------------------------------------------------------------------------------------------ |
-| `queryClient`      | `QueryClient?`     | कैश अमान्यकरण के लिए React-क्वेरी क्लाइंट                                                  |
-| `queryKeys`        | `string[]?`        | बहिष्कृत और उपेक्षित; पुरानी कॉल साइटों के लिए रखा गया                                     |
-| `pollUrl`          | `string?`          | पोल समापन बिंदु URL। डिफ़ॉल्ट: `"/_agent-native/poll"`                                     |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only     |
-| `interval`         | `number?`          | मतदान अंतराल एमएस में। डिफ़ॉल्ट: `2000`                                                    |
-| `fallbackInterval` | `number?`          | SSE अनुपलब्ध होने पर फ़ॉलबैक मतदान अंतराल। डिफ़ॉल्ट: `15000`                               |
-| `pauseWhenHidden`  | `boolean?`         | ब्राउज़र टैब छिपा होने पर मतदान रोकें। डिफ़ॉल्ट: `true`                                    |
-| `ignoreSource`     | `string?`          | प्रति-टैब अनुरोध स्रोत को अनदेखा करें ताकि कोई टैब अपने स्वयं के लेखन से पुनः प्राप्त न हो |
-| `onEvent`          | `(data) => void`   | वैकल्पिक कॉलबैक जब SSE/पोलिंग को एक परिवर्तन ईवेंट प्राप्त होता है                         |
-
-सामान्य CRUD के लिए, `useActionQuery` और `useActionMutation` को प्राथमिकता दें; actions को उत्परिवर्तित करने से `source: "action"` उत्सर्जित होता है और वे हुक स्वचालित रूप से पुनः प्राप्त हो जाते हैं।
-
-## यूजचेंजवर्जन / यूजचेंजवर्जन {#use-change-version}
-
-फ़्रेमवर्क React क्वेरी कैश को बैकग्राउंड एजेंटों, क्रॉन जॉब्स या अन्य उपयोगकर्ताओं द्वारा किए गए परिवर्तनों के साथ सिंक करने के लिए परिवर्तन संस्करणों का उपयोग करता है।
-
-जब कोई सर्वर-साइड डेटाबेस उत्परिवर्तन होता है, तो सर्वर एक विशिष्ट `source` कुंजी के साथ एक परिवर्तन ईवेंट रिकॉर्ड करता है। क्लाइंट का `useDbSync` श्रोता इन घटनाओं को प्राप्त करता है और उस स्रोत के लिए स्थानीय परिवर्तन संस्करण काउंटर को बंद कर देता है। संस्करण काउंटर को अपनी React क्वेरी कुंजियों में मोड़ने से, जब भी बैकएंड क्लाइंट को नई गतिविधि के बारे में सूचित करता है तो क्वेरीज़ स्वचालित रूप से पुनः प्राप्त हो जाती हैं।
-
-- **`useChangeVersion(source: string): number`** - एक काउंटर लौटाता है जो निर्दिष्ट `source` के उत्परिवर्तित होने पर बढ़ता है।
-- **`useChangeVersions(sources: readonly string[]): number`** - एकाधिक स्रोतों के लिए संस्करण काउंटरों का योग लौटाता है।
-
-### उदाहरण: डेटाबेस के साथ एक कच्ची क्वेरी को समन्वयित करना
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### विलंबता मॉडल और अमान्य व्यवहार
-
-- **UI-आरंभित उत्परिवर्तन:** जब आप `useActionMutation` का उपयोग करके UI से एक क्रिया निष्पादित करते हैं, तो उत्परिवर्तन तुरंत सफलता पर `source: "action"` के साथ एक स्थानीय घटना को सक्रिय करता है। यह उस क्रिया के आधार पर सभी क्वेरी कुंजियों का **तत्काल, आशावादी रीफ़ेच** ट्रिगर करता है, जिससे दृश्य विलंब से बचा जा सकता है।
-- **बैकग्राउंड या एजेंट म्यूटेशन:** जब एआई एजेंट, वेबहुक या बैकग्राउंड वर्कर डेटा को म्यूट करता है, तो अपडेट क्लाइंट को प्रसारित किया जाता है। क्लाइंट का `useDbSync` इसे या तो तुरंत SSE (सर्वर-भेजे गए इवेंट) पर कैप्चर करता है या **2-सेकंड पोलिंग टिक** पर वापस आ जाता है। इसके बाद क्वेरी कुंजी संस्करण चालू हो जाता है, जिससे पृष्ठभूमि रीफ़ेच ट्रिगर हो जाता है।
-
-<Diagram id="doc-block-1o7phrk" title={"रीफ़ेच के लिए दो रास्ते"} summary={"एक स्थानीय उत्परिवर्तन अपने स्वयं के कैश को तुरंत अमान्य कर देता है; एक दूरस्थ लेखन इस टैब पर SSE, या फ़ॉलबैक के रूप में पोलिंग टिक तक पहुंचता है।"}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">यह टैब</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">एजेंट · webhook · दूसरा टैब</span
-      ><strong>रिमोट लेखन</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...इनपुट) {#cn}
-
-वर्ग नामों को मर्ज करने की उपयोगिता (clsx + टेलविंड-मर्ज):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/hi-IN/drop-in-agent.mdx b/packages/core/docs/content/locales/hi-IN/drop-in-agent.mdx
index 3eeee27684..7c6d28d0d3 100644
--- a/packages/core/docs/content/locales/hi-IN/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/hi-IN/drop-in-agent.mdx
@@ -225,7 +225,7 @@ sendToAgentChat({
 
 जब उसी रूट को MCP ऐप के रूप में एम्बेड किया जाता है, सबमिट किया जाता है
 `sendToAgentChat()` कॉल होस्ट चैट पर अग्रेषित की जाती हैं जहां समर्थित है; देखें
-MCP ऐप ब्रिज व्यवहार के लिए [Client](/docs/client#sendtoagentchat)।
+MCP ऐप ब्रिज व्यवहार के लिए [एजेंट चैट](/docs/client-agent-chat#sendtoagentchat)।
 
 यदि आप लोडिंग स्थिति चाहते हैं, तो `useSendToAgentChat()` हुक का उपयोग करें - यह `send` और `isGenerating` दोनों लौटाता है:
 
diff --git a/packages/core/docs/content/locales/hi-IN/notifications.mdx b/packages/core/docs/content/locales/hi-IN/notifications.mdx
index 0543e07f53..6bfa648bb0 100644
--- a/packages/core/docs/content/locales/hi-IN/notifications.mdx
+++ b/packages/core/docs/content/locales/hi-IN/notifications.mdx
@@ -363,7 +363,7 @@ export function HeaderBar() {
 ## यह कैसे काम करता है {#internals}
 
 - **मालिक का दायरा** - प्रत्येक पंक्ति में एक `owner` कॉलम होता है; प्रत्येक क्वेरी इस पर फ़िल्टर होती है; प्रत्येक मार्ग प्रमाणित सत्र के ईमेल का उपयोग करता है। उपयोगकर्ता कभी भी एक-दूसरे की सूचनाएं नहीं देखते हैं।
-- **पोल एकीकरण** - प्रत्येक उत्परिवर्तन `recordChange()` को कॉल करता है इसलिए [`useDbSync`](/docs/client) का उपयोग करने वाले टेम्पलेट बिना किसी अतिरिक्त वायरिंग के स्वतः-अमान्य हो जाते हैं।
+- **पोल एकीकरण** - प्रत्येक उत्परिवर्तन `recordChange()` को कॉल करता है इसलिए [`useDbSync`](/docs/client-data#usedbsync) का उपयोग करने वाले टेम्पलेट बिना किसी अतिरिक्त वायरिंग के स्वतः-अमान्य हो जाते हैं।
 - **सर्वोत्तम प्रयास फैन-आउट** - चैनल त्रुटियां पकड़ी जाती हैं और लॉग की जाती हैं; एक असफल चैनल दूसरों को या इनबॉक्स लिखने को ब्लॉक नहीं करता है।
 - **आग लगाओ और भूल जाओ** - `notify()` इनबॉक्स लेखन पूरा होने के बाद वापस आता है; कस्टम चैनल पृष्ठभूमि में चलते हैं।
 
diff --git a/packages/core/docs/content/locales/hi-IN/progress.mdx b/packages/core/docs/content/locales/hi-IN/progress.mdx
index 266347bed3..e6c9a87125 100644
--- a/packages/core/docs/content/locales/hi-IN/progress.mdx
+++ b/packages/core/docs/content/locales/hi-IN/progress.mdx
@@ -233,7 +233,7 @@ mode: agentic
 ## यह कैसे काम करता है {#internals}
 
 - **मालिक का दायरा** - प्रत्येक पंक्ति में एक `owner` कॉलम होता है; प्रत्येक क्वेरी इस पर फ़िल्टर होती है। उपयोगकर्ता केवल अपने स्वयं के रन देखते हैं।
-- **पोल एकीकरण** - प्रत्येक उत्परिवर्तन `recordChange()` को कॉल करता है इसलिए [`useDbSync`](/docs/client) का उपयोग करने वाले टेम्पलेट बिना किसी अतिरिक्त वायरिंग के स्वतः-अमान्य हो जाते हैं।
+- **पोल एकीकरण** - प्रत्येक उत्परिवर्तन `recordChange()` को कॉल करता है इसलिए [`useDbSync`](/docs/client-data#usedbsync) का उपयोग करने वाले टेम्पलेट बिना किसी अतिरिक्त वायरिंग के स्वतः-अमान्य हो जाते हैं।
 - **तालिका का नाम** - फ्रेमवर्क में आंतरिक एजेंट-चैट टर्न जीवनचक्र ट्रैकिंग के लिए एक `agent_runs` तालिका भी है। दोनों चिंताओं को अलग रखने के लिए प्रोग्रेस प्रिमिटिव `progress_runs` का उपयोग करता है।
 - **प्रतिशत क्लैम्पिंग** - मानों को `[0, 100]` पर क्लैंप किया जाता है और लिखने पर एक पूर्णांक में पूर्णांकित किया जाता है।
 
@@ -241,4 +241,4 @@ mode: agentic
 
 - [**Notifications**](/docs/notifications) - काम खत्म होने पर उपयोगकर्ता को बताने के लिए `manage-progress` (`action=complete`) के साथ जोड़ी बनाएं
 - [**Automations**](/docs/automations) - वॉचडॉग `run.progress.updated` के माध्यम से धीमी गति से चलता है
-- [**Client**](/docs/client) - वास्तविक समय कैश अमान्यकरण के लिए `useDbSync`
+- [**डेटा और सिंक**](/docs/client-data) - वास्तविक समय कैश अमान्यकरण के लिए `useDbSync`
diff --git a/packages/core/docs/content/locales/hi-IN/real-time-collaboration.mdx b/packages/core/docs/content/locales/hi-IN/real-time-collaboration.mdx
index 564de61672..7458d944a9 100644
--- a/packages/core/docs/content/locales/hi-IN/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/hi-IN/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ description: "बहु-उपयोगकर्ता सहयोगात्
 एजेंट के साथ संपादन करना Google डॉक्स या फिग्मा में काम करने जैसा लगता है
 एक सहकर्मी जो त्वरित और अथक दोनों है:
 
-यदि आपको एजेंट या किसी अन्य उपयोगकर्ता द्वारा SQL को लिखने पर ताज़ा करने के लिए UI की आवश्यकता है, तो आपको इसकी कोई आवश्यकता नहीं है - [`useDbSync`](/docs/client) का उपयोग करें। यह पृष्ठ एकल समृद्ध-पाठ दस्तावेज़ (साझा कर्सर, संघर्ष-मुक्त विलय) के चरित्र-स्तरीय सह-संपादन के लिए है। दोनों एक ही `/_agent-native/poll` चैनल पर चलते हैं।
+यदि आपको एजेंट या किसी अन्य उपयोगकर्ता द्वारा SQL को लिखने पर ताज़ा करने के लिए UI की आवश्यकता है, तो आपको इसकी कोई आवश्यकता नहीं है - [`useDbSync`](/docs/client-data#usedbsync) का उपयोग करें। यह पृष्ठ एकल समृद्ध-पाठ दस्तावेज़ (साझा कर्सर, संघर्ष-मुक्त विलय) के चरित्र-स्तरीय सह-संपादन के लिए है। दोनों एक ही `/_agent-native/poll` चैनल पर चलते हैं।
 
 यह तीन युद्ध-परीक्षित प्रौद्योगिकियों पर बनाया गया है: **Yjs** (संघर्ष-मुक्त विलय के लिए CRDT), **टिपटैप** (रिच टेक्स्ट एडिटर), और **पोलिंग-आधारित सिंक** (सर्वर रहित और एज सहित सभी तैनाती वातावरण में काम करता है)।
 
@@ -774,7 +774,7 @@ undoManager.redo(); // Shift+Cmd+Z
 
 ## संबंधित दस्तावेज़ {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) - `useDbSync` + `useChangeVersion`
+- [सिंक इंटरनल्स](/docs/client-sync-internals) - `useDbSync` + `useChangeVersion`
   प्रणाली जो `updatedAt` बम्प ड्राइविंग एडिटर समाधान प्रदान करती है।
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   और संसाधन-स्कोप सहयोग के लिए `assertAccess`।
diff --git a/packages/core/docs/content/locales/hi-IN/routing.mdx b/packages/core/docs/content/locales/hi-IN/routing.mdx
deleted file mode 100644
index 91b0e58635..0000000000
--- a/packages/core/docs/content/locales/hi-IN/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "रूटिंग"
-description: "React राउटर v8 के साथ एजेंट-नेटिव ऐप्स के लिए फ़ाइल-आधारित रूटिंग - पेज, डायनामिक पैरामीटर और नेविगेशन।"
----
-
-# रूटिंग
-
-एजेंट-नेटिव ऐप्स `@react-router/fs-routes` से `flatRoutes()` के माध्यम से फ़ाइल-आधारित रूटिंग के साथ **React राउटर v8** का उपयोग करते हैं। `app/routes/` में प्रत्येक फ़ाइल URL बन जाती है। टेम्प्लेट डॉट-नोटेशन कन्वेंशन का उपयोग करते हैं - डॉट्स एक फ़ाइल नाम के अंदर URL सेगमेंट को अलग करते हैं।
-
-## फ़ाइल-आधारित रूटिंग {#file-based-routing}
-
-### फ़ाइल → URL मैपिंग
-
-| फ़ाइल                 | URL                | नोट्स                                  |
-| --------------------- | ------------------ | -------------------------------------- |
-| `_index.tsx`          | `/`                | सूचकांक मार्ग                          |
-| `settings.tsx`        | `/settings`        | सरल पृष्ठ                              |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | डॉट = `/`, `$` = गतिशील पैरामीटर       |
-| `_app.tsx`            | (कोई URL खंड नहीं) | पाथलेस लेआउट - `_` के साथ उपसर्ग       |
-| `inbox/route.tsx`     | `/inbox`           | फ़ोल्डर फॉर्म - `route.tsx` इंडेक्स है |
-
-डायनेमिक पैरामीटर के लिए `$` के साथ एक सेगमेंट को उपसर्ग करें। इसे एक पथहीन लेआउट मार्ग (कोई URL खंड नहीं) बनाने के लिए `_` के साथ उपसर्ग करें। टेम्प्लेट `flatRoutes()` का उपयोग करते हैं - उपरोक्त डॉट-नोटेशन फ़ाइल प्राथमिक है; नेस्टेड-फ़ोल्डर फॉर्म `inbox/route.tsx` भी काम करता है।
-
-<Diagram id="doc-block-1xvr59i" title={"पथहीन लेआउट पृष्ठों को लपेट देता है"} summary={"एक _app.tsx लेआउट (कोई URL खंड नहीं) साझा शेल को एक बार प्रस्तुत करता है; मिलान किए गए पृष्ठ इसके <आउटलेट/> के अंदर प्रस्तुत होते हैं, इसलिए एजेंट साइडबार कभी भी नेविगेशन पर प्रदर्शित नहीं होता है।"}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >pathless layout · स्थायी shell + एजेंट sidebar</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## एक नया पेज जोड़ना {#adding-a-page}
-
-फ़ाइल बनाएं और एक डिफ़ॉल्ट घटक निर्यात करें:
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-बस इतना ही - React राउटर इसे स्वचालित रूप से उठाता है, पंजीकरण की आवश्यकता नहीं है।
-
-## गतिशील पैरामीटर {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## नेविगेशन {#navigation}
-
-क्लाइंट-साइड नेविगेशन के लिए `<Link>` और प्रोग्रामेटिक नेविगेशन के लिए `useNavigate()` का उपयोग करें:
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## आगे क्या है
-
-- [**Client**](/docs/client) - एजेंट-मूल ब्राउज़र हुक और उपयोगिताएँ
-- [**Server**](/docs/server) - फ़ाइल-आधारित सर्वर रूट और `/_agent-native/` नेमस्पेस
diff --git a/packages/core/docs/content/locales/ja-JP/client-advanced.mdx b/packages/core/docs/content/locales/ja-JP/client-advanced.mdx
new file mode 100644
index 0000000000..861953af1c
--- /dev/null
+++ b/packages/core/docs/content/locales/ja-JP/client-advanced.mdx
@@ -0,0 +1,178 @@
+---
+title: "高度"
+description: "app/ の低レベルなプリミティブとエスケープ ハッチ: application_state への直接アクセス、バックグラウンドでのチャット送信、カスタム提案チップ、MCP アプリ ホスト ブリッジ。"
+---
+
+# 高度
+
+概要、データと同期、Agent チャット、Routing は典型的なケース、つまりほとんどのページが必要とするフックとヘルパーをカバーしています。このページでは、その下にある低レベルのプリミティブとより狭いエスケープ ハッチを扱います。ほとんどのアプリはこれらに直接触れることはありません。カスタムの選択同期や、埋め込み型の MCP アプリなど、デフォルトのフックがサポートするより凝ったものを構築するときに、これらに手を伸ばしてください。手書きのキーで生の `useQuery` を同期する場合は、代わりに [同期の内部](/docs/client-sync-internals) を参照してください。
+
+## アプリケーション状態 {#application-state}
+
+`application_state` は、エージェントが UI が現在何を見ているかを知るために読み取る SQL に裏付けられたキー/バリュー ストアで、ナビゲーション、選択、その他のフォーカスされたオブジェクトのコンテキストを含みます ([Context Awareness](/docs/context-awareness) を参照)。`useAgentRouteState` と `useSemanticNavigationState` (これも Context Awareness で扱われています) は、一般的なナビゲーションのケースについてこれらを既にラップしています。それらがカバーしていないもの、カスタムの選択の同期や、コンポーネントのレンダー フローの外からの書き込みなどを同期する必要があるときは、直接以下のプリミティブに手を伸ばしてください。
+
+### readClientAppState {#read-client-app-state}
+
+キーの現在の値を読み取ります。そのキーに最後に書き込まれた値、またはそのキーがまだ一度も書き込まれていない場合は `null` に解決されます。
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+キーに値を書き込みます。下記の `setClientAppState` とは異なり、`null` を渡した場合でも常に書き込みます。`undefined` を渡すと、`undefined` は有効な JSON ではないためスローされます。キーをクリアするには `setClientAppState(key, undefined)` または `deleteClientAppState()` を使用してください。
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+ほとんどの UI コードが使うべき便利なラッパーです。値を書き込むか、`null`/`undefined` を渡した場合はキーを削除します。呼び出し元が本当に「常に書き込み、決して削除しない」を必要としない限り、`writeClientAppState` の代わりにこれを使用してください。
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+キーを完全に削除します。
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+複数のキーを 1 回のリクエストで読み取ります。`{ values, missing }` を返します。`values` には、明示的に `null` として書き込まれたキーを含め、サーバーが行を持っているすべてのキーのエントリがあります。`missing` には、一度も書き込まれたことがないキーが列挙されます。これが、「一度も書き込まれていない」を「null として書き込まれた」と区別できる方法です。
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+100 個を超えるキーのリクエストは自動的に分割されます。`readClientAppState()` 自体はこの上に構築されています: 同じティックで発行された呼び出しは、裏で 1 回のリクエストにまとめられるため、1 回のレンダー パス内で何度も呼び出しても、1 回ごとに 1 リクエストではなく、合計で 1 回の往復になります。
+
+### オプション {#application-state-options}
+
+`signal` は上記の 5 つの関数すべてで受け付けられ、進行中の呼び出しをキャンセルします。`requestSource` と `keepalive` は、読み取りには意味がないため、3 つの書き込み関数にのみ適用されます。
+
+| オプション      | タイプ         | 適用対象                                                           | 説明                                                                                                               |
+| --------------- | -------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| `requestSource` | `string?`      | `writeClientAppState`、`setClientAppState`、`deleteClientAppState` | 書き込みに id をタグ付けし、対応する `useDbSync({ ignoreSource })` がその再フェッチをスキップできるようにします    |
+| `keepalive`     | `boolean?`     | `writeClientAppState`、`setClientAppState`、`deleteClientAppState` | リクエストがページのアンロードを超えて生存できるようにします。選択のクリアなどのクリーンアップ書き込みに使用します |
+| `signal`        | `AbortSignal?` | 5 つの関数すべて                                                   | リクエストをキャンセルします                                                                                       |
+
+### 失敗時の動作 {#failure-behavior}
+
+上記の 5 つの関数はすべて、リクエストの失敗、非 2xx レスポンス、パースできない本文の場合にスローします。スローされる `Error` は、サーバーが応答した場合には `.status` プロパティを持つため、呼び出し元が必要に応じて HTTP ステータスで分岐できます。呼び出しを `try`/`catch` で包むか、他のネットワーク呼び出しと同様にエラー バウンダリに伝播させてください。
+
+### TAB_ID とは {#tab-id}
+
+`requestSource` には、一般的に `TAB_ID` が設定されます。これは、すべてのテンプレートが `app/lib/tab-id.ts` からエクスポートする普通の定数で、タブの生存期間中は同じままで、タブ間で異なる短いランダムな文字列です。書き込み側で `requestSource: TAB_ID` を、読み取り側で `useDbSync({ ignoreSource: TAB_ID })` をペアリングすることが、タブが他の全員の変更には反応しつつ、自分自身の書き込みの再フェッチを避ける方法です。完全な手順については [Context Awareness](/docs/context-awareness#jitter-prevention) を参照してください。
+
+## sendToAgentChat: バックグラウンド送信 {#background-send}
+
+UI アクションが、サイドバーを開いたりフォーカスしたりせずに、実際のエージェントの作業を開始すべきときは `background: true` を使用してください。これでも通常のチャット スレッド/実行が作成され、エージェントのツール/アクション/コンテキストを使用し、実行トレイを通じて作業を監視可能な状態に保ちます。これは生の単発モデル呼び出しではありません。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` は `newTab` と組み合わせて使うことを意図しています。これにより、非表示の作業がユーザーの現在のアクティブな会話を上書きしないようにします。UI が後でフォローアップのステータスを関連付けたり、実行へディープリンクしたりする必要がある場合は、返された `tabId` を使用してください。
+
+[Agent チャット](/docs/client-agent-chat#agentchatmessage) でカバーされているものを超えた、もう少しの `AgentChatMessage` オプションがあります。主に埋め込みや下流の統合のためのケースです。
+
+| オプション            | タイプ      | 説明                                                                                     |
+| --------------------- | ----------- | ---------------------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | `newTab` と組み合わせて、タブをフォーカスせずに実行し、`RunsTray` に実行結果を表示します |
+| `projectSlug`         | `string?`   | 構造化されたコンテキストのためのオプションのプロジェクト スラグ                          |
+| `preset`              | `string?`   | 下流のコンシューマ向けのオプションのプリセット名                                         |
+| `referenceImagePaths` | `string[]?` | オプションの参照画像パス                                                                 |
+
+## MCP アプリ ホスト ブリッジ {#mcp-app-host-bridge}
+
+MCP アプリとして埋め込まれるルートは URL ファーストであるべきです。パス/クエリ パラメータから現在のアーティファクトをロードし、実際の React ルートかフォーカスされた共有コンポーネントをレンダリングし、ホスト ブリッジはホスト所有の振る舞いにのみ使用します。`@agent-native/core/client` は、埋め込みルートが呼び出すヘルパーをエクスポートします。
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` は、最後にプッシュされたホスト コンテキストのスナップショットを読み取ります。`useMcpAppHostContext()` は、React コンポーネントを変更にサブスクライブさせます。リクエスト用のヘルパー (`openMcpAppHostLink`、`requestMcpAppDisplayMode`、`updateMcpAppModelContext`) は、埋め込まれた MCP アプリ フレームの外では `false` を、フレーム内では `Promise<boolean>` を返します。
+
+`sendToAgentChat()` ([Agent チャット](/docs/client-agent-chat#sendtoagentchat) を参照) は、埋め込みルートからの自動送信されるプロンプトに同じブリッジを使用します。`embedApp()` で作成された MCP アプリ埋め込みの内側では、自動送信されるメッセージ (`submit` が省略、または `true`) はブリッジに転送され、ブリッジは埋め込みを含むホストに非表示のコンテキストを追加し、表示されるユーザー ターンを送信するよう要求します。`context` は、ユーザー向けチャットとして投稿されることなく、モデルに表示され続けます。`submit: false` は、MCP アプリが標準的なドラフト事前入力 API を定義していないため、ローカルな事前入力/レビューの動作を維持します。内部的にはこれは送信済みチャット パスで、時には `agentNative.submitChat` として表面化します。アプリのコードは、そのイベントを直接投稿するのではなく、`sendToAgentChat()` を呼び出すべきです。
+
+ブリッジ自体、`ui/*` の JSON-RPC メッセージ、`agentNative.mcpHost.*` ラッパー リレー、移植対制御フレーム レンダリング、ホスト コンテキスト、表示モードのリクエストは、[External Agents](/docs/external-agents#mcp-app-bridge) が所有します。プロトコル全体については [MCP Apps](/docs/mcp-apps) を参照してください。
+
+## カスタム提案チップ {#custom-suggestions}
+
+`<AgentSidebar>` の `dynamicSuggestions` ([Agent チャット](/docs/client-agent-chat#dynamic-suggestions) を参照) は、既に静的な `suggestions` とフレームワーク自身のコンテキスト認識ヒューリスティックをマージしています。フレームワークのデフォルトのヒューリスティックの代わりに、同じ `application_state` のコンテキストから計算された決定論的でドメイン固有のチップをアプリが求める場合は、代わりに `getSuggestions` を渡してください。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` は、組み込みのヒューリスティックが読み取るのと同じ `navigation`/`selection`/`pending-selection-context` のスナップショットを受け取るため、カスタムの実装は、汎用的なルールの代わりにアプリ固有のルールを使って、デフォルトの実装が反応するのと全く同じ状態に反応できます。
+
+## 次は何ですか
+
+- [**概要**](/docs/client-overview) — これらのプリミティブが存在する `app/` と `public/` のディレクトリ レイアウト
+- [**データと同期**](/docs/client-data) — 代わりに使うべきデフォルトのアクション フックと `useDbSync`
+- [**同期の内部**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` と、再フェッチが取りうる 2 つのレイテンシ パス
+- [**Agent チャット**](/docs/client-agent-chat) — 代わりに使うべきデフォルトの `sendToAgentChat`/`askUserQuestion` ヘルパーと、ステージングされたエージェント チャット コンテキスト状態 API
+- [**エントリーポイント**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` と SSR ストリーミングのカスタマイズ
+- [**Context Awareness**](/docs/context-awareness) — `application_state` の上に構築された `navigation`/`selection` のセマンティクスと、`TAB_ID`/ジッター防止の完全な手順
+- [**Generative UI**](/docs/generative-ui) — `askUserQuestion` を超えたより豊かなインライン チャット コントロール
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — MCP アプリ ホスト ブリッジの完全な内部構造
+  </content>
diff --git a/packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx b/packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx
new file mode 100644
index 0000000000..0b4d10eb39
--- /dev/null
+++ b/packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx
@@ -0,0 +1,312 @@
+---
+title: "Agent チャット"
+description: "エージェント チャットへのクライアント側のエントリーポイント: sendToAgentChat、openAgentSettings、askUserQuestion、動的な提案、useAgentChatGenerating、ステージングされたエージェント チャット コンテキスト状態。"
+---
+
+# Agent チャット
+
+アプリケーションのクライアントは、小さなクライアント ヘルパーのセットを通じてエージェントと話すことができます。プロンプトの送信、非表示コンテキストのステージング、ユーザーへのブロッキングな質問、エージェント パネルのオープンをカバーします。
+
+以下の例では、**Draft response** ボタンがエージェントにユーザーへの質問を促します。ユーザーが回答すると、エージェントは現在のページのコンテキストとユーザーの回答を念頭に置いて返信の作成を進めます。
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="実行履歴サイドバーを示す Dispatch アプリのスクリーンショット。"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Dispatch の実行履歴サイドバー。"
+/>
+
+## 仕組み
+
+Agent-Native が提供するクライアント ヘルパー メソッドを使用することで、UI はさまざまな方法でエージェントにユーザーとのやり取りを促すことができます。下の図は、ユーザーがクリックする "Draft response" ボタンが、応答を生成する前にエージェントにユーザーとのやり取りを促す様子を示しています。
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="「who owns each step」というタイトルのシーケンス図。App Code、UI、Agent の 3 つのライフラインを示す。ユーザーが「draft response」をクリックすると askUserQuestion() がトリガーされる。これはエージェント パネル内にインラインでレンダリングされることを説明する注記がある。ユーザーが返答すると、Agent 上で sendDraftRequest() が呼び出され、draft-ticket-reply を呼び出して、作成された返信を UI のコンポーザーに返す。"
+  align="full"
+  width={600}
+  caption="「Draft response」ボタンのフローを可視化したシーケンス図。"
+/>
+
+ユーザー エクスペリエンスは次のとおりです。
+
+1. ユーザーが **Draft response** ボタンをクリックすると、`askUserQuestion()` 関数が呼び出されます。質問はエージェント パネル内にインラインで表示され回答されます。
+
+1. ユーザーが **Offer a refund** を選ぶと、`sendDraftRequest()` がプロンプトとチケットのコンテキストをエージェントに送信します。
+
+1. エージェントが `draft-ticket-reply` [アクション](/docs/actions) を呼び出し、作成された返信が返信コンポーザーに表示されます。
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "質問、その選択肢、それがどのように振る舞うか。",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description: "完全な質問文。明確で具体的、疑問符で終わる。",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description: '非常に短いチップ/見出し。約 12 文字、例 `"Response"`。',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2〜4 個の異なる選択肢。各項目は `{ label, value?, description?, preview?, recommended? }`。`value` はデフォルトで `label` になります。",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            '自由記述の "Other" 選択肢を追加し、担当者が入力できるようにします。',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "単一選択の代わりに複数選択にします。",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description:
+            "エージェント パネルがポーリングするアプリケーション状態のキー。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      "選択された `value` (`allowMultiple` の場合は `value[]`)、担当者が入力した「Other」テキスト、またはスキップした場合は `null`。回答するまで保留状態のままです。エージェント パネルがマウントされている必要があります (すべてのテンプレートでマウントされています)。",
+  }}
+/>
+
+この関数は、アプリのコードからユーザーに多肢選択の質問をし、それをエージェント パネル内にインラインでレンダリングし、回答を待ちます。UI がエージェントの作業を開始する前に、2〜4 個の選択肢を持つ 1 つの小さな決定を必要とする場合に、カスタム モーダルを構築する代わりに使用します。
+
+以下の例では、チケット ページの「Draft Response」ボタンが、何かをエージェントに送信する前に、担当者にどう返信したいかを尋ねます。
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "`[isGenerating, send]` タプル。`isGenerating` は `send()` を呼び出した瞬間から、エージェント チャットの実行が停止を報告するまで `true` です。`send(opts)` は `sendToAgentChat()` と同じシグネチャを持ち、送信先のタブ id を返します。",
+  }}
+/>
+
+この React フックは、読み込み状態の追跡を加えて `sendToAgentChat()` をラップします。
+
+1. 1 番目の引数 `isGenerating` は、呼び出すと true になり、エージェントが生成を完了すると false にリセットされます。
+
+2. 2 番目の引数 `send()` は、`sendToAgentChat()` 関数を反映します。
+
+`isGenerating` は、実行が実際に開始し、停止を報告した場合にのみリセットされます。`submit: false` の呼び出しは、実行を開始せずにドラフトを事前入力するだけなので、その後は `isGenerating` が永久に `true` のままになります。このフックは `submit: true` の送信にのみ使用してください。事前入力のみの送信には `sendToAgentChat()` を直接呼び出してください。
+
+上記の `askUserQuestion()` の例とこれを組み合わせると、ボタンのハンドラーが完成します。
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="Draft Response ハンドラーを完成させる"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "読み込み状態 + 送信をひとつに",
+      note: "`useAgentChatGenerating()` は単純な `sendToAgentChat()` 呼び出しと同じタプル形状を返しますが、リクエストが処理中の間ボタンを無効化するための `isDrafting` を追加します。",
+    },
+    {
+      lines: "10-17",
+      label: "ask ステップを再利用",
+      note: "これは上のセクションとまったく同じ `askUserQuestion()` の呼び出しで、今回はボタン自身のハンドラー内にあります。",
+    },
+    {
+      lines: "18",
+      label: "使用前に絞り込む",
+      note: "戻り値の型は `allowMultiple` による `string[]` を常に許容するため、この呼び出しではそれを設定していなくてもこのチェックは必要です。",
+    },
+    {
+      lines: "20-25",
+      label: "選択を文章に変換",
+      note: "選択された値、または担当者自身が入力したテキストを、下のプロンプトが自然に読める言い回しにマッピングします。",
+    },
+    {
+      lines: "27-32",
+      label: "アクションと意図を名指しする",
+      note: "メッセージは、エージェントが正確にどのアクションを呼び出すべきか (`draft-ticket-reply`) を伝え、返信をそのまま送信しないよう念押しします。`openSidebar: true` は、サイドバーが閉じていた場合でも作成された返信が確実に見えるようにします。",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting がボタンを駆動する",
+      note: "`sendDraftRequest()` が処理中の間だけ無効化・再ラベル化されます。`askUserQuestion()` が担当者の回答を待っている間は、ボタンはクリック可能なままです。それは `sendDraftRequest()` が呼び出されるより前に発生するためです。",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+`postMessage` 経由でエージェント チャットにメッセージを送信します。これは `useAgentChatGenerating()` がラップしている、より低レベルのプリミティブで、UI のやり取りが自前の読み込み状態の追跡を必要としない場合に便利です。メッセージだけでは伝わらない追加の詳細には `context` を渡します。これは同じ表示メッセージに `<context>` タグで囲んで追加されます。ユーザーから隠されるわけではありません。すぐに送信するには `submit: true` を、ユーザーが最初にレビューするドラフトを事前入力するには `submit: false` を渡します。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| オプション    | タイプ     | 説明                                                                                                 |
+| ------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | チャットに送信されるプロンプト。設定されている場合、`context` はこの同じ表示メッセージに追加されます |
+| `context`     | `string?`  | 表示メッセージに `<context>` タグで囲んで追加される追加の詳細。ユーザーから隠されない                |
+| `submit`      | `boolean?` | true = 自動送信、false = 事前入力のみ                                                                |
+| `newTab`      | `boolean?` | このプロンプト用に別のチャット スレッドを作成する                                                    |
+| `openSidebar` | `boolean?` | サイドバーを開かずに送信/事前入力するには false を設定                                               |
+
+MCP アプリ埋め込み内からこれを実行する場合や、サイドバーを開かずに実行をバックグラウンドに送る方法は、いずれも [高度](/docs/client-advanced#background-send) で扱っています。
+
+## 動的な提案 {#dynamic-suggestions}
+
+会話が始まる前、`<AgentSidebar>`、`<AgentPanel>`、`<AssistantChat>` は空のチャットにプロンプト チップを表示します。デフォルトでは、これらは固定の `suggestions` リストだけではありません。フレームワークはアプリケーション状態から `navigation`、`selection`、`pending-selection-context`、現在の URL を読み取り、実際に画面に表示されているものに一致するチップをマージします。
+
+これは 2 つのチェックで行われます。何かが選択されている場合は、「Summarize this selection」のような汎用的なチップを追加します。それとは別に、多くのアプリが既に使用しているフィールド名 (メール スレッドの `threadId`/`emailId` や、チャートの `dashboardId`/`chartId` など) を `navigation` から探し、そのような画面に合わせたチップ (スレッドなら「Draft a reply」、チャートなら「Find anomalies in this data」など) を追加します。生成された結果は、静的な `suggestions` とマージされ、重複が除去され、`max` で上限が設けられます。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+現在の画面がヒューリスティックが認識するものに一致せず、何も選択されていない場合、チップは追加されず、空のチャットは静的な `suggestions` だけにフォールバックします。静的チップのみを保持するには `dynamicSuggestions={false}` を設定してください。アプリのナビゲーションの形が組み込みのヒューリスティックに一致しない場合、または完全に決定論的なアプリ固有のチップが欲しい場合は、[高度](/docs/client-advanced#custom-suggestions) を参照してください。
+
+## openAgentSettings(section?) {#openagentsettings}
+
+アプリの設定ページやセットアップ カードがエージェント サイドバーの設定タブを開くべきときは、`openAgentSettings()` を使用します。特定のセクションを開くには、`"llm"`、`"secrets"`、`"automations"`、`"voice"`、`"limits"` などのセクション id を渡します。
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+`agent-panel:open-settings` を直接ディスパッチするより、このヘルパーを優先してください。
+
+## Agent チャット コンテキスト状態 {#agent-chat-context-state}
+
+コンテキスト状態の API は、ステージングされたコンテキスト チップと双方向に同期する必要がある UI のためのオプションの配線です。コンポーザーの外で現在ステージングされている項目をレンダリングしたり、項目が既に添付されているかどうかを反映したり、明示的な削除/クリア操作を提供したりする場合に使います。
+
+単純な「これをエージェントに送信する」や「レビュー用にこのドラフトを事前入力する」フローには、これらのヘルパーに手を出さないでください。それらには [`sendToAgentChat()`](#sendtoagentchat) を `context` と `submit` と一緒に使用してください。
+
+| API                               | 使用する場合                                                                                |
+| --------------------------------- | ------------------------------------------------------------------------------------------- |
+| `useAgentChatContext()`           | React コンポーネントがステージングされたコンテキストのライブ リストを必要とする場合         |
+| `setAgentChatContextItem(item)`   | 命令型のコードが 1 つのキー付きコンテキスト項目をステージングまたは置換すべき場合           |
+| `listAgentChatContext()`          | 非 React コードがステージングされたコンテキストの一度限りのスナップショットを必要とする場合 |
+| `removeAgentChatContextItem(key)` | UI が安定した `key` によって 1 つのステージング済みコンテキスト項目を削除すべき場合         |
+| `clearAgentChatContext()`         | ビューやモードのリセット後など、UI がステージングされたコンテキストをすべてクリアすべき場合 |
+| `refreshAgentChatContext()`       | 命令型のコードが最新の永続化されたコンテキスト スナップショットを再読み込みすべき場合       |
+
+`useAgentChatContext()` は `{ items, set, remove, clear, refresh }` を返します。
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` は、現在ステージングされている項目を一度だけ確認する必要がある命令型のコード向けです。`clearAgentChatContext()` は意図的に広い範囲に対応します。選択が 1 つだけ変わった場合は `removeAgentChatContextItem(key)` を使用してください。
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| オプション    | タイプ     | 説明                                                                           |
+| ------------- | ---------- | ------------------------------------------------------------------------------ |
+| `key`         | `string`   | 既存のナゲットを置き換えるために使用される安定した識別子                       |
+| `title`       | `string`   | コンポーザーのチップに表示される短いラベル                                     |
+| `context`     | `string`   | 次に送信されるプロンプトに含まれる非表示のコンテキスト                         |
+| `openSidebar` | `boolean?` | デフォルトは true。コンテキストをサイレントにステージングするには false を渡す |
+
+## 次は何ですか
+
+- [**概要**](/docs/client-overview) — これらのヘルパーが `app/` の中でどこに位置するか
+- [**データと同期**](/docs/client-data) — UI 自体を最新に保つアクション フックと `useDbSync`
+- [**Drop-in Agent**](/docs/drop-in-agent) — これらのヘルパーがレンダリングされる場所を用意する `<AgentSidebar>`/`<AgentPanel>` のマウント
+- [**高度**](/docs/client-advanced) — バックグラウンド送信、カスタム提案チップ、MCP アプリ ホスト ブリッジ
+- [**Generative UI**](/docs/generative-ui) — `askUserQuestion` を超えたインライン チャット コントロールの構築
+  </content>
diff --git a/packages/core/docs/content/locales/ja-JP/client-data.mdx b/packages/core/docs/content/locales/ja-JP/client-data.mdx
new file mode 100644
index 0000000000..014f6ed1a7
--- /dev/null
+++ b/packages/core/docs/content/locales/ja-JP/client-data.mdx
@@ -0,0 +1,435 @@
+---
+title: "データと同期"
+description: "app/ がエージェントが呼び出すのと同じアクションを読み書きし、ライブ同期を保つためのアクション フック。"
+---
+
+# データと同期
+
+クライアント アプリケーションからアプリ データを読み書きする主な方法は、[アクション](/docs/actions) フックを通すことです。リクエストをアクションに埋め込むことで、クライアントとエージェントの両方が同じ方法でアプリケーションを操作できます。
+
+以下の例では、チケットがドロップダウンから手動で、続いてチャット エージェント経由で現在のユーザーに割り当てられます。UI とエージェントはどちらも同じアクションにアクセスします。
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="UI アクションとエージェント アクションが同じ結果になる例。"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="UI アクションとエージェント アクションが同じ結果になる例。"
+/>
+
+## データのフェッチと変更 {#fetching-mutating}
+
+典型的なアプリは独自の API 層を構築し、手書きの `fetch` リクエストでそれを呼び出します。agent-native アプリはそのレイヤーをスキップします。`app/` は、以下のフックを通じて、エージェントが既にツールとして持っている同じアクションを呼び出します。
+
+<Diagram id="doc-block-client-data-fm-1" title="典型的な fetch とアクション フックの比較" summary="典型的なコンポーネントは、それだけがアクセスできるルートを呼び出します。agent-native なコンポーネントは、エージェントも呼び出せるアクションを呼び出します。">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">典型的</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>自分の API ルート</strong>
+      <small class="diagram-muted">フロントエンドだけが呼び出せる</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>データベース</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead アクション</span>
+      <small class="diagram-muted">エージェント ツールでもある</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL データベース</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### アクション フック {#action-hooks}
+
+最もよく使うことになるアクション フックは 2 つあります。`useActionQuery()` と `useActionMutation()` です。これら 2 つのフックは、アプリのアクションへのアクセスを提供します。
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "アクションの登録名。",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "アクションの入力。`defineAction()` のスキーマから型付けされます。",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "[useQuery オプション](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) のすべて (`queryKey` と `queryFn` を除く。これらはフック自体が設定します)。",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      '`["action", name, params]` の下にキャッシュされます。手動の無効化なしで、変更アクションが完了するたびに自動的に再フェッチされます。',
+  }}
+/>
+
+このフックは、読み取り専用のアクションで使用することを意図しています。[useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) 関数の薄いラッパーです。
+
+以下の例では、`list-tickets` アクションが呼び出されます。これは、すべてのチケットに対して GET リクエストを行うのと似ています。
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+以下の例は、`get-ticket` アクションを通じて単一のチケットをフェッチするリクエストを示しています。クエリを特定のチケットのみに絞るために `ticketId` が渡されます。追加の `enabled` オプションは、クエリが自動的には実行されず、`ticketId` が存在する場合にのみ実行されるようにするために渡されます。
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "アクションの登録名。",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "[useMutation オプション](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) のすべて (`mutationFn` を除く。これはフック自体が設定します)。",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "デフォルトのリクエスト メソッドを上書きします。",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "成功時の自動キャッシュ更新をオプトアウトします。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      '成功すると `source: "action"` で変更イベントを発行するため、変更されたデータを読み取っているすべての `useActionQuery()` が自動的に再フェッチされます。手動の無効化は不要です。',
+  }}
+/>
+
+このフックは、作成、更新、送信など、データを変更するアクションで使用することを意図しています。[useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) 関数の薄いラッパーです。
+
+`useActionQuery()` とは異なり、アクションの入力はフック自体には渡されません。ミューテーションを実行する準備ができたときに `mutate()` または `mutateAsync()` に渡します。
+
+以下の例では、`send-ticket-reply` アクションが呼び出されて、チケットに返信が投稿されます。ボタンの `onClick` などのイベント ハンドラーから `mutate()` を呼び出します。
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+以下の例は、同じミューテーションを `onSuccess` オプション付きで示しています。キャッシュの無効化はすべてのミューテーションの後に自動的に発生するため、`onSuccess` は返信が送信された後に返信コンポーザーをクリアするなど、ローカルな副作用にのみ必要です。
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "アクションの登録名。",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "アクションの入力。`defineAction()` のスキーマから型付けされます。",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "以下はすべてオプションです。",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "デフォルトのリクエスト メソッドを上書きします。",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "リクエストをキャンセルします。",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "デフォルトの 60 秒のタイムアウトを、正当に時間がかかるアクションのために上書きします。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "上記のフックとは異なり、キャッシュも自動再フェッチもありません。結果に依存する他の UI がある場合は、手動の無効化と組み合わせてください。",
+  }}
+/>
+
+この関数は、プレーンなイベント ハンドラー、スクリプト、その他の非 React コード パスなど、React のレンダー フローの外側での命令的な単発アクション呼び出しのためのものです。フックの結果ではなく、直接プロミスを返します。
+
+以下の例では、`update-ticket` アクションがキーボード ショートカット ハンドラーから React のレンダー フローの外で呼び出され、チケットを担当者に割り当てます。
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+以下の例は、`timeoutMs` オプション付きの同じ呼び出しを示しています。デフォルトの 60 秒のタイムアウトより正当に長くかかるアクションに便利です。
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+すべての `useActionQuery()`、`useActionMutation()`、`callAction()` のリクエストは 60 秒のタイムアウトで制限されており、タイムアウトは黙って再試行されるのではなくエラーとして表面化します。`useActionQuery()` は、React Query の abort シグナルを使用して、上書きされたリクエストも自動的にキャンセルします。
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "すべてのフィールドはオプションです。",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description:
+            "キャッシュの無効化に使用する React Query クライアント。",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "ポーリング エンドポイントの URL。",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "SSE エンドポイントの URL。ポーリングのみを使うには `false` を渡します。",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "ポーリング間隔 (ミリ秒)。",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "SSE が接続されている間のバックアップとしてのポーリング間隔で、イベントが取り逃された場合に備えます。切断されたタブは、代わりにより速い `interval` (または固定のアイドル間隔) でポーリングします。",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "ブラウザのタブが非表示のときにポーリングを一時停止します。非表示のタブは SSE 接続を維持し、アクティブなときは 10 秒ごと、アイドル状態になると 60 秒ごとを上限にポーリングします。",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "無視するタブごとのリクエスト ソースで、タブが自身の書き込みから再フェッチしないようにします。",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "SSE またはポーリングが変更イベントを受信したときのオプションのコールバック。",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "アクション イベントがトリガーする広範な無効化をフィルタリングします。ほとんど必要ありません。通常のソース バージョン管理されたクエリが `useChangeVersion` を通じて反応し続ける一方で、高コストなアクティブ クエリを明示的なリフレッシュのセマンティクスに保つために使用します。",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "同期イベントがすべてのアクション クエリを無効化しないようにするアクション名。すでに独自の狭い無効化を実行している高頻度のバックグラウンド アクションにのみ使用します。",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description:
+            "非推奨で無視されます。古い呼び出し元のために残されています。",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+このフックは、エージェントの書き込み、webhook、別のブラウザ タブからの変更など、自分のアクションの外で発生するデータベースの変更に UI を同期させ続けることを意図しています。サーバー送信イベント経由で変更をリッスンし、サーバー送信イベントが利用できない場合はポーリングにフォールバックします。
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+通常の CRUD には `useActionQuery()` と `useActionMutation()` を優先してください。変更アクションは `source: "action"` を発行するため、それらのフックはすぐに再フェッチします。エージェント、webhook、または別のタブからの変更は、代わりに `useDbSync()` を通じて SSE またはポーリング フォールバック経由で届きます。生の `useQuery()` 呼び出しをカスタム キーで同期させる必要がある場合は、[同期の内部](/docs/client-sync-internals) を参照してください。`application_state` に直接書き込む必要がある場合は、[高度](/docs/client-advanced) を参照してください。
+
+## 次は何ですか
+
+- [**概要**](/docs/client-overview) — このページのフックが存在する `app/` と `public/` ディレクトリ レイアウト
+- [**Agent チャット**](/docs/client-agent-chat) — エージェントへのプロンプト送信とコンテキストのステージング
+- [**Actions**](/docs/actions) — このページのすべてのフックの背後にある `defineAction` サーフェス
+- [**高度**](/docs/client-advanced) — `application_state` への直接アクセス
+- [**同期の内部**](/docs/client-sync-internals) — `useChangeVersion` で生の `useQuery` を同期する
+- [**Real-Time Sync**](/docs/key-concepts#polling-sync) — `useDbSync` が UI を最新の状態に保つ方法
diff --git a/packages/core/docs/content/locales/ja-JP/client-entry-points.mdx b/packages/core/docs/content/locales/ja-JP/client-entry-points.mdx
new file mode 100644
index 0000000000..0e45faca80
--- /dev/null
+++ b/packages/core/docs/content/locales/ja-JP/client-entry-points.mdx
@@ -0,0 +1,28 @@
+---
+title: "エントリーポイント"
+description: "app/entry.client.tsx と app/entry.server.tsx: 薄いハイドレーションと SSR ブートストラップのラッパー、そしてストリーミングの振る舞いをカスタマイズするタイミング。"
+---
+
+# エントリーポイント
+
+`app/entry.client.tsx` はサーバーでレンダリングされた HTML をブラウザでハイドレートし、`app/entry.server.tsx` はその HTML をサーバー上でレンダリングします。どちらも React Router によって生成される薄いラッパーです。これらを編集する必要はほとんどありません。
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+これらに手を伸ばすのは、ストリーミングの振る舞いの変更など、高度な SSR のカスタマイズのためだけにしてください。通常のページ、レイアウト、データにはここでの変更は不要です。ページを追加する場合は、代わりに [Routing](/docs/client-routing) を参照してください。
+
+## 次は何ですか
+
+- [**概要**](/docs/client-overview) — これらのファイルが `app/` の中でどこに位置するか
+- [**Routing**](/docs/client-routing) — `app/` を拡張する通常の方法である、ページの追加
+- [**高度**](/docs/client-advanced) — その他の低レベルなクライアント プリミティブとエスケープ ハッチ
+  </content>
diff --git a/packages/core/docs/content/locales/ja-JP/client-overview.mdx b/packages/core/docs/content/locales/ja-JP/client-overview.mdx
new file mode 100644
index 0000000000..0fe2566051
--- /dev/null
+++ b/packages/core/docs/content/locales/ja-JP/client-overview.mdx
@@ -0,0 +1,206 @@
+---
+title: "概要"
+description: "app/ と public/ ディレクトリ: agent-native アプリの表示を組み立てる場所と、エージェントとの同期を保つブラウザ API。"
+---
+
+# 概要
+
+`app/` は、agent-native アプリの実際の表示を組み立てる場所です。ページ、レイアウト、コンポーネント、スタイルなど。 `public/` には、アイコン、マニフェスト、ブランド マークなど、それと一緒に配信される静的アセットが格納されています。これは典型的な React Router v8 アプリであり、特別なエージェント専用のサーフェスではありません。開発時間の大半はここに費やされます。
+
+典型的なフロントエンドとのアーキテクチャ上の唯一の違いは、このレイヤーには独自のバックエンド フォー フロントエンドがないことです。エージェントが呼び出すのと同じアクションを通じてデータを読み書きするため、ここで構築されたものは自動的にエージェントも実行できる機能になります。
+
+<Diagram id="doc-block-client-overview-1" title="従来のフロントエンド vs. Agent Native" summary="従来のフロントエンドは、それ専用の API 層を呼び出します。Agent Native では、app/ とエージェントの両方が同じアクションを呼び出すため、ここで構築されるすべての機能が無料でエージェント呼び出し可能になります。">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">従来</div>
+    <div class="diagram-node">app/ (React フロントエンド)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API 層</strong>
+      <small class="diagram-muted">フロントエンドだけが呼び出せる</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>データベース</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React フロントエンド)</div>
+      <div class="diagram-node">エージェント</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">対等なパートナー、同じ操作</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL データベース</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## クライアントが担う役割 {#role}
+
+ブラウザからのリクエスト、エージェント ループ、外部 API クライアントは、すべて同じアクションと同じ SQL データベースに解決されます。このレイヤーがエージェントの手が届かない「アプリのバックエンド」に別途話しかけることはありません。ここで機能を構築するということは、エージェントが既に持っている操作の上に UI を構築すること、または新しいアクションを定義して同時にその UI も手に入れることを意味します。この契約の操作側については [Actions](/docs/actions) を参照してください。
+
+このページでは、`app/` の中で作業するディレクトリと、他のどこにも文書化されていないブラウザ ランタイムの部分 (`root.tsx`、`public/`) を扱います。コンポーネントをアクションやエージェントに接続する React フックは、それぞれ専用のページで扱っています。
+
+| ページ                                              | 内容                                                                                                                            |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| **[データと同期](/docs/client-data)**               | `useActionQuery`、`useActionMutation`、`callAction`、`useDbSync`                                                                |
+| **[Agent チャット](/docs/client-agent-chat)**       | `sendToAgentChat`、`askUserQuestion`、`openAgentSettings`、動的な提案、ステージングされたエージェント チャット コンテキスト状態 |
+| **[高度](/docs/client-advanced)**                   | `application_state` への直接アクセス、バックグラウンドでのチャット送信、カスタム提案チップ、MCP アプリ ホスト ブリッジ          |
+| **[同期の内部](/docs/client-sync-internals)**       | 生の `useQuery` を同期するための `useChangeVersion`/`useChangeVersions`                                                         |
+| **[エントリーポイント](/docs/client-entry-points)** | `app/entry.client.tsx`/`app/entry.server.tsx` と SSR のカスタマイズ                                                             |
+
+## app/ と public/ の内容 {#project-directories}
+
+| パス                                                | 内容                                                                                                                                |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | HTML シェルとプロバイダー スタック — 下記の [ブラウザ シェル](#app-shell) を参照                                                    |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | ハイドレーションと SSR のブートストラップ — [エントリーポイント](/docs/client-entry-points) を参照                                  |
+| **`app/routes.ts` + `app/routes/`**                 | ファイルベースのページとナビゲーション — [Routing](/docs/client-routing) を参照                                                     |
+| **`app/components/`**                               | 自分の UI: shadcn スタイルのプリミティブとアプリ固有のコンポーネント — [shadcn/ui](/docs/shadcn-ui) を参照                          |
+| **`app/hooks/`**                                    | データ、同期、エージェント チャットのフック — [データと同期](/docs/client-data) と [Agent チャット](/docs/client-agent-chat) を参照 |
+| **`app/lib/`**                                      | 共有クライアント ユーティリティ (アプリ設定、タブ id、`cn`) — 下記の [ユーティリティ](#utilities) を参照                            |
+| **`app/design-system.ts`**                          | オプションのカスタム デザイン システム アダプター — [カスタム デザイン システム](/docs/custom-design-system) を参照                 |
+| **`app/i18n/`**                                     | ローカライズされた UI 文言のカタログ — [Internationalization](/docs/internationalization) を参照                                    |
+| **`app/global.css`**                                | 基本スタイルと Tailwind のエントリーポイント                                                                                        |
+| **`public/`**                                       | そのまま配信される静的アセット — 下記の [静的アセット](#public-directory) を参照                                                    |
+
+## ブラウザ シェル: root.tsx と AppProviders {#app-shell}
+
+`app/root.tsx` は React ツリーの最上位です。HTML ドキュメント シェル (`<html>`、`<head>`、`<Meta>`、`<Links>`、`<Scripts>`) と、すべてのルートがその内側でレンダリングされるプロバイダー スタックです。
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` は、次のものを配線する単一のラッパーです。
+
+- `useActionQuery`/`useActionMutation` が使用する React Query クライアント ([データと同期](/docs/client-data#fetching-mutating) を参照)。
+- `i18n.catalog` として渡される i18n カタログ ([Internationalization](/docs/internationalization) を参照)。
+- クライアント側のセッション チェック: プライベート パスでは、匿名の訪問者はプライベート UI がマウントされる前にサインインへリダイレクトされます。パブリック/SEO ルートには `isPublicPath` を、MCP 埋め込みトークンなど別の方法で認証されるサーフェスには `sessionBypass` を渡します。[Authentication](/docs/authentication) を参照してください。
+
+多くのアプリはここで `<AgentSidebar>` または `<AgentPanel>` もマウントし、すべてのルートで無料でエージェント パネルを利用できるようにします。[Drop-in Agent](/docs/drop-in-agent#sidebar) を参照してください。
+
+## 静的アセット: public/ {#public-directory}
+
+`public/` の内容はすべて、ビルドで処理されずにサイトのルートでそのまま配信されます。すべてのテンプレートに次が含まれます。
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+`manifest.json` は、訪問者がアプリをホーム画面やアプリ ドックにインストールした場合に表示される内容 (名前、短い名前、テーマ/背景色、アイコン セット) を制御します。
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+これらのファイルを置き換えて `manifest.json` と、それらを参照する `root.tsx` 内の `<link rel="icon">`/`<link rel="apple-touch-icon">` タグを更新するだけでアプリをリブランドできます。別途の登録手順はありません。既存のサイトから完全なブランド システム (色、フォント、favicon) を取得する場合は、これらのファイルを手作業で編集する代わりに [Brand Systems and Figma](/docs/template-design-brand-and-figma) を参照してください。
+
+## ユーティリティ: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` はクラス名をマージします (clsx + tailwind-merge)。これは、`app/components/` 全体で条件付きの Tailwind クラスを組み合わせる標準的な方法です。
+
+## 次は何ですか
+
+- [**データと同期**](/docs/client-data) — アクション フックと `useDbSync`
+- [**Agent チャット**](/docs/client-agent-chat) — `sendToAgentChat`、`askUserQuestion`、動的な提案
+- [**高度**](/docs/client-advanced) — アプリケーション状態、バックグラウンドでのチャット送信、MCP アプリ ホスト ブリッジ
+- [**同期の内部**](/docs/client-sync-internals) — 生の `useQuery` を同期する `useChangeVersion`
+- [**エントリーポイント**](/docs/client-entry-points) — SSR ブートストラップのカスタマイズ
+- [**Routing**](/docs/client-routing) — ファイルベースのページ、動的パラメータ、ナビゲーション
+- [**Actions**](/docs/actions) — すべてのデータ フックの背後にある `defineAction` サーフェス
+- [**カスタム デザイン システム**](/docs/custom-design-system) — `app/design-system.ts` で独自のコンポーネント ライブラリに切り替える
+- [**Authentication**](/docs/authentication) — `AppProviders` がプライベート パスで実行するセッション チェック
diff --git a/packages/core/docs/content/locales/ja-JP/client-routing.mdx b/packages/core/docs/content/locales/ja-JP/client-routing.mdx
new file mode 100644
index 0000000000..d66a706b1b
--- /dev/null
+++ b/packages/core/docs/content/locales/ja-JP/client-routing.mdx
@@ -0,0 +1,122 @@
+---
+title: "Routing"
+description: "React Router v8 を使った agent-native アプリのファイルベース ルーティング: ページ、動的パラメータ、ナビゲーション。"
+---
+
+# Routing
+
+agent-native アプリは、`@react-router/fs-routes` の `flatRoutes()` によるファイルベース ルーティングで **React Router v8** を使用します。`app/routes/` 内のすべてのファイルが URL になります。テンプレートはドット記法の規則を使用します。ドットは単一のファイル名内で URL のセグメントを区切ります。
+
+このページでは、ブラウザ内でレンダリングされるページである、クライアント ルート (`app/routes/` から) を扱います。サーバー ルートは別のシステムです: `server/routes/` の下にある Nitro のファイル ルートと、フレームワーク自身の `/_agent-native/*` エンドポイントです。それらは [Routes](/docs/server-routes) ページにあります。この 2 つはディレクトリ、命名規則、ルーターのいずれも共有していません。そのため、`server/routes/` のファイルがここでページになることはなく、`app/routes/` のファイルがサーバー エンドポイントになることもありません。
+
+<Diagram id="doc-block-client-routing-1" title="ファイル名 → URL" summary="app/routes/ 内の各ファイルが URL になります。ドットはスラッシュになり、$ セグメントは動的パラメータになります。">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## ファイルベース ルーティング {#file-based-routing}
+
+### ファイル → URL のマッピング
+
+| ファイル                   | URL                    | 補足                                                                                         |
+| -------------------------- | ---------------------- | -------------------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | インデックス ルート                                                                          |
+| `dashboard.tsx`            | `/dashboard`           | 単純なページ                                                                                 |
+| `extensions.$id.tsx`       | `/extensions/:id`      | `extensions.tsx` の `<Outlet/>` 内にネストされます。`$` は動的パラメータです                 |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | 末尾の `_` によって `dashboard.tsx` へのネストがスキップされるため、これは独立したページです |
+| `_app.tsx`                 | (URL セグメントなし)   | パスレス レイアウト。`_` を接頭辞にします                                                    |
+| `inbox/route.tsx`          | `/inbox`               | フォルダ形式。`route.tsx` がインデックスです                                                 |
+
+セグメントに `$` を接頭辞として付けると動的パラメータになります。`_` を接頭辞に付けるとパスレスなレイアウト ルート (URL セグメントなし) になり、ドットの前に末尾の `_` を追加すると、ネストしているように見えるパスをその親のレイアウトへのネストからオプトアウトさせます。テンプレートは `flatRoutes()` を使用します。上記のドット記法のファイルが基本形です。ネストされたフォルダ形式 `inbox/route.tsx` も動作します。
+
+## ページの追加 {#adding-a-page}
+
+ファイルを作成し、デフォルトのコンポーネントをエクスポートします。
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+これだけです。React Router が自動的にそれを検出します。登録は不要です。
+
+## 動的パラメータ {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+ドットの前の末尾の `_` によって、このページは `dashboard.tsx` の `<Outlet/>` 内にネストされず、チケット キューのレイアウトの中に表示されるのではなく、`/dashboard/:ticketId` で独立したフルページとしてレンダリングされます。
+
+## ナビゲーション {#navigation}
+
+クライアント側のナビゲーションには `<Link>` を、プログラムによるナビゲーションには `useNavigate()` を使用します。
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+どちらも、それ単独ではエージェントにユーザーが何を見ているかを伝えません。それは別の関心事で、`useAgentRouteState()` が現在のルートをアプリケーション状態に書き込むことで処理されます。[Context Awareness](/docs/context-awareness) を参照してください。
+
+## 次は何ですか
+
+- [**概要**](/docs/client-overview) — `app/routes/` が `app/` と `public/` の残りの中でどこに位置するか
+- [**データと同期**](/docs/client-data) — ルート内からのデータの読み書き
+- [**Agent チャット**](/docs/client-agent-chat) — ルートからのプロンプト送信とコンテキストのステージング
+- [**Routes**](/docs/server-routes) — 別のサーバー ルーティング システム: `server/routes/` 内のファイル ルートとフレームワークの `/_agent-native/` 名前空間
+- [**Context Awareness**](/docs/context-awareness) — エージェントが現在のルートと選択を学習する方法
+  </content>
diff --git a/packages/core/docs/content/locales/ja-JP/client-sync-internals.mdx b/packages/core/docs/content/locales/ja-JP/client-sync-internals.mdx
new file mode 100644
index 0000000000..5b6198d254
--- /dev/null
+++ b/packages/core/docs/content/locales/ja-JP/client-sync-internals.mdx
@@ -0,0 +1,125 @@
+---
+title: "同期の内部"
+description: "useDbSync の背後にある変更バージョンの仕組み: 生の useQuery を同期するための useChangeVersion/useChangeVersions と、再フェッチが取りうる 2 つのレイテンシ パス。"
+---
+
+# 同期の内部
+
+[Live Sync](/docs/key-concepts#polling-sync) はメンタル モデルをカバーしています: エージェントの書き込みが変更イベントになり、`useDbSync()` がそれを取り込み、影響を受けるクエリが再フェッチされる、という流れです。このページでは、ほとんどのアプリが直接触れることのない、その下にある仕組みをカバーします。`useDbSync()` がインクリメントする変更バージョン カウンターと、`useActionQuery()` を経由していない生の `useQuery()` 呼び出しにそれらを組み込む方法です。
+
+`useActionQuery()` は、変更アクションが完了すると既に自動的に再フェッチします ([データと同期](/docs/client-data#fetching-mutating) を参照)。`useChangeVersion()`/`useChangeVersions()` に手を伸ばすのは、統合ステータスを読み取る低レベルのクライアント ヘルパーなど、そのパスの外で生の `useQuery()` 呼び出しを同期させている場合だけです。
+
+## 変更バージョンの仕組み {#how-it-works}
+
+サーバー側のデータベースの変更が発生すると、サーバーは `source` キーでタグ付けされた変更イベントを記録します。`useDbSync()` はそのイベントを受け取り、そのソースのローカル カウンターをインクリメントします。カウンターを React Query のキーに組み込むことで、バックエンドがそのソースの新しいアクティビティを報告するたびに、クエリが自動的に再フェッチされます。
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description: '監視する変更イベントのソース。例: `"dashboards"`。',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description:
+      "指定されたソースが変更されるたびにインクリメントされるカウンター。",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "一度に監視する複数の変更イベントのソース。",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "指定されたソースそれぞれのバージョン カウンターの合計。",
+  }}
+/>
+
+以下の例では、生の `useQuery()` 呼び出しがダッシュボードを直接読み取り、そのソースが変更されるたびに再フェッチされるように `"dashboards"` ソースのバージョン カウンターをクエリ キーに組み込んでいます。
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` は、再フェッチ中に前のデータを画面に残すため、ビューが読み込み状態にちらつきません。
+
+## 再フェッチへの 2 つのパス {#latency-models}
+
+ミューテーションは 2 つの方法のいずれかで UI に到達し、それぞれレイテンシが異なります。
+
+自分の `useActionMutation()` 呼び出しが行ったローカルなミューテーションは、成功するとすぐに `source: "action"` イベントを発行します。そのアクションに依存するすべてのクエリはすぐに再フェッチされます。書き込みを行ったタブが既にその変更を知っているため、往復の遅延はありません。
+
+エージェント、webhook、別のタブ、別のユーザーによるリモートなミューテーションは、まずこのタブに到達する必要があります。`useDbSync()` は、SSE 経由でほぼ即座にそれを取り込むか、SSE が利用できない場合はポーリング フォールバックで約 2 秒以内に取り込みます。そのイベントが到着してからようやく、関連するバージョン カウンターがインクリメントされ、クエリがバックグラウンドで再フェッチされます。
+
+<Diagram id="doc-block-client-sync-internals-3" title="再フェッチへの 2 つのパス" summary="ローカルなミューテーションは自身のキャッシュを即座に無効化します。リモートの書き込みは SSE、またはフォールバックとしてのポーリングを介してこのタブに到達します。">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">このタブ</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >fires source: "action" on success &rarr; instant local refetch</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">エージェント · webhook · 別のタブ</span
+      ><strong>リモートの書き込み</strong
+      ><small class="diagram-muted"
+        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
+        &rarr; background refetch</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## 次は何ですか
+
+- [**Live Sync**](/docs/key-concepts#polling-sync) — このページがその下で扱う、概念的なメンタル モデル
+- [**データと同期**](/docs/client-data) — これらのプリミティブの代わりにほとんどのページで使うべき `useActionQuery`/`useDbSync`
+- [**高度**](/docs/client-advanced) — その他の低レベルなクライアント プリミティブとエスケープ ハッチ
+  </content>
diff --git a/packages/core/docs/content/locales/ja-JP/client.mdx b/packages/core/docs/content/locales/ja-JP/client.mdx
deleted file mode 100644
index 4c81a53a13..0000000000
--- a/packages/core/docs/content/locales/ja-JP/client.mdx
+++ /dev/null
@@ -1,470 +0,0 @@
----
-title: "クライアント"
-description: "エージェント ネイティブ アプリ用の React フックとユーティリティ: sendToAgentChat、オプションのエージェント チャット コンテキスト状態、useDbSync、useAgentChatGenerating、および cn。"
----
-
-# クライアント
-
-`@agent-native/core` は、エージェント ネイティブ アプリのブラウザ側に React フックとユーティリティを提供します。
-
-これらのクライアント/React API は、`@agent-native/core` と `@agent-native/core/client` の両方からエクスポートされます。ベア `@agent-native/core` ルートはデフォルトでノード ビルドに解決されるため、明確にして正しいバンドルを実現するために、`@agent-native/core/client` (ブラウザ エントリ) からインポートします。
-
-ファイルベースのルーティング (ページ、動的パラメータ、ナビゲーションの追加) については、[Routing](/docs/routing) を参照してください。
-
-## データのフェッチと変更 {#fetching-mutating}
-
-ブラウザからアプリ データを読み書きする主な方法は、アクション フックを使用することです。 `fetch` 呼び出しを `/_agent-native/*` ルートに手書きしないでください。代わりに名前付きヘルパーを使用してください ([Actions](/docs/actions) を参照)。
-
-<Diagram id="doc-block-14hiq5q" title={"ブラウザのデータループ"} summary={"フックはアクションを通じて読み取りと書き込みを行います。 useDbSync はデータベースを監視し、エージェントとバックグラウンドの書き込みが同じキャッシュを自動的に再取得するようにします。"}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>SQLデータベース</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(opts) {#sendtoagentchat}
-
-postMessage 経由でエージェント チャットにメッセージを送信します。これは、UI インタラクションから AI タスクを委任する一般的な方法です。非表示のモデル コンテキストには `context` を渡し、すぐに送信するには `submit: true` を、ユーザーが最初にレビューするドラフトを事前入力するには `submit: false` を渡します。
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-`embedApp()` で作成された MCP アプリ埋め込み内、自動送信メッセージ
-(`submit` 省略または `true`) は MCP アプリ ホスト ブリッジに転送されます。
-包含ホストに、非表示のコンテキストを追加し、表示されるユーザー ターンを送信するように要求します。
-`context` は、ユーザー向けチャットとして投稿されずに、モデルに表示されたままになります。
-MCP アプリはローカルの事前入力/レビュー動作を維持しないため、`submit: false` はローカルの事前入力/レビュー動作を維持します
-標準のドラフトプレフィル API を定義します。内部的には、これは送信されたチャット パスです
-`agentNative.submitChat` として現れることもあります。アプリコードは
-そのイベントを直接投稿するのではなく、`sendToAgentChat()`。
-
-### サイレントバックグラウンド送信 {#background-send}
-
-UI アクションが実際のエージェントの作業を開始する必要がある場合は、`background: true` を使用します
-サイドバーを開くか、フォーカスします。これでも通常のチャット スレッド/実行が作成されます。
-エージェントの tools/actions/context を使用し、作業を監視可能な状態に保ちます
-ラントレイ。これは生のワンショット モデル呼び出しではありません。
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` は `newTab` とペアになるように設計されているため、非表示の作業は行われません
-overwrite the user's active conversation. Use the returned `tabId` if the UI
-後でフォローアップ ステータスを関連付けたり、実行にディープリンクしたりする必要があります。
-
-### エージェントチャットメッセージ {#agentchatmessage}
-
-| オプション            | タイプ      | 説明                                                                            |
-| --------------------- | ----------- | ------------------------------------------------------------------------------- |
-| `message`             | `string`    | チャットに送信される表示されるプロンプト                                        |
-| `context`             | `string?`   | 非表示のコンテキストが追加されました (チャット UI には表示されません)           |
-| `submit`              | `boolean?`  | true = 自動送信、false = 事前入力のみ                                           |
-| `newTab`              | `boolean?`  | このプロンプトに対して別のチャット スレッドを作成します                         |
-| `background`          | `boolean?`  | `newTab` では、タブをフォーカスせずに実行し、実行結果を `RunsTray` に表示します |
-| `openSidebar`         | `boolean?`  | サイドバーを開かずに送信/事前入力するには false を設定します                    |
-| `projectSlug`         | `string?`   | 構造化コンテキストのオプションのプロジェクト スラグ                             |
-| `preset`              | `string?`   | ダウンストリーム コンシューマのオプションのプリセット名                         |
-| `referenceImagePaths` | `string[]?` | オプションの参照画像パス                                                        |
-
-## エージェント チャット コンテキストの状態 (詳細) {#agent-chat-context-state}
-
-コンテキスト状態の API は、双方向同期を必要とする UI のオプションのプラミングです。
-ステージングされたコンテキスト チップ: 現在のステージングされたアイテムをコンポーザーの外部でレンダリングします。
-項目がすでに添付されているかどうかを反映するか、明示的に提供する
-コントロールを削除/クリアします。
-
-単純に「これをエージェントに送信する」目的でこれらのヘルパーにアクセスしないでください。
-「レビューのためにこのドラフトを事前入力する」フロー。 `sendToAgentChat()` を `context` と一緒に使用する
-それらについては `submit`。
-
-| API                               | 次の場合に使用します                                                                                  |
-| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `useAgentChatContext()`           | React コンポーネントにはライブ ステージングされたコンテキスト リストが必要です                        |
-| `setAgentChatContextItem(item)`   | 命令型コードは 1 つのキー付きコンテキスト項目をステージングまたは置換する必要があります               |
-| `listAgentChatContext()`          | 非 React コードには、ステージングされたコンテキストの 1 回限りのスナップショットが必要です            |
-| `removeAgentChatContextItem(key)` | UI は、安定した `key` によって 1 つの段階的コンテキスト項目を削除する必要があります                   |
-| `clearAgentChatContext()`         | UI は、ビューやモードのリセット後など、ステージングされたコンテキストをすべてクリアする必要があります |
-| `refreshAgentChatContext()`       | 命令型コードは、永続化された最新のコンテキスト スナップショットを再読み取りする必要があります         |
-
-`useAgentChatContext()` は `{ items, set, remove, clear, refresh }` を返します。
-
-## openAgentSettings(セクション?) {#openagentsettings}
-
-アプリ設定ページまたはセットアップ カードを開く必要がある場合は、`openAgentSettings()` を使用してください
-エージェント サイドバーの [設定] タブ。 `"llm"`、`"secrets"` などのセクション ID を渡します。
-`"automations"`、`"voice"`、または `"limits"` を使用して特定のセクションを開きます。
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-`agent-panel:open-settings` を直接ディスパッチするよりも、このヘルパーを優先します。
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` は、
-現在ステージングされているアイテムを 1 回。 `clearAgentChatContext()` は意図的に幅広くなっています。使用
-選択項目が 1 つだけ変更された場合は `removeAgentChatContextItem(key)`。
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| オプション    | タイプ     | 説明                                                                            |
-| ------------- | ---------- | ------------------------------------------------------------------------------- |
-| `key`         | `string`   | 既存のナゲットを置き換えるために使用される安定した識別子                        |
-| `title`       | `string`   | コンポーザーチップに表示される短いラベル                                        |
-| `context`     | `string`   | 次に送信されるプロンプトに含まれる非表示のコンテキスト                          |
-| `openSidebar` | `boolean?` | デフォルトは true です。 false をステージングコンテキストにサイレントに渡します |
-
-## ユーザーに質問する(オプション) {#ask-user-question}
-
-アプリコードからユーザーに多肢選択の質問をし、それをインラインでレンダリングします
-エージェントパネルに進み、**回答を待ちます**。これは、
-エージェントの組み込み `ask-question` ツール: `GuidedQuestionPayload` を
-`"guided-questions"` アプリケーション状態キー (マウントされた場所
-`GuidedQuestionFlow` がそれをレンダリングし、エージェント パネルが表示されるので、質問は次のとおりです。
-表示されます。回答がエージェントに返されるエージェント ツールとは異なります。
-`askUserQuestion()` **発信者への応答で解決**するため、UI は
-その上で分岐します。
-
-UI がその前に 1 つの小さな決定 (2 ～ 4 つの選択肢) を必要とする場合に使用します
-カスタム モーダルを構築するのではなく、エージェントの作業を開始します。
-フリーフォーム詳細用のコンポーザと、複数フィールド入力用のフォーム/ポップオーバー。
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-各オプションは `{ label, value?, description?, preview?, recommended? }` です。 `value`
-デフォルトは `label` で、`preview` は
-option. The promise resolves with the selected `value` (or `value[]` when
-`allowMultiple`)、ユーザーが「その他」を選択した場合のフリーテキスト文字列、または `null`
-スキップした場合、ユーザーが応答するまで保留状態になります。エージェントパネルが必要
-マウントされます (すべてのテンプレートにあります)。
-
-エージェントは `ask-question` ツールを通じて同じ UI に到達します。
-エージェントは、_it_ がコンテキストから解決できない本物のフォークにヒットしたときに尋ねます。使用
-`askUserQuestion()` _UI_ が選択肢に基づいてアクションを制御する必要がある場合。
-
-## MCP アプリホストブリッジ {#mcp-app-host-bridge}
-
-MCP アプリとして埋め込まれたルートは URL ファーストである必要があります: 現在のアーティファクトをロードします
-パス/クエリ パラメータ、実際の React ルートまたはフォーカスされた共有コンポーネントをレンダリングします。
-ホストブリッジはホスト所有の動作にのみ使用します。 `@agent-native/core/client`
-ヘルパーに埋め込まれたルート呼び出しをエクスポートします:
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()` は、プッシュされた最新のホスト コンテキスト スナップショットを読み取ります。
-`useMcpAppHostContext()` は、React コンポーネントを変更にサブスクライブします。リクエスト
-ヘルパー (`openMcpAppHostLink`、`requestMcpAppDisplayMode`、
-`updateMcpAppModelContext`) 埋め込まれた MCP アプリ フレームの外で `false` を返す、または
-`Promise<boolean>` フレーム内。 `sendToAgentChat()` は
-埋め込みルートからの自動送信プロンプト。
-
-ブリッジ自体 — `ui/*` JSON-RPC メッセージ、`agentNative.mcpHost.*`
-ラッパー リレー、移植対制御フレーム レンダリング、ホスト コンテキスト、および
-表示モードのリクエスト — が所有しています
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## 動的な提案 {#dynamic-suggestions}
-
-`<AgentSidebar>`、`<AgentPanel>`、および `<AssistantChat>` は、デフォルトで静的 `suggestions` をコンテキスト認識の提案とマージします。フレームワークは、空のチャットが表示されている間にアプリケーションの状態から `navigation`、`selection`、`pending-selection-context`、および現在の URL を読み取り、現在の画面に一致するプロンプト チップを提供します。
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-静的チップのみを保持するように `dynamicSuggestions={false}` を設定します。アプリが同じアプリケーション状態コンテキストからの決定論的なドメイン固有のチップを必要とする場合は、`getSuggestions` を渡します。
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-読み込み状態の追跡を使用して sendToAgentChat をラップする React フック:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-`isGenerating` は、`send()` を呼び出すと true になり、エージェントが生成を完了すると自動的に false にリセットされます。
-
-## useDbSync(オプション?) {#usedbsync}
-
-React フック (以前の `useFileWatcher`) は、SSE を介してデータベースの変更をリッスンし、ポーリングにフォールバックし、UI をエージェントの書き込みと一致させるフレームワーク クエリ キャッシュを無効にします。
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### オプション {#usedbsync-options}
-
-| オプション         | タイプ             | 説明                                                                                   |
-| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | React - キャッシュ無効化のためのクライアントのクエリ                                   |
-| `queryKeys`        | `string[]?`        | 非推奨で無視されます。古い通話サイト用に保持                                           |
-| `pollUrl`          | `string?`          | エンドポイント URL をポーリングします。デフォルト: `"/_agent-native/poll"`             |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
-| `interval`         | `number?`          | ポーリング間隔 (ミリ秒)。デフォルト: `2000`                                            |
-| `fallbackInterval` | `number?`          | SSE が使用できない場合のフォールバック ポーリング間隔。デフォルト: `15000`             |
-| `pauseWhenHidden`  | `boolean?`         | ブラウザのタブが非表示の場合はポーリングを一時停止します。デフォルト: `true`           |
-| `ignoreSource`     | `string?`          | タブが自身の書き込みから再取得しないように無視するタブごとのリクエスト ソース          |
-| `onEvent`          | `(data) => void`   | SSE/polling が変更イベントを受信したときのオプションのコールバック                     |
-
-通常の CRUD の場合は、`useActionQuery` および `useActionMutation` を優先します。 actions を変更すると `source: "action"` が発行され、それらのフックは自動的に再フェッチされます。
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-フレームワークは変更バージョンを使用して、React クエリ キャッシュをバックグラウンド エージェント、cron ジョブ、または他のユーザーによって行われた変更と同期します。
-
-サーバー側のデータベースの変更が発生すると、サーバーは特定の `source` キーを使用して変更イベントを記録します。クライアントの `useDbSync` リスナーはこれらのイベントを受信し、そのソースのローカル変更バージョン カウンターをバンプします。バージョン カウンターを React クエリ キーに組み込むことにより、バックエンドがクライアントに新しいアクティビティを通知するたびに、クエリが自動的に再フェッチされます。
-
-- **`useChangeVersion(source: string): number`** — 指定された `source` が変更されるたびに増加するカウンターを返します。
-- **`useChangeVersions(sources: readonly string[]): number`** — 複数のソースのバージョン カウンターの合計を返します。
-
-### 例: 生のクエリをデータベースと同期する
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### レイテンシ モデルと無効化動作
-
-- **UI によって開始されたミューテーション:** `useActionMutation` を使用して UI からアクションを実行すると、ミューテーションは成功するとすぐに `source: "action"` のローカル イベントを起動します。これにより、そのアクションに応じてすべてのクエリ キーの**即時の楽観的な再取得**がトリガーされ、視覚的な遅延が回避されます。
-- **バックグラウンドまたはエージェントの変更:** AI エージェント、Webhook、またはバックグラウンド ワーカーがデータを変更すると、更新がクライアントにブロードキャストされます。クライアントの `useDbSync` は、これを SSE (サーバー送信イベント) 経由で即座にキャプチャするか、**2 秒のポーリング ティック** にフォールバックします。その後、クエリ キーのバージョンが変化し、バックグラウンドでの再取得がトリガーされます。
-
-<Diagram id="doc-block-prwgbw" title={"再フェッチへの 2 つのパス"} summary={"ローカルな突然変異は、それ自体のキャッシュを即座に無効にします。リモート書き込みは、SSE、またはフォールバックとしてのポーリング ティックを介してこのタブに到達します。"}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">このタブ</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">エージェント · webhook · 別タブ</span
-      ><strong>リモート書き込み</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...入力) {#cn}
-
-クラス名をマージするためのユーティリティ (clsx + tailwind-merge):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/ja-JP/drop-in-agent.mdx b/packages/core/docs/content/locales/ja-JP/drop-in-agent.mdx
index dd255b2d21..1afecaf82e 100644
--- a/packages/core/docs/content/locales/ja-JP/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/ja-JP/drop-in-agent.mdx
@@ -225,7 +225,7 @@ sendToAgentChat({
 
 同じルートが MCP アプリとして埋め込まれている場合、送信されます
 `sendToAgentChat()` 通話は、サポートされている場合はホスト チャットに転送されます。
-MCP アプリ ブリッジ動作の [Client](/docs/client#sendtoagentchat)。
+MCP アプリ ブリッジ動作の [Agent チャット](/docs/client-agent-chat#sendtoagentchat)。
 
 読み込み状態が必要な場合は、`useSendToAgentChat()` フックを使用します。これは、`send` と `isGenerating` の両方を返します。
 
diff --git a/packages/core/docs/content/locales/ja-JP/notifications.mdx b/packages/core/docs/content/locales/ja-JP/notifications.mdx
index e12c18ade8..d6a44922c8 100644
--- a/packages/core/docs/content/locales/ja-JP/notifications.mdx
+++ b/packages/core/docs/content/locales/ja-JP/notifications.mdx
@@ -363,7 +363,7 @@ export function HeaderBar() {
 ## 仕組み {#internals}
 
 - **所有者のスコープ** — すべての行に `owner` 列があります。すべてのクエリはそれをフィルタリングします。すべてのルートでは、認証されたセッションの電子メールが使用されます。ユーザーがお互いの通知を見ることはありません。
-- **ポーリング統合** — すべてのミューテーションが `recordChange()` を呼び出すため、[`useDbSync`](/docs/client) を使用するテンプレートは追加の配線なしで自動無効化されます。
+- **ポーリング統合** — すべてのミューテーションが `recordChange()` を呼び出すため、[`useDbSync`](/docs/client-data#usedbsync) を使用するテンプレートは追加の配線なしで自動無効化されます。
 - **ベストエフォート型ファンアウト** — チャネルエラーが捕捉され、ログに記録されます。 1 つのチャネルに障害が発生しても、他のチャネルや受信トレイへの書き込みはブロックされません。
 - **Fire-and-forget** — 受信箱への書き込みが完了すると、`notify()` が戻ります。カスタム チャネルはバックグラウンドで実行されます。
 
diff --git a/packages/core/docs/content/locales/ja-JP/progress.mdx b/packages/core/docs/content/locales/ja-JP/progress.mdx
index 5202e4e72d..0daac5263c 100644
--- a/packages/core/docs/content/locales/ja-JP/progress.mdx
+++ b/packages/core/docs/content/locales/ja-JP/progress.mdx
@@ -233,7 +233,7 @@ mode: agentic
 ## 仕組み {#internals}
 
 - **所有者のスコープ** — すべての行に `owner` 列があります。すべてのクエリはそれをフィルターに掛けます。ユーザーには自分の実行のみが表示されます。
-- **ポーリング統合** — すべてのミューテーションが `recordChange()` を呼び出すため、[`useDbSync`](/docs/client) を使用するテンプレートは追加の配線なしで自動無効化されます。
+- **ポーリング統合** — すべてのミューテーションが `recordChange()` を呼び出すため、[`useDbSync`](/docs/client-data#usedbsync) を使用するテンプレートは追加の配線なしで自動無効化されます。
 - **テーブル名** — フレームワークには、内部エージェント チャット ターン ライフサイクル追跡用の `agent_runs` テーブルもあります。進行状況プリミティブは、`progress_runs` を使用して 2 つの懸念事項を分離します。
 - **パーセント クランプ** — 値は `[0, 100]` にクランプされ、書き込み時に整数に丸められます。
 
@@ -241,4 +241,4 @@ mode: agentic
 
 - [**Notifications**](/docs/notifications) — `manage-progress` (`action=complete`) と組み合わせて、作業の終了をユーザーに通知します
 - [**Automations**](/docs/automations) — `run.progress.updated` 経由でウォッチドッグが低速で実行されます
-- [**Client**](/docs/client) — リアルタイム キャッシュ無効化の場合は `useDbSync`
+- [**データと同期**](/docs/client-data) — リアルタイム キャッシュ無効化の場合は `useDbSync`
diff --git a/packages/core/docs/content/locales/ja-JP/real-time-collaboration.mdx b/packages/core/docs/content/locales/ja-JP/real-time-collaboration.mdx
index 5e0e8a91df..6f48dd0c1f 100644
--- a/packages/core/docs/content/locales/ja-JP/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/ja-JP/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ description: "AI エージェントがファーストクラスのピアである
 エージェントと一緒に編集すると、共同編集エディターで作業しているような気分になります
 即席で疲れを知らない同僚:
 
-エージェントまたは別のユーザーが SQL に書き込むときに UI を更新するだけの場合は、これは必要ありません。[`useDbSync`](/docs/client) を使用してください。このページは、単一のリッチ テキスト ドキュメントを文字レベルで共同編集するためのものです (共有カーソル、競合のない結合)。どちらも同じ `/_agent-native/poll` チャネルに乗ります。
+エージェントまたは別のユーザーが SQL に書き込むときに UI を更新するだけの場合は、これは必要ありません。[`useDbSync`](/docs/client-data#usedbsync) を使用してください。このページは、単一のリッチ テキスト ドキュメントを文字レベルで共同編集するためのものです (共有カーソル、競合のない結合)。どちらも同じ `/_agent-native/poll` チャネルに乗ります。
 
 これは、**Yjs** (競合のないマージのための CRDT)、**TipTap** (リッチ テキスト エディター)、**ポーリング ベースの同期** (サーバーレスやエッジを含むすべての展開環境で機能します) という 3 つの実績のあるテクノロジーに基づいて構築されています。
 
@@ -774,7 +774,7 @@ undoManager.redo(); // Shift+Cmd+Z
 
 ## 関連ドキュメント {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) — `useDbSync` + `useChangeVersion`
+- [同期の内部](/docs/client-sync-internals) — `useDbSync` + `useChangeVersion`
   `updatedAt` バンプ ドライビング エディター調整を提供するシステム。
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   リソース単位のコラボレーションで使う `assertAccess`。
diff --git a/packages/core/docs/content/locales/ja-JP/routing.mdx b/packages/core/docs/content/locales/ja-JP/routing.mdx
deleted file mode 100644
index 1f90ae4f00..0000000000
--- a/packages/core/docs/content/locales/ja-JP/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "ルーティング"
-description: "React Router v8 を使用したエージェント ネイティブ アプリのファイルベースのルーティング — ページ、動的パラメータ、ナビゲーション。"
----
-
-# ルーティング
-
-エージェント ネイティブ アプリは、`@react-router/fs-routes` から `flatRoutes()` 経由のファイルベースのルーティングで **React Router v8** を使用します。 `app/routes/` 内のすべてのファイルは URL になります。テンプレートはドット表記規則を使用します。つまり、単一のファイル名内の URL セグメントはドットで区切られます。
-
-## ファイルベースのルーティング {#file-based-routing}
-
-### ファイル → URL マッピング
-
-| ファイル              | URL                  | メモ                                            |
-| --------------------- | -------------------- | ----------------------------------------------- |
-| `_index.tsx`          | `/`                  | インデックスルート                              |
-| `settings.tsx`        | `/settings`          | シンプルなページ                                |
-| `inbox.$threadId.tsx` | `/inbox/:threadId`   | ドット = `/`、`$` = 動的パラメータ              |
-| `_app.tsx`            | (URL セグメントなし) | パスレス レイアウト — `_` のプレフィックス      |
-| `inbox/route.tsx`     | `/inbox`             | フォルダー形式 — `route.tsx` はインデックスです |
-
-動的パラメータのセグメントに `$` という接頭辞を付けます。パスレス レイアウト ルート (URL セグメントなし) にするには、`_` というプレフィックスを付けます。テンプレートは `flatRoutes()` を使用します。上記のドット表記ファイルがプライマリです。ネストされたフォルダー形式 `inbox/route.tsx` も機能します。
-
-<Diagram id="doc-block-gw5atq" title={"パスレスレイアウトがページを包み込む"} summary={"_app.tsx レイアウト (URL セグメントなし) は、共有シェルを 1 回レンダリングします。一致したページは <Outlet/> 内でレンダリングされるため、エージェントのサイドバーがナビゲーションに再マウントされることはありません。"}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >パスなしレイアウト · 永続シェル + エージェントサイドバー</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## 新しいページを追加しています {#adding-a-page}
-
-ファイルを作成し、デフォルトのコンポーネントをエクスポートします。
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-それだけです。React ルーターが自動的にそれを取得します。登録は必要ありません。
-
-## 動的パラメータ {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## ナビゲーション {#navigation}
-
-クライアント側のナビゲーションには `<Link>` を使用し、プログラムによるナビゲーションには `useNavigate()` を使用します。
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## 次は何ですか
-
-- [**Client**](/docs/client) — エージェントネイティブのブラウザフックとユーティリティ
-- [**Server**](/docs/server) — ファイルベースのサーバー ルートと `/_agent-native/` 名前空間
diff --git a/packages/core/docs/content/locales/ko-KR/client-advanced.mdx b/packages/core/docs/content/locales/ko-KR/client-advanced.mdx
new file mode 100644
index 0000000000..9f41b0836f
--- /dev/null
+++ b/packages/core/docs/content/locales/ko-KR/client-advanced.mdx
@@ -0,0 +1,210 @@
+---
+title: "고급"
+description: "app/의 저수준 기본 요소와 예외적인 방법: application_state 직접 접근, 백그라운드 채팅 전송, 맞춤 제안 칩, MCP 앱 호스트 브리지."
+---
+
+# 고급
+
+개요, 데이터 및 동기화, Agent 채팅, 라우팅은 일반적인 경우 — 대부분의 페이지에 필요한 후크와 헬퍼 — 를 다룹니다. 이 페이지는 그 아래에 있는 더 저수준의 기본 요소와, 더 좁은 범위에서 쓰이는 예외적인 방법들을 다룹니다. 대부분의 앱은 이를 직접 다룰 일이 없습니다. 커스텀 선택 동기화나 임베드된 MCP 앱처럼 기본 후크가 지원하지 않는 더 커스텀한 것을 만들 때 이곳을 찾으세요. 손으로 만든 키로 원시 `useQuery`를 동기화해야 한다면 대신 [동기화 내부](/docs/client-sync-internals)를 참조하세요.
+
+## 애플리케이션 상태 {#application-state}
+
+`application_state`는 에이전트가 UI가 현재 무엇을 보고 있는지 알기 위해 읽는 SQL 기반 키/값 저장소입니다. 여기에는 내비게이션, 선택, 그 외 초점이 맞춰진 대상에 대한 컨텍스트가 포함됩니다([Context Awareness](/docs/context-awareness) 참조). `useAgentRouteState`와 `useSemanticNavigationState`(Context Awareness에서도 다룹니다)는 이미 일반적인 내비게이션 사례를 위해 이를 감싸고 있습니다. 아래의 기본 요소들은 커스텀 선택처럼 이들이 다루지 않는 것을 동기화해야 하거나, 컴포넌트의 렌더링 밖에서 써야 할 때 직접 사용하세요.
+
+### readClientAppState {#read-client-app-state}
+
+특정 키의 현재 값을 읽습니다. 그 키에 마지막으로 기록된 값으로 해석되며, 그 키가 한 번도 기록된 적이 없다면 `null`입니다.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+특정 키에 값을 씁니다. 아래의 `setClientAppState`와 달리, `null`을 전달해도 항상 씁니다. `undefined`를 전달하면 대신 예외가 발생합니다. `undefined`는 유효한 JSON이 아니기 때문입니다. 키를 지우려면 `setClientAppState(key, undefined)`나 `deleteClientAppState()`를 사용하세요.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+대부분의 UI 코드가 사용해야 할 편의 래퍼입니다: 값을 쓰거나, `null`/`undefined`를 전달하면 키를 삭제합니다. 호출 지점이 정말로 "항상 쓰고, 절대 삭제하지 않는" 동작을 필요로 하지 않는 한 `writeClientAppState` 대신 이것을 사용하세요.
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+키를 완전히 제거합니다.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+여러 키를 한 번의 요청으로 읽습니다. `{ values, missing }`을 반환합니다. `values`는 서버에 행이 존재하는 모든 키에 대한 항목을 담고 있으며, 명시적으로 `null`로 기록된 키도 포함합니다. `missing`은 한 번도 기록된 적이 없는 키들을 나열합니다. 이렇게 해서 "한 번도 기록되지 않음"이 "null로 기록됨"과 구분됩니다.
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+100개를 넘는 키 요청은 자동으로 나뉘어 처리됩니다. `readClientAppState()` 자체도 이 위에 만들어져 있습니다. 같은 틱(tick)에서 발생한 호출들은 내부적으로 하나의 배치 요청으로 통합되므로, 하나의 렌더 패스 안에서 여러 번 호출해도 호출당 한 번이 아니라 한 번의 왕복만 발생합니다.
+
+### 옵션 {#application-state-options}
+
+`signal`은 위 다섯 함수 모두에서 받으며, 진행 중인 호출을 취소하는 데 사용합니다. `requestSource`와 `keepalive`는 세 개의 쓰기 함수에만 적용됩니다. 읽기에는 아무 의미가 없기 때문입니다.
+
+| 옵션            | 유형           | 적용 대상                                                          | 설명                                                                                                           |
+| --------------- | -------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | 쓰기에 id를 태그하여, 일치하는 `useDbSync({ ignoreSource })`가 이를 다시 가져오지 않도록 건너뛸 수 있게 합니다 |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | 페이지가 언로드된 뒤에도 요청이 살아남도록 합니다. 선택 항목을 지우는 것과 같은 정리용 쓰기에 사용하세요       |
+| `signal`        | `AbortSignal?` | 다섯 함수 모두                                                     | 요청을 취소합니다                                                                                              |
+
+### 실패 동작 {#failure-behavior}
+
+다섯 함수 모두 요청 실패, 2xx가 아닌 응답, 또는 파싱할 수 없는 본문에 대해 예외를 던집니다. 던져지는 `Error`는 서버가 응답했을 경우 `.status` 속성을 가지므로, 호출자가 필요하면 HTTP 상태에 따라 분기할 수 있습니다. 다른 네트워크 호출과 마찬가지로 `try`/`catch`로 감싸거나 에러 바운더리로 전파되도록 두세요.
+
+### TAB_ID란 {#tab-id}
+
+`requestSource`는 보통 `TAB_ID`로 설정됩니다. 이는 모든 템플릿이 `app/lib/tab-id.ts`에서 내보내는 평범한 상수로, 탭이 살아있는 동안 동일하게 유지되고 탭마다 다른 짧은 무작위 문자열입니다. 쓰기 쪽에서 `requestSource: TAB_ID`를 짝지어 읽기 쪽에서 `useDbSync({ ignoreSource: TAB_ID })`를 사용하면, 탭이 자신의 쓰기는 다시 가져오지 않으면서도 다른 모든 것에는 여전히 반응하게 됩니다. 전체 과정은 [Context Awareness](/docs/context-awareness#jitter-prevention)를 참조하세요.
+
+## sendToAgentChat: 백그라운드 전송 {#background-send}
+
+UI 작업이 사이드바를 열거나 포커스를 옮기지 않고 실제 에이전트 작업을 시작해야
+할 때 `background: true`를 사용하세요. 이는 여전히 일반적인 채팅 스레드/실행을
+생성하고, 에이전트의 도구/actions/컨텍스트를 사용하며, 실행 트레이를 통해
+관찰 가능한 상태를 유지합니다. 이는 원시적인 일회성 모델 호출이 아닙니다.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background`는 `newTab`과 함께 사용하도록 만들어졌습니다. 그래야 숨겨진 작업이
+사용자의 활성 대화를 덮어쓰지 않습니다. UI가 후속 상태를 연관 짓거나 나중에
+실행으로 딥링크해야 한다면 반환된 `tabId`를 사용하세요.
+
+[Agent 채팅](/docs/client-agent-chat#agentchatmessage)에서 다룬 것들 외에도 몇 가지
+`AgentChatMessage` 옵션이 더 있으며, 대부분 임베드나 다운스트림 통합 사례를
+위한 것입니다.
+
+| 옵션                  | 유형        | 설명                                                                                     |
+| --------------------- | ----------- | ---------------------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | `newTab`과 함께 사용하면 탭에 포커스를 주지 않고 실행하며 `RunsTray`에 실행을 표시합니다 |
+| `projectSlug`         | `string?`   | 구조화된 컨텍스트를 위한 선택적 프로젝트 슬러그                                          |
+| `preset`              | `string?`   | 다운스트림 소비자를 위한 선택적 프리셋 이름                                              |
+| `referenceImagePaths` | `string[]?` | 선택적 참조 이미지 경로                                                                  |
+
+## MCP 앱 호스트 브리지 {#mcp-app-host-bridge}
+
+MCP 앱으로 임베드되는 경로는 URL 우선이어야 합니다: 경로/쿼리 매개변수에서
+현재 아티팩트를 로드하고, 실제 React 경로나 초점이 맞춰진 공유 컴포넌트를
+렌더링하며, 호스트 소유의 동작에만 호스트 브리지를 사용하세요.
+`@agent-native/core/client`는 임베드된 경로가 호출하는 헬퍼들을 내보냅니다.
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()`는 최근에 전달된 호스트 컨텍스트 스냅샷을 읽습니다.
+`useMcpAppHostContext()`는 React 컴포넌트를 변경 사항에 구독시킵니다. 요청
+헬퍼(`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`)는 임베드된 MCP 앱 프레임 밖에서는 `false`를,
+프레임 안에서는 `Promise<boolean>`을 반환합니다.
+
+`sendToAgentChat()`([Agent 채팅](/docs/client-agent-chat#sendtoagentchat) 참조)은
+임베드된 경로에서 자동 제출된 프롬프트에 동일한 브리지를 사용합니다.
+`embedApp()`으로 생성된 MCP 앱 임베드 안에서는, 자동 제출된 메시지(`submit`을
+생략했거나 `true`인 경우)가 브리지로 전달되고, 브리지는 포함하고 있는
+호스트에게 숨겨진 컨텍스트를 추가하고 표시되는 사용자 턴을 보내달라고
+요청합니다. `context`는 사용자에게 보이는 채팅으로 게시되지 않으면서도
+모델에는 보이는 상태로 유지됩니다. `submit: false`는 로컬 미리 채우기/검토
+동작을 그대로 유지합니다. MCP 앱은 표준 초안 미리 채우기 API를 정의하지
+않기 때문입니다. 내부적으로 이는 때때로 `agentNative.submitChat`으로
+드러나는 제출된-채팅 경로입니다. 앱 코드는 그 이벤트를 직접 게시하는 대신
+여전히 `sendToAgentChat()`을 호출해야 합니다.
+
+브리지 자체, `ui/*` JSON-RPC 메시지, `agentNative.mcpHost.*` 래퍼 릴레이,
+이식(transplant) 방식과 제어되는 프레임(controlled-frame) 렌더링, 호스트
+컨텍스트, 디스플레이 모드 요청은 [External Agents](/docs/external-agents#mcp-app-bridge)가
+관리합니다. 전체 프로토콜은 [MCP Apps](/docs/mcp-apps)를 참조하세요.
+
+## 맞춤 제안 칩 {#custom-suggestions}
+
+`<AgentSidebar>`의 `dynamicSuggestions`([Agent 채팅](/docs/client-agent-chat#dynamic-suggestions) 참조)는
+이미 고정된 `suggestions`를 프레임워크 자체의 컨텍스트 인식 휴리스틱과
+병합합니다. 프레임워크의 기본 휴리스틱 대신 동일한 `application_state`
+컨텍스트로부터 계산된 결정론적이고 도메인 특화된 칩을 앱이 원할 때는
+`getSuggestions`를 전달하세요.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions`는 내장 휴리스틱이 읽는 것과 동일한 `navigation`/`selection`/`pending-selection-context`
+스냅샷을 받으므로, 커스텀 구현이 기본 구현과 정확히 같은 상태에 반응하되
+일반적인 규칙이 아닌 앱 전용 규칙으로 반응할 수 있습니다.
+
+## 다음 단계
+
+- [**개요**](/docs/client-overview) — 이 기본 요소들이 속한 `app/`과 `public/` 디렉터리 구조
+- [**데이터 및 동기화**](/docs/client-data) — 대부분의 페이지가 대신 사용해야 할 기본 action 후크와 `useDbSync`
+- [**동기화 내부**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions`와 다시 가져오기가 거칠 수 있는 두 가지 지연 경로
+- [**Agent 채팅**](/docs/client-agent-chat) — 대부분의 UI가 대신 사용해야 할 기본 `sendToAgentChat`/`askUserQuestion` 헬퍼, 그리고 단계적 에이전트 채팅 컨텍스트 상태 API
+- [**엔트리 포인트**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx`와 SSR 스트리밍 커스터마이징
+- [**Context Awareness**](/docs/context-awareness) — `application_state`에 기반한 `navigation`/`selection` 시맨틱, `TAB_ID`/지터 방지 과정
+- [**Generative UI**](/docs/generative-ui) — `askUserQuestion`을 넘어서는 더 풍부한 인라인 채팅 컨트롤
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — MCP 앱 호스트 브리지의 전체 내부 구조
diff --git a/packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx b/packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx
new file mode 100644
index 0000000000..ae52185f93
--- /dev/null
+++ b/packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx
@@ -0,0 +1,315 @@
+---
+title: "Agent 채팅"
+description: "에이전트 채팅으로 들어가는 클라이언트 측 진입점: sendToAgentChat, openAgentSettings, askUserQuestion, 동적 제안, useAgentChatGenerating, 그리고 단계적 에이전트 채팅 컨텍스트 상태."
+---
+
+# Agent 채팅
+
+여러분의 애플리케이션 클라이언트는 작은 클라이언트 헬퍼 집합을 통해 에이전트와 대화할 수 있습니다. 여기에는 프롬프트 전송, 숨겨진 컨텍스트 준비, 사용자에게 블로킹 질문하기, 에이전트 패널 열기가 포함됩니다.
+
+아래 예시에서는 **답변 초안 작성** 버튼이 에이전트에게 사용자에게 질문을 하도록 요청합니다. 사용자가 답변하면 에이전트는 현재 페이지 컨텍스트와 사용자의 응답을 염두에 두고 답변 초안을 작성합니다.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="실행 기록 사이드바를 보여주는 Dispatch 앱 스크린샷"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Dispatch의 실행 기록 사이드바."
+/>
+
+## 작동 방식
+
+Agent-Native가 제공하는 클라이언트 헬퍼 메서드를 사용하면 UI가 다양한 방식으로 사용자와 상호작용하도록 에이전트에게 요청할 수 있습니다. 아래 다이어그램은 사용자가 클릭한 "답변 초안 작성" 버튼이 응답을 생성하기 전에 에이전트가 사용자와 상호작용하도록 요청하는 과정을 보여줍니다.
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="'각 단계는 누구의 몫인가'라는 제목의 시퀀스 다이어그램. App Code, UI, Agent라는 세 개의 라이프라인을 보여준다. 사용자가 'draft response'를 클릭하면 askUserQuestion()이 트리거된다. 이는 에이전트 패널에 인라인으로 렌더링된다는 설명이 붙어 있다. 사용자가 답변하면 sendDraftRequest()가 Agent에서 호출되어 draft-ticket-reply를 호출하고, 작성된 답글을 UI의 작성기로 반환한다."
+  align="full"
+  width={600}
+  caption="'답변 초안 작성' 버튼 흐름을 시각화한 시퀀스 다이어그램."
+/>
+
+사용자 경험은 다음과 같습니다.
+
+1. 사용자가 **답변 초안 작성** 버튼을 클릭하면 `askUserQuestion()` 함수가 호출됩니다. 질문은 에이전트 패널 안에서 인라인으로 답변됩니다.
+
+1. 사용자가 **환불 제공**을 선택하면 `sendDraftRequest()`가 프롬프트와 티켓 컨텍스트를 에이전트에게 전송합니다.
+
+1. 에이전트는 `draft-ticket-reply` [action](/docs/actions)을 호출하고, 작성된 답글이 답글 작성기에 나타납니다.
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description:
+        "질문, 그 옵션들, 그리고 이것이 어떻게 동작해야 하는지입니다.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "완전한 질문입니다. 명확하고 구체적이며 물음표로 끝나야 합니다.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            '약 12자 정도의 매우 짧은 칩/제목입니다. 예: `"Response"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2~4개의 서로 다른 옵션입니다. 각각은 `{ label, value?, description?, preview?, recommended? }`입니다. `value`의 기본값은 `label`입니다.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            '담당자가 직접 입력할 수 있는 자유 텍스트 "기타" 옵션을 추가합니다.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "단일 선택 대신 다중 선택입니다.",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description: "에이전트 패널이 폴링하는 애플리케이션 상태 키입니다.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      '선택된 `value`(`allowMultiple`인 경우 `value[]`), 담당자가 입력한 "기타" 텍스트, 또는 건너뛴 경우 `null`입니다. 답변할 때까지 대기 상태로 유지됩니다. 에이전트 패널이 마운트되어 있어야 하며, 모든 템플릿에서 이는 이미 마운트되어 있습니다.',
+  }}
+/>
+
+이 함수는 앱 코드에서 사용자에게 객관식 질문을 던지고, 이를 에이전트 패널 안에 인라인으로 렌더링한 뒤 답변을 기다립니다. UI가 에이전트 작업을 시작하기 전에 2~4개 옵션 중 작은 결정 하나가 필요할 때, 커스텀 모달을 만드는 대신 이 함수를 사용하세요.
+
+아래 예시에서는 티켓 페이지의 "답변 초안 작성" 버튼이 에이전트에게 무언가를 보내기 전에 담당자에게 어떻게 응답하고 싶은지 묻습니다.
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "`[isGenerating, send]` 튜플입니다. `isGenerating`은 `send()`가 호출된 순간부터 에이전트 채팅 실행이 중지되었다고 보고할 때까지 `true`입니다. `send(opts)`는 `sendToAgentChat()`과 동일한 시그니처를 가지며, 전송된 탭 id를 반환합니다.",
+  }}
+/>
+
+이 React 후크는 `sendToAgentChat()`을 로딩 상태 추적과 함께 감쌉니다.
+
+1. 첫 번째 반환값인 `isGenerating`은 호출 시점에 true가 되고, 에이전트가 생성을 마치면 false로 재설정됩니다.
+
+2. 두 번째 반환값인 `send()`는 `sendToAgentChat()` 함수를 그대로 미러링합니다.
+
+`isGenerating`은 실행이 실제로 시작되어 중지되었다고 보고할 때만 재설정됩니다. `submit: false` 호출은 실행을 시작하지 않고 초안만 미리 채우므로, 그 이후로는 `isGenerating`이 영원히 `true`로 남습니다. 이 후크는 `submit: true` 전송에만 사용하세요. 미리 채우기만 하는 전송에는 `sendToAgentChat()`을 직접 호출하세요.
+
+위의 `askUserQuestion()` 예시와 이 후크를 결합하면 버튼의 핸들러가 완성됩니다.
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title={"답변 초안 작성 핸들러 완성하기"}
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "로딩 상태 + 전송, 함께",
+      note: "`useAgentChatGenerating()`은 단순한 `sendToAgentChat()` 호출과 동일한 형태의 튜플을 반환하지만, 요청이 진행 중일 때 버튼을 비활성화할 수 있도록 `isDrafting`을 추가로 제공합니다.",
+    },
+    {
+      lines: "10-17",
+      label: "질문 단계 재사용",
+      note: "위 섹션의 `askUserQuestion()` 호출과 정확히 동일하며, 이제 버튼 자체의 핸들러 안에 들어 있습니다.",
+    },
+    {
+      lines: "18",
+      label: "답변을 사용하기 전에 좁혀두기",
+      note: "반환 타입은 항상 `allowMultiple`로 인한 `string[]`을 허용하므로, 이 호출이 그 옵션을 사용하지 않더라도 이 검사가 필요합니다.",
+    },
+    {
+      lines: "20-25",
+      label: "선택 결과를 문장으로 변환",
+      note: "선택된 값이나 담당자가 직접 입력한 텍스트를, 아래 프롬프트가 자연스럽게 읽을 수 있는 표현으로 매핑합니다.",
+    },
+    {
+      lines: "27-32",
+      label: "action과 의도를 명시하기",
+      note: "이 메시지는 에이전트에게 어떤 action을 호출할지(`draft-ticket-reply`)를 정확히 알려주고, 답글을 그대로 전송하지 말라고 상기시킵니다. `openSidebar: true`는 사이드바가 닫혀 있었더라도 작성된 답글이 보이도록 합니다.",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting이 버튼을 제어",
+      note: "`sendDraftRequest()`가 진행 중일 때만 비활성화되고 레이블이 바뀝니다. `askUserQuestion()`이 담당자의 응답을 기다리는 동안은 버튼이 계속 클릭 가능합니다. 이는 `sendDraftRequest()`가 호출되기 전에 일어나기 때문입니다.",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+`postMessage`를 통해 에이전트 채팅에 메시지를 보냅니다. 이는 위의 `useAgentChatGenerating()`이 감싸고 있는 더 저수준의 기본 요소로, UI 상호작용이 자체적인 로딩 상태 추적을 필요로 하지 않을 때 유용합니다. 메시지만으로는 전달되지 않는 추가적인 세부 정보에는 `context`를 전달하세요. 이는 동일한 표시 메시지에 `<context>` 태그로 감싸여 덧붙여집니다. 사용자에게 숨겨지지 않습니다. 즉시 전송하려면 `submit: true`를, 사용자가 먼저 검토할 초안을 미리 채우려면 `submit: false`를 전달하세요.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| 옵션          | 유형       | 설명                                                                                                   |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
+| `message`     | `string`   | 채팅에 전송되는 프롬프트입니다. `context`가 설정되어 있으면 동일한 표시 메시지에 덧붙여집니다          |
+| `context`     | `string?`  | 표시 메시지에 덧붙여지는 추가 세부 정보로, `<context>` 태그로 감싸집니다. 사용자에게 숨겨지지 않습니다 |
+| `submit`      | `boolean?` | true = 자동 제출, false = 미리 채우기만                                                                |
+| `newTab`      | `boolean?` | 이 프롬프트를 위한 별도의 채팅 스레드를 생성합니다                                                     |
+| `openSidebar` | `boolean?` | 사이드바를 열지 않고 제출/미리 채우려면 false로 설정하세요                                             |
+
+MCP 앱 임베드 내부에서 이를 실행하는 경우, 또는 사이드바를 열지 않고 실행을 백그라운드로 보내는 경우는 모두 [고급](/docs/client-advanced#background-send)에서 다룹니다.
+
+## 동적 제안 {#dynamic-suggestions}
+
+대화가 시작되기 전, `<AgentSidebar>`, `<AgentPanel>`, `<AssistantChat>`은 빈 채팅에 프롬프트 칩을 보여줍니다. 기본적으로 이는 여러분이 고정한 `suggestions` 목록만이 아닙니다. 프레임워크는 애플리케이션 상태에서 `navigation`, `selection`, `pending-selection-context`, 그리고 현재 URL을 읽어, 실제 화면에 있는 내용과 일치하는 칩을 병합합니다.
+
+이는 두 가지 검사를 통해 이루어집니다. 무언가가 선택되어 있으면 "이 선택 항목 요약"과 같은 일반적인 칩을 추가합니다. 별도로, `navigation`에서 이메일 스레드의 `threadId`/`emailId`나 차트의 `dashboardId`/`chartId`처럼 이미 여러 앱이 사용하는 흔한 필드 이름을 찾아, 스레드에는 "답장 초안 작성", 차트에는 "이 데이터에서 이상치 찾기"처럼 그 화면 종류에 맞는 칩을 추가합니다. 그 결과는 여러분의 고정 `suggestions`와 병합되고, 중복이 제거되며, `max`로 상한이 설정됩니다.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+현재 화면이 이 휴리스틱이 인식하는 어떤 것과도 일치하지 않고 아무것도 선택되어 있지 않다면, 이는 아무 칩도 제공하지 않고 빈 채팅은 여러분의 고정 `suggestions`만으로 되돌아갑니다. 고정 칩만 유지하려면 `dynamicSuggestions={false}`를 설정하세요. 앱의 내비게이션 형태가 내장 휴리스틱과 맞지 않거나, 완전히 결정론적인 앱 전용 칩을 원한다면 [고급](/docs/client-advanced#custom-suggestions)을 참조하세요.
+
+## openAgentSettings(section?) {#openagentsettings}
+
+앱 설정 페이지나 설정 카드가 에이전트 사이드바의 설정 탭을 열어야 할 때
+`openAgentSettings()`를 사용하세요. 특정 섹션을 열려면 `"llm"`, `"secrets"`,
+`"automations"`, `"voice"`, `"limits"`와 같은 섹션 id를 전달하세요.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+`agent-panel:open-settings`를 직접 디스패치하는 것보다 이 헬퍼를 사용하는 것을 우선하세요.
+
+## Agent 채팅 컨텍스트 상태 {#agent-chat-context-state}
+
+컨텍스트 상태 API는 단계적으로 준비된 컨텍스트 칩과 양방향 동기화가 필요한 UI를 위한 선택적 배관입니다: 현재 준비된 항목을 작성기 밖에서 렌더링하거나, 어떤 항목이 이미 첨부되어 있는지 반영하거나, 명시적인 제거/삭제 컨트롤을 제공하는 경우입니다.
+
+단순한 "이것을 에이전트에게 보내기"나 "이 초안을 검토용으로 미리 채우기" 흐름에는 이 헬퍼들을 사용하지 마세요. 그런 경우에는 [`sendToAgentChat()`](#sendtoagentchat)을 `context`와 `submit`과 함께 사용하세요.
+
+| API                               | 사용 시점                                                                |
+| --------------------------------- | ------------------------------------------------------------------------ |
+| `useAgentChatContext()`           | React 컴포넌트가 현재 준비된 컨텍스트 목록을 실시간으로 필요로 할 때     |
+| `setAgentChatContextItem(item)`   | 명령형 코드가 키를 가진 컨텍스트 항목 하나를 준비하거나 대체해야 할 때   |
+| `listAgentChatContext()`          | React가 아닌 코드가 준비된 컨텍스트의 일회성 스냅샷이 필요할 때          |
+| `removeAgentChatContextItem(key)` | UI가 안정적인 `key`로 준비된 컨텍스트 항목 하나를 제거해야 할 때         |
+| `clearAgentChatContext()`         | 화면이나 모드가 재설정된 뒤처럼 UI가 준비된 컨텍스트를 전부 지워야 할 때 |
+| `refreshAgentChatContext()`       | 명령형 코드가 최신으로 저장된 컨텍스트 스냅샷을 다시 읽어야 할 때        |
+
+`useAgentChatContext()`는 `{ items, set, remove, clear, refresh }`를 반환합니다.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()`는 현재 준비된 항목을 한 번만 검사하면 되는 명령형 코드를 위한 것입니다. `clearAgentChatContext()`는 의도적으로 광범위합니다. 선택 항목 하나만 바뀌었다면 `removeAgentChatContextItem(key)`를 사용하세요.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| 옵션          | 유형       | 설명                                                                 |
+| ------------- | ---------- | -------------------------------------------------------------------- |
+| `key`         | `string`   | 기존 항목을 대체하는 데 사용되는 안정적인 식별자                     |
+| `title`       | `string`   | 작성기 칩에 표시되는 짧은 레이블                                     |
+| `context`     | `string`   | 다음에 제출되는 프롬프트에 포함되는 숨겨진 컨텍스트                  |
+| `openSidebar` | `boolean?` | 기본값은 true입니다. 조용히 컨텍스트를 준비하려면 false를 전달하세요 |
+
+## 다음 단계
+
+- [**개요**](/docs/client-overview) — 이 헬퍼들이 `app/` 안에서 차지하는 위치
+- [**데이터 및 동기화**](/docs/client-data) — UI 자체를 최신 상태로 유지하는 action 후크와 `useDbSync`
+- [**드롭인 에이전트**](/docs/drop-in-agent) — 이 헬퍼들이 렌더링될 곳을 마련하기 위한 `<AgentSidebar>`/`<AgentPanel>` 마운트
+- [**고급**](/docs/client-advanced) — 백그라운드 전송, 맞춤 제안 칩, MCP 앱 호스트 브리지
+- [**Generative UI**](/docs/generative-ui) — `askUserQuestion`을 넘어서는 더 풍부한 인라인 채팅 컨트롤 만들기
diff --git a/packages/core/docs/content/locales/ko-KR/client-data.mdx b/packages/core/docs/content/locales/ko-KR/client-data.mdx
new file mode 100644
index 0000000000..4da61deab4
--- /dev/null
+++ b/packages/core/docs/content/locales/ko-KR/client-data.mdx
@@ -0,0 +1,434 @@
+---
+title: "데이터 및 동기화"
+description: "app/이 에이전트가 호출하는 동일한 actions를 읽고 쓰며 실시간으로 동기화하는 데 사용하는 action 후크."
+---
+
+# 데이터 및 동기화
+
+클라이언트 애플리케이션에서 앱 데이터를 읽고 쓰는 주된 방법은 [action](/docs/actions) 후크를 사용하는 것입니다. 요청을 actions에 담아 보내면 클라이언트와 에이전트가 동일한 방식으로 애플리케이션과 상호작용할 수 있습니다.
+
+아래 예시에서는 티켓이 드롭다운을 통해 수동으로, 그리고 채팅 에이전트를 통해 현재 사용자에게 배정됩니다. UI와 에이전트는 동일한 action에 접근합니다.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="UI 작업과 에이전트 작업이 동일한 결과를 내는 예시."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="UI 작업과 에이전트 작업이 동일한 결과를 내는 예시."
+/>
+
+## 데이터 가져오기 및 변경하기 {#fetching-mutating}
+
+일반적인 앱은 자체 API 레이어를 만들고 직접 작성한 `fetch` 요청으로 이를 호출합니다. 에이전트 네이티브 앱은 그 레이어를 건너뜁니다: `app/`은 아래 후크를 통해 에이전트가 이미 도구로 가지고 있는 동일한 actions를 호출합니다.
+
+<Diagram id="doc-block-client-data-fm-1" title={"일반적인 fetch vs. action 후크"} summary={"일반적인 컴포넌트는 자신만 접근할 수 있는 경로를 호출합니다. 에이전트 네이티브 컴포넌트는 에이전트도 호출할 수 있는 action을 호출합니다."}>
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">일반적인 방식</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>여러분의 API 경로</strong>
+      <small class="diagram-muted">프런트엔드만 호출 가능</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>데이터베이스</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Component</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead action</span>
+      <small class="diagram-muted">에이전트 도구이기도 함</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL 데이터베이스</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Action 후크 {#action-hooks}
+
+가장 많이 사용하게 될 두 개의 action 후크는 `useActionQuery()`와 `useActionMutation()`입니다. 이 두 후크는 앱의 actions에 접근할 수 있게 해줍니다.
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "등록된 action의 이름입니다.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "action의 입력값으로, `defineAction()` 스키마에서 타입이 지정됩니다.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "[useQuery 옵션](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) 중 `queryKey`와 `queryFn`을 제외한 모든 것입니다. 이 둘은 후크가 직접 설정합니다.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      '`["action", name, params]` 아래에 캐시됩니다. 변형 작업이 완료될 때마다 별도의 수동 무효화 없이 자동으로 다시 가져옵니다.',
+  }}
+/>
+
+이 후크는 읽기 전용 actions에 사용하기 위한 것입니다. [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) 함수를 얇게 감싼 래퍼입니다.
+
+아래 예시에서는 `list-tickets` action이 호출됩니다. 이는 모든 티켓에 대한 GET 요청을 보내는 것과 비슷합니다.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+다음 예시는 `get-ticket` action을 통해 단일 티켓을 가져오는 요청을 보여줍니다. 쿼리 범위를 특정 티켓으로 좁히기 위해 `ticketId`를 전달합니다. 쿼리가 자동으로 실행되지 않고 `ticketId`가 있을 때만 실행되도록 보장하기 위해 `enabled` 옵션이 추가로 제공됩니다.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "등록된 action의 이름입니다.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "[useMutation 옵션](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) 중 `mutationFn`을 제외한 모든 것입니다. 이는 후크가 직접 설정합니다.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "기본 요청 메서드를 재정의합니다.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "성공 시 자동 캐시 갱신을 건너뜁니다.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      '성공 시 `source: "action"`으로 변경 이벤트를 내보내므로, 영향을 받는 데이터를 읽는 모든 `useActionQuery()`가 자동으로 다시 가져옵니다. 수동 무효화가 필요하지 않습니다.',
+  }}
+/>
+
+이 후크는 생성, 수정, 전송처럼 데이터를 변경하는 actions에 사용하기 위한 것입니다. [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) 함수를 얇게 감싼 래퍼입니다.
+
+`useActionQuery()`와 달리 action의 입력값은 후크 자체에 전달되지 않습니다. 변경을 실행할 준비가 되었을 때 `mutate()` 또는 `mutateAsync()`에 전달합니다.
+
+아래 예시에서는 `send-ticket-reply` action이 호출되어 티켓에 답글이 게시됩니다. 버튼의 `onClick`과 같은 이벤트 핸들러에서 `mutate()`를 호출합니다.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+다음 예시는 동일한 변경 작업에 `onSuccess` 옵션을 추가한 모습을 보여줍니다. 캐시 무효화는 모든 변경 작업 후에 자동으로 일어나므로, `onSuccess`는 답글이 전송된 뒤 작성기를 비우는 것과 같은 로컬 부수 효과에만 필요합니다.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "등록된 action의 이름입니다.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "action의 입력값으로, `defineAction()` 스키마에서 타입이 지정됩니다.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "아래 항목은 모두 선택 사항입니다.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "기본 요청 메서드를 재정의합니다.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "요청을 취소합니다.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "정당하게 더 오래 걸리는 actions를 위해 기본 60초 타임아웃을 재정의합니다.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "위 후크들과 달리 캐시도 자동 다시 가져오기도 없습니다. 다른 UI가 이 결과에 의존한다면 수동 무효화와 함께 사용하세요.",
+  }}
+/>
+
+이 함수는 React 렌더 흐름 밖에서 일회성으로 action을 명령형으로 호출하기 위한 것입니다. 일반 이벤트 핸들러, 스크립트, 그 외 React가 아닌 어떤 코드 경로에서도 사용할 수 있습니다. 후크 결과 대신 프로미스를 직접 반환합니다.
+
+아래 예시에서는 React 렌더 흐름 밖의 키보드 단축키 핸들러에서 `update-ticket` action을 호출하여 티켓을 담당자에게 배정합니다.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+다음 예시는 동일한 호출에 `timeoutMs` 옵션을 추가한 모습입니다. 기본 60초 타임아웃보다 정당하게 더 오래 걸리는 actions에 유용합니다.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+모든 `useActionQuery()`, `useActionMutation()`, `callAction()` 요청은 60초 타임아웃으로 제한되며, 타임아웃은 조용히 재시도하지 않고 오류로 나타납니다. `useActionQuery()`는 React Query의 abort signal을 이용해 이전 요청이 대체될 때 자동으로 취소하기도 합니다.
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "모든 필드는 선택 사항입니다.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "캐시 무효화에 사용되는 React Query 클라이언트입니다.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "폴링 엔드포인트 URL입니다.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "SSE 엔드포인트 URL입니다. 폴링만 사용하려면 `false`를 전달하세요.",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "폴링 간격(ms)입니다.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "SSE가 연결되어 있는 동안, 이벤트를 놓쳤을 때를 대비한 백업으로 사용되는 폴링 간격입니다. 연결이 끊긴 탭은 더 빠른 `interval`(또는 고정된 유휴 주기)로 폴링합니다.",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "브라우저 탭이 숨겨져 있을 때 폴링을 일시 중지합니다. 숨겨진 탭도 SSE 연결은 유지하며, 활성 상태에서는 10초, 유휴 상태가 되면 60초보다 빠르게 폴링하지 않습니다.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "무시할 탭별 요청 소스로, 탭이 자신의 쓰기로 인해 다시 가져오지 않도록 합니다.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "SSE 또는 폴링이 변경 이벤트를 수신했을 때 실행되는 선택적 콜백입니다.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "action 이벤트가 촉발하는 광범위한 무효화를 필터링합니다. 거의 필요하지 않습니다. 비용이 큰 활성 쿼리를 명시적 새로 고침 방식으로 유지하면서, 일반적인 소스 버전 관리 쿼리들은 여전히 `useChangeVersion`으로 반응하도록 하는 데 사용하세요.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "동기화 이벤트가 모든 action 쿼리를 무효화하지 않도록 할 action 이름들입니다. 이미 자체적으로 좁은 무효화를 수행하는 대용량 백그라운드 actions에만 사용하세요.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description:
+            "더 이상 사용되지 않으며 무시됩니다. 기존 호출 지점을 위해 유지됩니다.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+이 후크는 여러분의 actions 밖에서 일어나는 데이터베이스 변경 — 에이전트의 쓰기, 웹훅, 다른 브라우저 탭에서의 변경 등 — 과 UI를 동기화하기 위한 것입니다. 서버-전송 이벤트(server-sent events)로 변경을 수신하며, 서버-전송 이벤트를 사용할 수 없을 때는 폴링으로 대체합니다.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+일반적인 CRUD에는 `useActionQuery()`와 `useActionMutation()`을 사용하세요. 변형 actions는 `source: "action"`을 내보내므로 이 후크들은 즉시 다시 가져옵니다. 에이전트, 웹훅, 다른 탭에서 온 변경은 대신 `useDbSync()`를 통해 SSE 또는 폴링 폴백으로 도착합니다. 원시 `useQuery()` 호출을 커스텀 키로 동기화해야 한다면 [동기화 내부](/docs/client-sync-internals)를 참조하세요. `application_state`에 직접 써야 한다면 [고급](/docs/client-advanced)을 참조하세요.
+
+## 다음 단계
+
+- [**개요**](/docs/client-overview) — 이 페이지의 후크들이 속한 `app/` 및 `public/` 디렉터리 구조
+- [**Agent 채팅**](/docs/client-agent-chat) — 프롬프트 전송과 에이전트를 위한 컨텍스트 준비
+- [**Actions**](/docs/actions) — 이 페이지의 모든 후크 뒤에 있는 `defineAction` 표면
+- [**고급**](/docs/client-advanced) — `application_state` 직접 접근
+- [**동기화 내부**](/docs/client-sync-internals) — `useChangeVersion`으로 원시 `useQuery` 동기화하기
+- [**Real-Time Sync**](/docs/key-concepts#polling-sync) — `useDbSync`가 UI를 최신 상태로 유지하는 방법
diff --git a/packages/core/docs/content/locales/ko-KR/client-entry-points.mdx b/packages/core/docs/content/locales/ko-KR/client-entry-points.mdx
new file mode 100644
index 0000000000..ba19567824
--- /dev/null
+++ b/packages/core/docs/content/locales/ko-KR/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "엔트리 포인트"
+description: "app/entry.client.tsx와 app/entry.server.tsx: 얇은 하이드레이션 및 SSR 부트스트랩 래퍼, 그리고 스트리밍 동작을 커스터마이징해야 할 때."
+---
+
+# 엔트리 포인트
+
+`app/entry.client.tsx`는 서버에서 렌더링된 HTML을 브라우저에서 하이드레이션하고, `app/entry.server.tsx`는 서버에서 그 HTML을 렌더링합니다. 둘 다 React Router가 생성하는 얇은 래퍼입니다. 이를 수정해야 할 일은 거의 없습니다.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+이 파일들은 고급 SSR 커스터마이징 — 예를 들어 스트리밍 동작을 바꾸는 것 — 에만 손대세요. 일반적인 페이지, 레이아웃, 데이터는 여기서 바꿀 필요가 없습니다. 페이지를 추가하는 것은 대신 [Routing](/docs/client-routing)을 참조하세요.
+
+## 다음 단계
+
+- [**개요**](/docs/client-overview) — 이 파일들이 `app/` 안에서 자리하는 위치
+- [**Routing**](/docs/client-routing) — `app/`을 확장하는 일반적인 방법인 페이지 추가하기
+- [**고급**](/docs/client-advanced) — 그 외의 저수준 클라이언트 기본 요소와 예외적인 방법들
diff --git a/packages/core/docs/content/locales/ko-KR/client-overview.mdx b/packages/core/docs/content/locales/ko-KR/client-overview.mdx
new file mode 100644
index 0000000000..c9e46f5651
--- /dev/null
+++ b/packages/core/docs/content/locales/ko-KR/client-overview.mdx
@@ -0,0 +1,206 @@
+---
+title: "개요"
+description: "app/ 및 public/ 디렉터리: 에이전트 네이티브 앱의 화면을 만드는 곳, 그리고 에이전트와 동기화된 상태를 유지하기 위해 사용하는 브라우저 API."
+---
+
+# 개요
+
+`app/`는 에이전트 네이티브 앱의 실제 화면 — 페이지, 레이아웃, 컴포넌트, 스타일 — 을 만드는 곳입니다. `public/`은 그 옆에서 함께 제공되는 정적 자산 — 아이콘, 매니페스트, 브랜드 마크 — 을 담고 있습니다. 이것은 일반적인 React Router v8 앱이며, 에이전트 전용의 특별한 표면이 아닙니다. 대부분의 개발 시간이 여기에 쓰입니다.
+
+일반적인 프런트엔드와의 유일한 아키텍처상 차이점은 이 레이어에는 자체적인 backend-for-frontend가 없다는 것입니다. 이 레이어는 에이전트가 호출하는 것과 동일한 actions를 통해 데이터를 읽고 쓰므로, 여기서 연결한 모든 것은 자동으로 에이전트도 수행할 수 있는 작업이 됩니다.
+
+<Diagram id="doc-block-client-overview-1" title={"전통적인 프런트엔드 vs. Agent Native"} summary={"전통적인 프런트엔드는 자신만 접근할 수 있는 자체 API 레이어를 호출합니다. Agent Native에서는 app/과 에이전트가 동일한 actions를 호출하므로, 여기서 만든 모든 기능이 별도의 작업 없이 에이전트도 호출할 수 있게 됩니다."}>
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">전통적인 방식</div>
+    <div class="diagram-node">app/ (React 프런트엔드)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API 레이어</strong>
+      <small class="diagram-muted">프런트엔드만 호출 가능</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>데이터베이스</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (React 프런트엔드)</div>
+      <div class="diagram-node">에이전트</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">동등한 파트너, 동일한 작업</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL 데이터베이스</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## 클라이언트가 맡는 역할 {#role}
+
+브라우저 요청, 에이전트 루프, 외부 API 클라이언트는 모두 동일한 actions와 동일한 SQL 데이터베이스로 귀결됩니다. 에이전트가 접근할 수 없는 별도의 "앱 백엔드"는 이 레이어가 대화할 상대로 존재하지 않습니다. 여기서 기능을 만든다는 것은 에이전트가 이미 가지고 있는 작업 위에 UI를 얹거나, 새로운 action을 정의하면서 동시에 그 UI도 얻는다는 뜻입니다. 이 계약의 작업(operation) 쪽은 [Actions](/docs/actions)를 참조하세요.
+
+이 페이지는 여러분이 작업하는 디렉터리와, 다른 곳에서 다루지 않는 브라우저 런타임의 부분들(`root.tsx`, `public/`)을 다룹니다. 컴포넌트를 actions 및 에이전트와 연결하는 React 후크는 각각 초점이 맞춰진 별도 페이지에 있습니다.
+
+| 페이지                                         | 다루는 내용                                                                                              |
+| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| **[데이터 및 동기화](/docs/client-data)**      | `useActionQuery`, `useActionMutation`, `callAction`, `useDbSync`                                         |
+| **[Agent 채팅](/docs/client-agent-chat)**      | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, 동적 제안, 단계적 에이전트 채팅 컨텍스트 상태 |
+| **[고급](/docs/client-advanced)**              | `application_state` 직접 접근, 백그라운드 채팅 전송, 맞춤 제안 칩, MCP 앱 호스트 브리지                  |
+| **[동기화 내부](/docs/client-sync-internals)** | 원시 `useQuery`를 동기화하기 위한 `useChangeVersion`/`useChangeVersions`                                 |
+| **[엔트리 포인트](/docs/client-entry-points)** | `app/entry.client.tsx`/`app/entry.server.tsx`와 SSR 커스터마이징                                         |
+
+## app/와 public/의 구성 {#project-directories}
+
+| 경로                                                | 다루는 내용                                                                                                              |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| **`app/root.tsx`**                                  | HTML 셸과 provider 스택 — 아래 [브라우저 셸](#app-shell) 참조                                                            |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | 하이드레이션 및 SSR 부트스트랩 — [엔트리 포인트](/docs/client-entry-points) 참조                                         |
+| **`app/routes.ts` + `app/routes/`**                 | 파일 기반 페이지와 내비게이션 — [Routing](/docs/client-routing) 참조                                                     |
+| **`app/components/`**                               | 여러분의 UI: shadcn 스타일 프리미티브와 앱 전용 컴포넌트 — [shadcn/ui](/docs/shadcn-ui) 참조                             |
+| **`app/hooks/`**                                    | 데이터, 동기화, 에이전트 채팅 후크 — [데이터 및 동기화](/docs/client-data) 및 [Agent 채팅](/docs/client-agent-chat) 참조 |
+| **`app/lib/`**                                      | 공유 클라이언트 유틸리티(앱 구성, 탭 id, `cn`) — 아래 [유틸리티](#utilities) 참조                                        |
+| **`app/design-system.ts`**                          | 선택적 커스텀 디자인 시스템 어댑터 — [커스텀 디자인 시스템](/docs/custom-design-system) 참조                             |
+| **`app/i18n/`**                                     | 지역화된 UI 문구 카탈로그 — [국제화](/docs/internationalization) 참조                                                    |
+| **`app/global.css`**                                | 기본 스타일과 Tailwind 진입점                                                                                            |
+| **`public/`**                                       | 그대로 제공되는 정적 자산 — 아래 [정적 자산](#public-directory) 참조                                                     |
+
+## 브라우저 셸: root.tsx와 AppProviders {#app-shell}
+
+`app/root.tsx`는 React 트리의 최상단입니다: HTML 문서 셸(`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`)과, 모든 경로가 그 안에서 렌더링되는 provider 스택입니다.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders`는 다음을 한 번에 연결해 주는 단일 래퍼입니다.
+
+- `useActionQuery`/`useActionMutation`이 사용하는 React Query 클라이언트([데이터 및 동기화](/docs/client-data#fetching-mutating) 참조).
+- `i18n.catalog`로 전달되는 i18n 카탈로그([국제화](/docs/internationalization) 참조).
+- 클라이언트 측 세션 검사: 비공개 경로에서는 익명 방문자가 어떤 비공개 UI도 마운트되기 전에 로그인 화면으로 리디렉션됩니다. 공개/SEO 경로에는 `isPublicPath`를, MCP 임베드 토큰처럼 다른 방식으로 인증되는 표면에는 `sessionBypass`를 전달하세요. [Authentication](/docs/authentication) 참조.
+
+대부분의 앱은 여기에 `<AgentSidebar>` 또는 `<AgentPanel>`도 마운트하여 모든 경로가 별도의 작업 없이 에이전트 패널을 갖게 합니다. [드롭인 에이전트](/docs/drop-in-agent#sidebar) 참조.
+
+## 정적 자산: public/ {#public-directory}
+
+`public/`에 있는 모든 것은 빌드에서 가공되지 않은 채로 사이트 루트에서 그대로 제공됩니다. 모든 템플릿은 다음을 포함합니다.
+
+```text
+public/
+  favicon.svg           -> 브라우저 탭 아이콘
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> manifest.json에서 참조하는 PWA 아이콘
+  manifest.json          -> 웹 앱 매니페스트(이름, 테마 색상, 아이콘)
+  *-logo-*.svg, *-icon-*.svg -> 기본 UI에서 사용하는 브랜드 마크
+```
+
+`manifest.json`은 방문자가 앱을 홈 화면이나 앱 독에 설치할 때 표시되는 내용 — 이름, 짧은 이름, 테마/배경 색상, 아이콘 세트 — 을 제어합니다.
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+이 파일들을 교체하고 `manifest.json`과 `root.tsx`에서 이를 참조하는 `<link rel="icon">`/`<link rel="apple-touch-icon">` 태그를 업데이트하는 것으로 앱을 리브랜딩할 수 있습니다. 별도의 등록 절차는 없습니다. 이런 파일들을 직접 편집하는 대신 기존 사이트에서 전체 브랜드 시스템(색상, 폰트, 파비콘)을 가져오려면 [브랜드 시스템과 Figma](/docs/template-design-brand-and-figma)를 참조하세요.
+
+## 유틸리티: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn`은 클래스 이름을 병합합니다(clsx + tailwind-merge). `app/components/` 전반에서 조건부 Tailwind 클래스를 조합하는 표준적인 방법입니다.
+
+## 다음 단계
+
+- [**데이터 및 동기화**](/docs/client-data) — action 후크와 `useDbSync`
+- [**Agent 채팅**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion`, 동적 제안
+- [**고급**](/docs/client-advanced) — 애플리케이션 상태, 백그라운드 채팅 전송, MCP 앱 호스트 브리지
+- [**동기화 내부**](/docs/client-sync-internals) — 원시 `useQuery`를 동기화하기 위한 `useChangeVersion`
+- [**엔트리 포인트**](/docs/client-entry-points) — SSR 부트스트랩 커스터마이징
+- [**Routing**](/docs/client-routing) — 파일 기반 페이지, 동적 매개변수, 내비게이션
+- [**Actions**](/docs/actions) — 모든 데이터 후크 뒤에 있는 `defineAction` 표면
+- [**커스텀 디자인 시스템**](/docs/custom-design-system) — `app/design-system.ts`를 통해 나만의 컴포넌트 라이브러리로 교체하기
+- [**Authentication**](/docs/authentication) — `AppProviders`가 비공개 경로에서 수행하는 세션 검사
diff --git a/packages/core/docs/content/locales/ko-KR/client-routing.mdx b/packages/core/docs/content/locales/ko-KR/client-routing.mdx
new file mode 100644
index 0000000000..3473737a44
--- /dev/null
+++ b/packages/core/docs/content/locales/ko-KR/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "라우팅"
+description: "React Router v8을 사용하는 에이전트 네이티브 앱의 파일 기반 라우팅: 페이지, 동적 매개변수, 내비게이션."
+---
+
+# 라우팅
+
+에이전트 네이티브 앱은 `@react-router/fs-routes`의 `flatRoutes()`를 통한 파일 기반 라우팅과 함께 **React Router v8**을 사용합니다. `app/routes/`의 모든 파일이 URL이 됩니다. 템플릿은 점 표기법 규칙을 사용합니다. 점은 하나의 파일 이름 안에서 URL 세그먼트를 구분합니다.
+
+이 페이지는 클라이언트 경로, 즉 `app/routes/`에서 브라우저에 렌더링되는 페이지를 다룹니다. 서버 경로는 별도의 시스템입니다: `server/routes/` 아래의 Nitro 파일 경로와, 프레임워크 자체의 `/_agent-native/*` 엔드포인트입니다. 이들은 [Routes](/docs/server-routes) 페이지에 있습니다. 이 둘은 디렉터리도, 명명 규칙도, 라우터도 공유하지 않으므로, `server/routes/`의 파일이 여기서 페이지가 되는 일도 없고 `app/routes/`의 파일이 서버 엔드포인트가 되는 일도 없습니다.
+
+<Diagram id="doc-block-client-routing-1" title={"파일 이름 → URL"} summary={"app/routes/의 각 파일은 URL이 됩니다. 점은 슬래시가 되고, $ 세그먼트는 동적 매개변수가 됩니다."}>
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## 파일 기반 라우팅 {#file-based-routing}
+
+### 파일 → URL 매핑
+
+| 파일                       | URL                    | 참고                                                                                   |
+| -------------------------- | ---------------------- | -------------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | 인덱스 경로                                                                            |
+| `dashboard.tsx`            | `/dashboard`           | 단순한 페이지                                                                          |
+| `extensions.$id.tsx`       | `/extensions/:id`      | `extensions.tsx`의 `<Outlet/>` 안에 중첩됩니다. `$`는 동적 매개변수입니다              |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | 뒤에 붙은 `_`는 `dashboard.tsx` 아래 중첩되는 것을 건너뛰므로 이는 독립된 페이지입니다 |
+| `_app.tsx`                 | (URL 세그먼트 없음)    | 경로 없는 레이아웃입니다. `_`를 접두사로 붙입니다                                      |
+| `inbox/route.tsx`          | `/inbox`               | 폴더 형식입니다. `route.tsx`가 인덱스입니다                                            |
+
+동적 매개변수는 세그먼트에 `$`를 접두사로 붙이세요. 경로 없는 레이아웃 경로(URL 세그먼트 없음)로 만들려면 `_`를 접두사로 붙이거나, 중첩된 것처럼 보이는 경로를 부모의 레이아웃 아래 중첩에서 제외하려면 점 앞에 `_`를 붙이세요. 템플릿은 `flatRoutes()`를 사용합니다. 위의 점 표기법 파일 형식이 기본입니다. 중첩 폴더 형식 `inbox/route.tsx`도 동작합니다.
+
+## 새 페이지 추가하기 {#adding-a-page}
+
+파일을 만들고 기본 컴포넌트를 내보내세요.
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+이것으로 끝입니다. React Router가 별도의 등록 없이 자동으로 이를 인식합니다.
+
+## 동적 매개변수 {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+점 앞에 붙은 `_`는 이 페이지가 `dashboard.tsx`의 `<Outlet/>` 안에 중첩되지 않도록 막아주므로, 티켓 대기열 레이아웃 안에 나타나는 대신 `/dashboard/:ticketId`에서 독립된 전체 페이지로 렌더링됩니다.
+
+## 내비게이션 {#navigation}
+
+클라이언트 측 내비게이션에는 `<Link>`를, 프로그래매틱 내비게이션에는 `useNavigate()`를 사용하세요.
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+이 둘 중 어느 것도 사용자가 지금 무엇을 보고 있는지를 스스로 에이전트에게 알려주지는 않습니다. 이는 별도의 관심사로, `useAgentRouteState()`가 현재 경로를 애플리케이션 상태에 기록함으로써 처리됩니다. [Context Awareness](/docs/context-awareness)를 참조하세요.
+
+## 다음 단계
+
+- [**개요**](/docs/client-overview) — `app/routes/`가 `app/`과 `public/`의 나머지 부분 사이에서 차지하는 위치
+- [**데이터 및 동기화**](/docs/client-data) — 경로 안에서 데이터를 읽고 쓰기
+- [**Agent 채팅**](/docs/client-agent-chat) — 경로에서 프롬프트를 전송하고 컨텍스트를 준비하기
+- [**Routes**](/docs/server-routes) — 별도의 서버 라우팅 시스템: `server/routes/` 아래의 파일 경로와 프레임워크의 `/_agent-native/` 네임스페이스
+- [**Context Awareness**](/docs/context-awareness) — 에이전트가 현재 경로와 선택 상태를 알게 되는 방법
diff --git a/packages/core/docs/content/locales/ko-KR/client-sync-internals.mdx b/packages/core/docs/content/locales/ko-KR/client-sync-internals.mdx
new file mode 100644
index 0000000000..88621ca15b
--- /dev/null
+++ b/packages/core/docs/content/locales/ko-KR/client-sync-internals.mdx
@@ -0,0 +1,133 @@
+---
+title: "동기화 내부"
+description: "useDbSync 뒤에 있는 변경 버전 메커니즘: 원시 useQuery를 동기화하기 위한 useChangeVersion/useChangeVersions, 그리고 다시 가져오기가 거칠 수 있는 두 가지 지연 경로."
+---
+
+# 동기화 내부
+
+[Live Sync](/docs/key-concepts#polling-sync)는 정신적 모델을 다룹니다: 에이전트의 쓰기가 변경 이벤트가 되고, `useDbSync()`가 이를 수신하며, 영향을 받는 쿼리가 다시 가져오기를 합니다. 이 페이지는 그 아래에 있는 메커니즘 — 대부분의 앱이 직접 다루지 않는 — 을 다룹니다: `useDbSync()`가 증가시키는 변경 버전 카운터, 그리고 `useActionQuery()`를 거치지 않는 원시 `useQuery()` 호출에 이를 접목하는 방법입니다.
+
+`useActionQuery()`는 변형 action이 완료되면 이미 자동으로 다시 가져옵니다([데이터 및 동기화](/docs/client-data#fetching-mutating) 참조). `useChangeVersion()`/`useChangeVersions()`는 그 경로 밖에서 원시 `useQuery()` 호출을 동기화할 때 — 예를 들어 통합 상태를 읽는 저수준 클라이언트 헬퍼처럼 — 에만 사용하세요.
+
+## 변경 버전이 작동하는 방식 {#how-it-works}
+
+서버 측 데이터베이스 변형이 발생하면 서버는 `source` 키가 태그된 변경 이벤트를 기록합니다. `useDbSync()`는 그 이벤트를 받아 해당 소스에 대한 로컬 카운터를 증가시킵니다. 이 카운터를 React Query 키에 접어 넣으면, 백엔드가 해당 소스에 대한 새로운 활동을 알릴 때마다 쿼리가 자동으로 다시 가져오기를 합니다.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description: '감시할 변경 이벤트 소스입니다. 예: `"dashboards"`.',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "주어진 소스가 변형될 때마다 증가하는 카운터입니다.",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "한 번에 감시할 여러 개의 변경 이벤트 소스입니다.",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "주어진 모든 소스에 대한 버전 카운터의 합입니다.",
+  }}
+/>
+
+아래 예시에서는 원시 `useQuery()` 호출이 대시보드를 직접 읽으며, `"dashboards"`
+소스의 버전 카운터를 쿼리 키에 접어 넣어 그 소스가 바뀔 때마다 다시 가져오기를
+하도록 합니다.
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev`는 다시 가져오는 동안 화면에 이전 데이터를
+유지하여, 화면이 로딩 상태로 깜빡이지 않도록 합니다.
+
+## 다시 가져오기로 향하는 두 가지 경로 {#latency-models}
+
+변형은 두 가지 방식 중 하나로 UI에 도달하며, 각각 지연 시간이 다릅니다.
+
+여러분 자신의 `useActionMutation()` 호출이 만든 로컬 변형은 성공하는 즉시
+`source: "action"` 이벤트를 발생시킵니다. 그 action에 의존하는 모든 쿼리는
+즉시 다시 가져오기를 합니다. 왕복 지연이 없습니다. 쓰기를 한 탭이 이미
+그것을 알고 있기 때문입니다.
+
+에이전트, 웹훅, 다른 탭, 다른 사용자로부터 온 원격 변형은 먼저 이 탭에
+도달해야 합니다. `useDbSync()`는 SSE를 통해 거의 즉시 이를 수신하거나,
+SSE를 사용할 수 없는 경우 약 2초 안에 폴링 폴백으로 이를 수신합니다. 그
+이벤트가 도착해야만 관련 버전 카운터가 증가하고 쿼리가 백그라운드에서
+다시 가져오기를 합니다.
+
+<Diagram id="doc-block-client-sync-internals-3" title={"다시 가져오기로 향하는 두 가지 경로"} summary={"로컬 변형은 자신의 캐시를 즉시 무효화합니다. 원격 쓰기는 SSE를 통해, 또는 폴백으로서의 폴링을 통해 이 탭에 도달합니다."}>
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">이 탭</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >성공 시 source: "action" 발생 &rarr; 즉시 로컬 다시 가져오기</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">에이전트 · 웹훅 · 다른 탭</span
+      ><strong>원격 쓰기</strong
+      ><small class="diagram-muted"
+        >SSE 푸시, 또는 폴백으로서의 약 2초 폴링 &rarr; 버전 증가 &rarr;
+        백그라운드 다시 가져오기</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## 다음 단계
+
+- [**Live Sync**](/docs/key-concepts#polling-sync) — 이 페이지가 그 아래로 들어가는 개념적 정신 모델
+- [**데이터 및 동기화**](/docs/client-data) — `useActionQuery`/`useDbSync`로, 대부분의 페이지는 이 기본 요소들 대신 이것을 사용해야 합니다
+- [**고급**](/docs/client-advanced) — 그 외의 저수준 클라이언트 기본 요소와 예외적인 방법들
diff --git a/packages/core/docs/content/locales/ko-KR/client.mdx b/packages/core/docs/content/locales/ko-KR/client.mdx
deleted file mode 100644
index 852adaa0b3..0000000000
--- a/packages/core/docs/content/locales/ko-KR/client.mdx
+++ /dev/null
@@ -1,470 +0,0 @@
----
-title: "클라이언트"
-description: "에이전트 네이티브 앱용 React 후크 및 유틸리티: sendToAgentChat, 선택적 에이전트 채팅 컨텍스트 상태, useDbSync, useAgentChatGenerating 및 cn."
----
-
-# 클라이언트
-
-`@agent-native/core`는 에이전트 네이티브 앱의 브라우저 측을 위한 React 후크 및 유틸리티를 제공합니다.
-
-이 클라이언트/React API는 `@agent-native/core` 및 `@agent-native/core/client` 모두에서 내보내집니다. 기본적으로 `@agent-native/core` 루트는 노드 빌드로 확인되므로 명확성과 올바른 번들링을 위해 `@agent-native/core/client`(브라우저 항목)에서 가져옵니다.
-
-파일 기반 라우팅(페이지, 동적 매개변수 및 탐색 추가)의 경우 [Routing](/docs/routing)를 참조하세요.
-
-## 데이터 가져오기 및 변형 {#fetching-mutating}
-
-브라우저에서 앱 데이터를 읽고 쓰는 기본 방법은 작업 후크를 이용하는 것입니다. `/_agent-native/*` 경로에 대한 `fetch` 호출을 직접 작성하지 마세요. 대신 명명된 도우미를 사용하세요([Actions](/docs/actions) 참조).
-
-<Diagram id="doc-block-151ykjv" title={"브라우저 데이터 루프"} summary={"후크는 작업을 통해 읽고 씁니다. useDbSync은 데이터베이스를 감시하므로 에이전트 및 백그라운드 쓰기가 동일한 캐시를 자동으로 다시 가져옵니다."}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>SQL 데이터베이스</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(옵션) {#sendtoagentchat}
-
-UI 상호 작용에서 AI 작업을 위임하는 일반적인 방법인 postMessage를 통해 에이전트 채팅에 메시지를 보냅니다. 숨겨진 모델 컨텍스트의 경우 `context`를 전달하고 즉시 전송하려면 `submit: true`를 전달하거나 사용자가 먼저 검토하는 초안을 미리 채우려면 `submit: false`를 전달하세요.
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-`embedApp()`로 생성된 MCP 앱 삽입 내부, 자동 제출된 메시지
-(`submit` 생략 또는 `true`)은 MCP 앱 호스트 브리지로 전달됩니다.
-포함된 호스트에게 숨겨진 컨텍스트를 추가하고 표시되는 사용자 차례를 보내도록 요청합니다.
-`context`는 사용자 대면 채팅으로 게시되지 않고 모델 표시 상태를 유지합니다.
-`submit: false`는 MCP 앱이 로컬 미리 채우기/검토 동작을 유지하지 않기 때문에
-표준 초안 미리 채우기 API를 정의합니다. 내부적으로 제출된 채팅 경로입니다
-때때로 `agentNative.submitChat`로 나타납니다. 앱 코드는 호출해야 합니다
-그 이벤트를 직접 게시하는 것보다 `sendToAgentChat()`
-
-### 무음 배경 전송 {#background-send}
-
-UI 작업으로 실제 에이전트 작업을 시작해야 하는 경우 `background: true`를 사용하세요.
-사이드바 열기 또는 초점 맞추기. 그래도 일반 채팅 스레드/실행이 생성됩니다.
-에이전트의 도구/actions/context를 사용하고 다음을 통해 작업을 관찰 가능하게 유지합니다
-실행 트레이; 이는 원시적인 일회성 모델 호출이 아닙니다.
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background`는 `newTab`와 쌍을 이루도록 고안되었으므로 숨겨진 작업은 수행되지 않습니다.
-사용자의 활성 대화를 덮어씁니다. UI인 경우 반환된 `tabId`를 사용하세요.
-후속 작업 상태를 연관시키거나 나중에 실행에 대한 딥 링크를 연결해야 합니다.
-
-### 에이전트채팅메시지 {#agentchatmessage}
-
-| 옵션                  | 유형        | 설명                                                                                 |
-| --------------------- | ----------- | ------------------------------------------------------------------------------------ |
-| `message`             | `string`    | 채팅에 전송된 시각적 메시지                                                          |
-| `context`             | `string?`   | 숨겨진 컨텍스트가 추가되었습니다(채팅 UI에는 표시되지 않음)                          |
-| `submit`              | `boolean?`  | true = 자동 제출, false = 미리 채우기만                                              |
-| `newTab`              | `boolean?`  | 이 메시지에 대해 별도의 채팅 스레드를 생성하세요                                     |
-| `background`          | `boolean?`  | `newTab`를 사용하면 탭에 초점을 맞추지 않고 실행하고 `RunsTray`에 실행을 표시합니다. |
-| `openSidebar`         | `boolean?`  | 사이드바를 열지 않고 제출/미리 채우려면 false로 설정                                 |
-| `projectSlug`         | `string?`   | 구조화된 컨텍스트를 위한 선택적 프로젝트 슬러그                                      |
-| `preset`              | `string?`   | 다운스트림 소비자를 위한 선택적 사전 설정 이름                                       |
-| `referenceImagePaths` | `string[]?` | 선택적 참조 이미지 경로                                                              |
-
-## 에이전트 채팅 컨텍스트 상태(고급) {#agent-chat-context-state}
-
-컨텍스트 상태 API는 양방향 동기화가 필요한 UI에 대한 선택적 배관입니다.
-단계적 컨텍스트 칩: 현재 단계적 항목을 작성기 외부에 렌더링
-항목이 이미 첨부되었는지 여부를 반영하거나 명시적으로 제공
-컨트롤 제거/삭제.
-
-간단한 "에이전트에게 보내기"를 위해 이러한 도우미에게 연락하지 마세요.
-"검토를 위해 이 초안을 미리 작성하세요" 흐름. `context`와 함께 `sendToAgentChat()` 사용
-그리고 `submit`도 있습니다.
-
-| API                               | 다음 경우에 사용                                                           |
-| --------------------------------- | -------------------------------------------------------------------------- |
-| `useAgentChatContext()`           | React 구성요소에는 라이브 스테이지 컨텍스트 목록이 필요합니다              |
-| `setAgentChatContextItem(item)`   | 명령형 코드는 하나의 키 컨텍스트 항목을 준비하거나 대체해야 합니다.        |
-| `listAgentChatContext()`          | React가 아닌 코드에는 단계적 컨텍스트의 일회성 스냅샷이 필요합니다.        |
-| `removeAgentChatContextItem(key)` | UI는 안정적인 `key`에 의해 하나의 단계적 컨텍스트 항목을 제거해야 합니다.  |
-| `clearAgentChatContext()`         | UI는 보기 또는 모드 재설정 후와 같이 모든 단계적 컨텍스트를 지워야 합니다. |
-| `refreshAgentChatContext()`       | 명령형 코드는 최신 지속 컨텍스트 스냅샷을 다시 읽어야 합니다.              |
-
-`useAgentChatContext()`는 `{ items, set, remove, clear, refresh }`를 반환합니다.
-
-## openAgentSettings(섹션?) {#openagentsettings}
-
-앱 설정 페이지나 설정 카드가 열려야 할 때 `openAgentSettings()`를 사용하세요
-에이전트 사이드바의 설정 탭. `"llm"`, `"secrets"`와 같은 섹션 ID를 전달하세요.
-`"automations"`, `"voice"` 또는 `"limits"`를 사용하여 특정 섹션을 엽니다.
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-`agent-panel:open-settings`를 직접 파견하는 것보다 이 도우미를 선호하세요.
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()`는 검사만 필요한 명령형 코드용입니다.
-현재 준비된 항목은 한 번입니다. `clearAgentChatContext()`는 의도적으로 광범위합니다. 사용
-하나의 선택만 변경된 경우 `removeAgentChatContextItem(key)`.
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| 옵션          | 유형       | 설명                                                           |
-| ------------- | ---------- | -------------------------------------------------------------- |
-| `key`         | `string`   | 기존 너겟을 대체하는 데 사용되는 안정적인 식별자               |
-| `title`       | `string`   | 작곡기 칩에 표시되는 짧은 라벨                                 |
-| `context`     | `string`   | 다음 제출 메시지에 숨겨진 컨텍스트가 포함됨                    |
-| `openSidebar` | `boolean?` | 기본값은 true입니다. false를 스테이지 컨텍스트에 자동으로 전달 |
-
-## askUserQuestion(opts) {#ask-user-question}
-
-사용자에게 앱 코드에서 객관식 질문을 하고 인라인으로 렌더링
-상담원 패널, **답변을 기다립니다**. 이는 클라이언트 측 쌍입니다.
-에이전트에 내장된 `ask-question` 도구: `GuidedQuestionPayload`를
-`"guided-questions"` 애플리케이션 상태 키(마운트된 위치
-`GuidedQuestionFlow`가 렌더링) 에이전트 패널을 표시하므로 질문은 다음과 같습니다.
-표시됩니다. 답변이 상담원에게 다시 전달되는 상담원 도구와는 달리
-`askUserQuestion()` **발신자의 응답으로 해결**하므로 UI는
-그쪽으로 가지를 치세요.
-
-UI가 실행하기 전에 정확히 하나의 작은 결정(2~4개 옵션)이 필요할 때 사용하세요.
-사용자 정의 모달을 구축하는 대신 에이전트 작업을 시작합니다.
-자유형 세부정보를 위한 작성기 및 다중 필드 입력을 위한 양식/팝오버
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-각 옵션은 `{ label, value?, description?, preview?, recommended? }`입니다. `value`
-기본값은 `label`이고 `preview`는 아래에 작은 모형/코드 조각을 렌더링합니다.
-option. The promise resolves with the selected `value` (or `value[]` when
-`allowMultiple`), 사용자가 "기타"를 선택한 경우의 자유 텍스트 문자열 또는 `null`
-건너뛰는 경우 — 사용자가 응답할 때까지 보류 상태로 유지됩니다. 에이전트 패널이 필요합니다
-마운트됩니다(모든 템플릿에 있음).
-
-에이전트는 `ask-question` 도구를 통해 동일한 UI에 도달합니다.
-에이전트는 *it*이 실제 포크에 도달하면 컨텍스트에서 해결할 수 없는지 묻습니다. 사용
-`askUserQuestion()` *UI*가 선택 항목에 대한 조치를 취해야 할 때
-
-## MCP 앱 호스트 브리지 {#mcp-app-host-bridge}
-
-MCP 앱으로 포함된 경로는 URL 우선이어야 합니다. 다음에서 현재 아티팩트를 로드합니다.
-경로/쿼리 매개변수, 실제 React 경로 또는 집중된 공유 구성요소 렌더링
-호스트 소유 동작에만 호스트 브리지를 사용합니다. `@agent-native/core/client`
-도우미가 포함된 경로 호출을 내보냅니다.
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()`는 최근 푸시된 호스트 컨텍스트 스냅샷을 읽습니다.
-`useMcpAppHostContext()`는 React 구성 요소를 변경 사항에 등록합니다. 요청
-도우미(`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
-`updateMcpAppModelContext`) 임베디드 MCP 앱 프레임 외부에서 `false`를 반환하거나
-프레임 내부의 `Promise<boolean>`. `sendToAgentChat()`는 동일한 브리지를 사용하여
-삽입된 경로에서 자동 제출된 프롬프트.
-
-브릿지 자체 — `ui/*` JSON-RPC 메시지, `agentNative.mcpHost.*`
-래퍼 릴레이, 이식 및 제어 프레임 렌더링, 호스트 컨텍스트
-디스플레이 모드 요청 — 소유
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## 동적 제안 {#dynamic-suggestions}
-
-`<AgentSidebar>`, `<AgentPanel>` 및 `<AssistantChat>`는 기본적으로 정적 `suggestions`를 상황 인식 제안과 병합합니다. 프레임워크는 빈 채팅이 표시되는 동안 애플리케이션 상태에서 `navigation`, `selection`, `pending-selection-context` 및 현재 URL를 읽은 다음 현재 화면과 일치하는 프롬프트 칩을 제공합니다.
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-정적 칩만 유지하도록 `dynamicSuggestions={false}`를 설정합니다. 앱이 동일한 애플리케이션 상태 컨텍스트에서 결정적인 도메인별 칩을 원하는 경우 `getSuggestions`를 전달하세요.
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-로드 상태 추적으로 sendToAgentChat을 래핑하는 React 후크:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-`isGenerating`는 `send()`를 호출하면 true로 바뀌고 에이전트가 생성을 마치면 자동으로 false로 재설정됩니다.
-
-## useDbSync(옵션?) {#usedbsync}
-
-SSE에 대한 데이터베이스 변경 사항을 수신하고 폴링으로 대체하며 UI를 에이전트 쓰기와 일치하도록 유지하는 프레임워크 쿼리 캐시를 무효화하는 React 후크(이전 `useFileWatcher`):
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### 옵션 {#usedbsync-options}
-
-| 옵션               | 유형               | 설명                                                                                   |
-| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | 캐시 무효화를 위한 React 쿼리 클라이언트                                               |
-| `queryKeys`        | `string[]?`        | 더 이상 사용되지 않으며 무시됩니다. 기존 통화 사이트용으로 유지됨                      |
-| `pollUrl`          | `string?`          | 폴링 끝점 URL. 기본값: `"/_agent-native/poll"`                                         |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
-| `interval`         | `number?`          | 폴링 간격(ms) 기본값: `2000`                                                           |
-| `fallbackInterval` | `number?`          | SSE를 사용할 수 없는 경우 대체 폴링 간격입니다. 기본값: `15000`                        |
-| `pauseWhenHidden`  | `boolean?`         | 브라우저 탭이 숨겨져 있으면 폴링을 일시 중지합니다. 기본값: `true`                     |
-| `ignoreSource`     | `string?`          | 탭이 자체 쓰기에서 다시 가져오지 않도록 무시할 탭별 요청 소스                          |
-| `onEvent`          | `(data) => void`   | SSE/폴링이 변경 이벤트를 수신할 때 선택적 콜백                                         |
-
-일반 CRUD의 경우 `useActionQuery` 및 `useActionMutation`를 선호합니다. actions를 변형하면 `source: "action"`가 방출되고 해당 후크는 자동으로 다시 가져옵니다.
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-프레임워크는 변경 버전을 사용하여 React 쿼리 캐시를 백그라운드 에이전트, 크론 작업 또는 다른 사용자가 변경한 내용과 동기화합니다.
-
-서버 측 데이터베이스 변형이 발생하면 서버는 특정 `source` 키를 사용하여 변경 이벤트를 기록합니다. 클라이언트의 `useDbSync` 수신기는 이러한 이벤트를 수신하고 해당 소스에 대한 로컬 변경 버전 카운터를 범프합니다. 버전 카운터를 React 쿼리 키에 추가하면 백엔드가 클라이언트에 새 활동을 알릴 때마다 쿼리가 자동으로 다시 가져옵니다.
-
-- **`useChangeVersion(source: string): number`** — 지정된 `source`가 변경될 때마다 증가하는 카운터를 반환합니다.
-- **`useChangeVersions(sources: readonly string[]): number`** — 여러 소스에 대한 버전 카운터의 합계를 반환합니다.
-
-### 예: 원시 쿼리를 데이터베이스와 동기화
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### 지연 모델 및 무효화 동작
-
-- **UI 시작 돌연변이:** `useActionMutation`를 사용하여 UI에서 작업을 실행할 때 돌연변이는 성공 시 즉시 `source: "action"`를 사용하여 로컬 이벤트를 실행합니다. 이렇게 하면 해당 작업에 따라 모든 쿼리 키의 **즉각적이고 낙관적인 다시 가져오기**가 트리거되어 시각적 지연이 방지됩니다.
-- **백그라운드 또는 에이전트 돌연변이:** AI 에이전트, 웹훅 또는 백그라운드 작업자가 데이터를 변형하면 업데이트가 클라이언트에 브로드캐스트됩니다. 클라이언트의 `useDbSync`는 SSE(서버 전송 이벤트)를 통해 즉시 이를 캡처하거나 **2초 폴링 틱**으로 폴백합니다. 그런 다음 쿼리 키 버전이 충돌하여 백그라운드 다시 가져오기가 트리거됩니다.
-
-<Diagram id="doc-block-q6d3kk" title={"다시 가져오기를 위한 두 가지 경로"} summary={"로컬 돌연변이는 자체 캐시를 즉시 무효화합니다. 원격 쓰기는 SSE 또는 대체 폴링 틱을 통해 이 탭에 도달합니다."}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">이 탭</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">에이전트 · webhook · 다른 탭</span
-      ><strong>원격 쓰기</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...입력) {#cn}
-
-클래스 이름 병합을 위한 유틸리티(clsx + tailwind-merge):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/ko-KR/drop-in-agent.mdx b/packages/core/docs/content/locales/ko-KR/drop-in-agent.mdx
index b1e72641d4..96a4db4e8e 100644
--- a/packages/core/docs/content/locales/ko-KR/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/ko-KR/drop-in-agent.mdx
@@ -225,7 +225,7 @@ sendToAgentChat({
 
 동일한 경로가 MCP 앱으로 삽입된 경우 제출
 `sendToAgentChat()` 통화는 지원되는 호스트 채팅으로 전달됩니다. 참조
-MCP 앱 브리지 동작을 위한 [Client](/docs/client#sendtoagentchat).
+MCP 앱 브리지 동작을 위한 [Agent 채팅](/docs/client-agent-chat#sendtoagentchat).
 
 로드 상태를 원하면 `useSendToAgentChat()` 후크를 사용하세요. `send`와 `isGenerating`를 모두 반환합니다.
 
diff --git a/packages/core/docs/content/locales/ko-KR/notifications.mdx b/packages/core/docs/content/locales/ko-KR/notifications.mdx
index f252f238d6..4a6a6ca2f2 100644
--- a/packages/core/docs/content/locales/ko-KR/notifications.mdx
+++ b/packages/core/docs/content/locales/ko-KR/notifications.mdx
@@ -363,7 +363,7 @@ export function HeaderBar() {
 ## 작동 방식 {#internals}
 
 - **소유자 범위** — 모든 행에는 `owner` 열이 있습니다. 모든 쿼리는 이를 필터링합니다. 모든 경로는 인증된 세션의 이메일을 사용합니다. 사용자는 서로의 알림을 볼 수 없습니다.
-- **폴 통합** — 모든 변이는 `recordChange()`를 호출하므로 [`useDbSync`](/docs/client)를 사용하는 템플릿은 추가 배선 없이 자동 무효화됩니다.
+- **폴 통합** — 모든 변이는 `recordChange()`를 호출하므로 [`useDbSync`](/docs/client-data#usedbsync)를 사용하는 템플릿은 추가 배선 없이 자동 무효화됩니다.
 - **최선의 팬아웃** — 채널 오류가 포착되어 기록됩니다. 하나의 실패한 채널이 다른 채널이나 받은편지함 쓰기를 차단하지 않습니다.
 - **Fire-and-forget** — 받은 편지함 쓰기가 완료된 후 `notify()`가 반환됩니다. 맞춤 채널은 백그라운드에서 실행됩니다.
 
diff --git a/packages/core/docs/content/locales/ko-KR/progress.mdx b/packages/core/docs/content/locales/ko-KR/progress.mdx
index 2308e3beca..af2b3689a4 100644
--- a/packages/core/docs/content/locales/ko-KR/progress.mdx
+++ b/packages/core/docs/content/locales/ko-KR/progress.mdx
@@ -233,7 +233,7 @@ mode: agentic
 ## 작동 방식 {#internals}
 
 - **소유자 범위** — 모든 행에는 `owner` 열이 있습니다. 모든 쿼리는 이를 필터링합니다. 사용자는 자신의 달리기만 볼 수 있습니다.
-- **폴링 통합** — 모든 변이는 `recordChange()`를 호출하므로 [`useDbSync`](/docs/client)를 사용하는 템플릿은 추가 배선 없이 자동 무효화됩니다.
+- **폴링 통합** — 모든 변이는 `recordChange()`를 호출하므로 [`useDbSync`](/docs/client-data#usedbsync)를 사용하는 템플릿은 추가 배선 없이 자동 무효화됩니다.
 - **테이블 이름** — 프레임워크에는 내부 상담원-채팅 차례 수명 주기 추적을 위한 `agent_runs` 테이블도 있습니다. 진행 프리미티브는 `progress_runs`를 사용하여 두 가지 문제를 별도로 유지합니다.
 - **비율 고정** — 값은 `[0, 100]`로 고정되고 쓰기 시 정수로 반올림됩니다.
 
@@ -241,4 +241,4 @@ mode: agentic
 
 - [**Notifications**](/docs/notifications) — `manage-progress`(`action=complete`)와 페어링하여 작업이 완료되면 사용자에게 알려줍니다.
 - [**Automations**](/docs/automations) — `run.progress.updated`를 통한 워치독 느린 실행
-- [**Client**](/docs/client) — 실시간 캐시 무효화를 위한 `useDbSync`
+- [**데이터 및 동기화**](/docs/client-data) — 실시간 캐시 무효화를 위한 `useDbSync`
diff --git a/packages/core/docs/content/locales/ko-KR/real-time-collaboration.mdx b/packages/core/docs/content/locales/ko-KR/real-time-collaboration.mdx
index a59bf099d8..d0830f4497 100644
--- a/packages/core/docs/content/locales/ko-KR/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/ko-KR/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ description: "AI 에이전트가 최고 수준의 피어인 다중 사용자 공
 에이전트와 함께 편집하는 것은 협업 편집기에서 작업하는 것과 같습니다.
 즉각적이고 지치지 않는 동료:
 
-상담원이나 다른 사용자가 SQL에 쓸 때 새로 고치기 위해 UI만 필요한 경우에는 이 중 어떤 것도 필요하지 않습니다. [`useDbSync`](/docs/client)를 사용하세요. 이 페이지는 단일 서식 있는 텍스트 문서의 문자 수준 공동 편집을 위한 것입니다(공유 커서, 충돌 없는 병합). 둘 다 동일한 `/_agent-native/poll` 채널을 타고 있습니다.
+상담원이나 다른 사용자가 SQL에 쓸 때 새로 고치기 위해 UI만 필요한 경우에는 이 중 어떤 것도 필요하지 않습니다. [`useDbSync`](/docs/client-data#usedbsync)를 사용하세요. 이 페이지는 단일 서식 있는 텍스트 문서의 문자 수준 공동 편집을 위한 것입니다(공유 커서, 충돌 없는 병합). 둘 다 동일한 `/_agent-native/poll` 채널을 타고 있습니다.
 
 이것은 **Yjs**(충돌 없는 병합을 위한 CRDT), **TipTap**(서식 있는 텍스트 편집기) 및 **폴링 기반 동기화**(서버리스 및 엣지를 포함한 모든 배포 환경에서 작동)의 세 가지 검증된 기술을 기반으로 구축되었습니다.
 
@@ -772,7 +772,7 @@ undoManager.redo(); // Shift+Cmd+Z
 
 ## 관련 문서 {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) — `useDbSync` + `useChangeVersion`
+- [동기화 내부](/docs/client-sync-internals) — `useDbSync` + `useChangeVersion`
   `updatedAt` 범프 드라이빙 에디터 조정을 제공하는 시스템
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   리소스 범위 협업에 사용하는 `assertAccess`입니다.
diff --git a/packages/core/docs/content/locales/ko-KR/routing.mdx b/packages/core/docs/content/locales/ko-KR/routing.mdx
deleted file mode 100644
index 672fc15288..0000000000
--- a/packages/core/docs/content/locales/ko-KR/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "라우팅"
-description: "React 라우터 v8을 사용한 에이전트 기반 앱을 위한 파일 기반 라우팅 — 페이지, 동적 매개변수 및 탐색."
----
-
-# 라우팅
-
-에이전트 네이티브 앱은 `@react-router/fs-routes`에서 `flatRoutes()`를 통한 파일 기반 라우팅과 함께 **React 라우터 v8**을 사용합니다. `app/routes/`의 모든 파일은 URL가 됩니다. 템플릿은 점 표기법 규칙을 사용합니다. 점은 단일 파일 이름 내에서 URL 세그먼트를 구분합니다.
-
-## 파일 기반 라우팅 {#file-based-routing}
-
-### 파일 → URL 매핑
-
-| 파일                  | URL                 | 참고                                   |
-| --------------------- | ------------------- | -------------------------------------- |
-| `_index.tsx`          | `/`                 | 색인 경로                              |
-| `settings.tsx`        | `/settings`         | 간단한 페이지                          |
-| `inbox.$threadId.tsx` | `/inbox/:threadId`  | 점 = `/`, `$` = 동적 매개변수          |
-| `_app.tsx`            | (URL 세그먼트 없음) | 경로 없는 레이아웃 — 접두사 `_`        |
-| `inbox/route.tsx`     | `/inbox`            | 폴더 형식 - `route.tsx`가 인덱스입니다 |
-
-동적 매개변수의 경우 세그먼트 앞에 `$`를 붙입니다. 경로 없는 레이아웃 경로(URL 세그먼트 없음)로 만들려면 접두사 `_`를 붙입니다. 템플릿은 `flatRoutes()`를 사용합니다. 위의 점 표기법 파일이 기본입니다. 중첩 폴더 형식 `inbox/route.tsx`도 작동합니다.
-
-<Diagram id="doc-block-lgrfn7" title={"경로 없는 레이아웃이 페이지를 래핑합니다."} summary={"_app.tsx 레이아웃(URL 세그먼트 없음)은 공유 쉘을 한 번 렌더링합니다. 일치하는 페이지는 <Outlet/> 내부에서 렌더링되므로 탐색 시 에이전트 사이드바가 다시 탑재되지 않습니다."}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >경로 없는 레이아웃 · 지속 셸 + 에이전트 사이드바</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## 새 페이지 추가 {#adding-a-page}
-
-파일 생성 및 기본 구성 요소 내보내기:
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-그렇습니다. React 라우터가 자동으로 선택하므로 등록이 필요하지 않습니다.
-
-## 동적 매개변수 {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## 탐색 {#navigation}
-
-클라이언트 측 탐색에는 `<Link>`를 사용하고 프로그래밍 방식 탐색에는 `useNavigate()`를 사용하세요.
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## 다음 단계
-
-- [**Client**](/docs/client) — 에이전트 기반 브라우저 후크 및 유틸리티
-- [**Server**](/docs/server) — 파일 기반 서버 경로 및 `/_agent-native/` 네임스페이스
diff --git a/packages/core/docs/content/locales/pt-BR/client-advanced.mdx b/packages/core/docs/content/locales/pt-BR/client-advanced.mdx
new file mode 100644
index 0000000000..b9ff8b5250
--- /dev/null
+++ b/packages/core/docs/content/locales/pt-BR/client-advanced.mdx
@@ -0,0 +1,192 @@
+---
+title: "Avançado"
+description: "Primitivas de nível mais baixo e válvulas de escape de app/: acesso direto ao estado do aplicativo, envios de chat em segundo plano, chips de sugestão personalizados, e a ponte de host do MCP App."
+---
+
+# Avançado
+
+Visão geral, Dados e sincronização, Chat do Agent, e Roteamento cobrem o caso típico: os ganchos e auxiliares que a maioria das páginas precisa. Esta página cobre as primitivas de nível mais baixo e as válvulas de escape mais estreitas por trás deles. A maioria dos aplicativos nunca toca nisso diretamente. Recorra a uma dessas quando você estiver construindo algo mais personalizado do que os ganchos padrão suportam, como uma sincronização de seleção personalizada ou um MCP App incorporado. Para sincronizar um `useQuery` bruto com uma chave feita à mão, veja [Sincronização interna](/docs/client-sync-internals) em vez disso.
+
+## Estado do aplicativo {#application-state}
+
+`application_state` é o armazenamento de chave/valor com backend em SQL que o agente lê para saber o que a UI está exibindo atualmente, incluindo navegação, seleção, e outro contexto de objeto em foco (veja [Consciência do Contexto](/docs/context-awareness)). `useAgentRouteState` e `useSemanticNavigationState` (também cobertos em Consciência do Contexto) já envolvem essas primitivas para o caso comum de navegação. Recorra às primitivas abaixo diretamente quando você estiver sincronizando algo que elas não cobrem, como uma seleção personalizada, ou gravando a partir de fora da renderização de um componente.
+
+### readClientAppState {#read-client-app-state}
+
+Lê o valor atual de uma chave. Resolve para o que foi gravado por último para essa chave, ou `null` se a chave nunca foi gravada.
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection é exatamente o que foi gravado por último nessa chave, ex.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// ou, se nada foi gravado em "selection" ainda:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+Grava um valor para uma chave. Diferente de `setClientAppState` abaixo, ele sempre grava, mesmo se você passar `null`. Passar `undefined` gera um erro em vez disso, já que `undefined` não é um JSON válido. Use `setClientAppState(key, undefined)` ou `deleteClientAppState()` para limpar uma chave.
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+O wrapper de conveniência que a maioria do código de UI deve usar: grava o valor, ou exclui a chave quando você passa `null`/`undefined`. Use este em vez de `writeClientAppState`, a menos que um call site realmente precise de "sempre gravar, nunca excluir."
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // limpa a chave, o mesmo que deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+Remove uma chave inteiramente.
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+Lê várias chaves em uma solicitação. Retorna `{ values, missing }`. `values` mantém uma entrada para toda chave para a qual o servidor tem uma linha, incluindo uma chave que foi explicitamente gravada como `null`. `missing` lista as chaves que nunca foram gravadas. É assim que "nunca gravada" permanece distinguível de "gravada como null."
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+Solicitações com mais de 100 chaves são divididas automaticamente. `readClientAppState()` em si é construído sobre isto: chamadas emitidas no mesmo tick são combinadas em uma única solicitação em lote nos bastidores, então chamá-lo muitas vezes em uma única passagem de renderização custa uma viagem de ida e volta, não uma por chamada.
+
+### Opções {#application-state-options}
+
+`signal` é aceito pelas cinco funções acima, para cancelar uma chamada em andamento. `requestSource` e `keepalive` se aplicam apenas às três funções de gravação, já que não significam nada para uma leitura.
+
+| Opção           | Tipo           | Aplica-se a                                                        | Descrição                                                                                                             |
+| --------------- | -------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Marca a gravação com um id para que um `useDbSync({ ignoreSource })` correspondente possa pular sua nova busca        |
+| `keepalive`     | `boolean?`     | `writeClientAppState`, `setClientAppState`, `deleteClientAppState` | Permite que a solicitação sobreviva ao descarregamento da página. Use para gravações de limpeza como limpar a seleção |
+| `signal`        | `AbortSignal?` | todas as cinco funções                                             | Cancela a solicitação                                                                                                 |
+
+### Comportamento de falha {#failure-behavior}
+
+Todas as cinco funções lançam um erro em caso de falha na solicitação, uma resposta não-2xx, ou um corpo que não pode ser analisado. O `Error` lançado carrega uma propriedade `.status` quando o servidor respondeu, para que um chamador possa se ramificar com base no status HTTP se necessário. Envolva uma chamada em `try`/`catch`, ou deixe-a propagar para um error boundary, da mesma forma que qualquer outra chamada de rede.
+
+### O que é o TAB_ID {#tab-id}
+
+`requestSource` é comumente definido como `TAB_ID`, uma constante simples que todo template exporta de `app/lib/tab-id.ts`: uma string curta e aleatória que permanece a mesma durante a vida de uma aba e difere entre abas. Combinar `requestSource: TAB_ID` em uma gravação com `useDbSync({ ignoreSource: TAB_ID })` no lado da leitura é como uma aba evita buscar novamente sua própria gravação enquanto ainda reage a todo o resto. Veja [Consciência do Contexto](/docs/context-awareness#jitter-prevention) para o passo a passo completo.
+
+## sendToAgentChat: envios em segundo plano {#background-send}
+
+Use `background: true` quando uma ação de UI deve iniciar trabalho real do agente sem
+abrir ou focar a barra lateral. Isso ainda cria uma thread/execução de chat normal,
+usa as ferramentas/actions/contexto do agente, e mantém o trabalho observável através
+da bandeja de execuções. Não é uma chamada de modelo pontual e crua.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` é destinado a ser combinado com `newTab` para que o trabalho oculto não
+sobrescreva a conversa ativa do usuário. Use o `tabId` retornado se a UI
+precisar correlacionar o status de acompanhamento ou criar um link direto para a execução mais tarde.
+
+Algumas opções adicionais de `AgentChatMessage` existem além das cobertas em [Chat do Agent](/docs/client-agent-chat#agentchatmessage), principalmente para casos incorporados ou de integração downstream:
+
+| Opção                 | Tipo        | Descrição                                                               |
+| --------------------- | ----------- | ----------------------------------------------------------------------- |
+| `background`          | `boolean?`  | Com `newTab`, executa sem focar a aba e mostra a execução em `RunsTray` |
+| `projectSlug`         | `string?`   | Slug de projeto opcional para contexto estruturado                      |
+| `preset`              | `string?`   | Nome de preset opcional para consumidores downstream                    |
+| `referenceImagePaths` | `string[]?` | Caminhos de imagem de referência opcionais                              |
+
+## Ponte de host do MCP App {#mcp-app-host-bridge}
+
+Rotas incorporadas como MCP Apps devem ser URL-first: carregar o artefato atual a partir de
+parâmetros de caminho/query, renderizar a rota React real ou um componente compartilhado focado,
+e usar a ponte de host apenas para comportamento de propriedade do host. `@agent-native/core/client`
+exporta os auxiliares que rotas incorporadas chamam:
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` lê o último snapshot de contexto de host enviado.
+`useMcpAppHostContext()` inscreve componentes React para mudanças. Os auxiliares de solicitação
+(`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
+`updateMcpAppModelContext`) retornam `false` fora de um frame de MCP App incorporado, ou
+`Promise<boolean>` dentro de um frame.
+
+`sendToAgentChat()` (veja [Chat do Agent](/docs/client-agent-chat#sendtoagentchat)) usa a mesma ponte para prompts enviados automaticamente a partir de rotas incorporadas. Dentro de um embed de MCP App criado com `embedApp()`, mensagens enviadas automaticamente (`submit` omitido ou `true`) são encaminhadas para a ponte, que pede ao host que o contém para adicionar contexto oculto e enviar o turno visível do usuário. `context` permanece visível para o modelo sem ser postado como chat voltado ao usuário. `submit: false` mantém o comportamento local de preenchimento prévio/revisão porque MCP Apps não definem uma API padrão de rascunho pré-preenchido. Internamente, este é o caminho de chat enviado, às vezes exposto como `agentNative.submitChat`. O código do aplicativo ainda deve chamar `sendToAgentChat()` em vez de postar esse evento diretamente.
+
+A ponte em si, as mensagens `ui/*` JSON-RPC, o relay de wrapper
+`agentNative.mcpHost.*`, transplante vs. renderização de frame controlado, contexto de host, e
+solicitações de modo de exibição, é de responsabilidade de
+[External Agents](/docs/external-agents#mcp-app-bridge). Veja [Aplicativos MCP](/docs/mcp-apps) para o protocolo completo.
+
+## Chips de sugestão personalizados {#custom-suggestions}
+
+`dynamicSuggestions` de `<AgentSidebar>` (veja [Chat do Agent](/docs/client-agent-chat#dynamic-suggestions)) já mescla as `suggestions` estáticas com a heurística de reconhecimento de contexto própria da estrutura. Passe `getSuggestions` em vez disso quando um aplicativo quiser chips determinísticos e específicos do domínio, calculados a partir do mesmo contexto de `application_state`, em vez da heurística padrão da estrutura.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` recebe o mesmo snapshot de `navigation`/`selection`/`pending-selection-context` que a heurística integrada lê, então uma implementação personalizada pode reagir exatamente ao mesmo estado que a padrão reage, apenas com regras específicas do aplicativo em vez de regras genéricas.
+
+## O que vem a seguir
+
+- [**Visão geral**](/docs/client-overview) — o layout de diretórios `app/` e `public/` onde essas primitivas vivem
+- [**Dados e sincronização**](/docs/client-data) — os ganchos de action padrão e `useDbSync` que a maioria das páginas deve usar em vez disso
+- [**Sincronização interna**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions` e os dois caminhos de latência que uma nova busca pode seguir
+- [**Chat do Agent**](/docs/client-agent-chat) — os auxiliares padrão `sendToAgentChat`/`askUserQuestion` que a maioria da UI deve usar em vez disso, e as APIs de estado de contexto do chat do agente preparado
+- [**Pontos de entrada**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` e personalização de streaming de SSR
+- [**Consciência do Contexto**](/docs/context-awareness) — a semântica de `navigation`/`selection` construída sobre `application_state`, e o passo a passo de `TAB_ID`/prevenção de jitter
+- [**Generative UI**](/docs/generative-ui) — controles de chat inline mais ricos além de `askUserQuestion`
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — os internos completos da ponte de host do MCP App
diff --git a/packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx b/packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx
new file mode 100644
index 0000000000..ad7692ad32
--- /dev/null
+++ b/packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx
@@ -0,0 +1,315 @@
+---
+title: "Chat do Agent"
+description: "Pontos de entrada do lado do cliente para o chat do agente: sendToAgentChat, openAgentSettings, askUserQuestion, sugestões dinâmicas, useAgentChatGenerating, e o estado de contexto do chat do agente preparado."
+---
+
+# Chat do Agent
+
+O cliente do seu aplicativo pode conversar com o agente através de um pequeno conjunto de auxiliares de cliente. Eles cobrem enviar um prompt, preparar contexto oculto, fazer uma pergunta bloqueante ao usuário, e abrir o painel do agente.
+
+No exemplo abaixo, um botão **Draft response** solicita que o agente faça uma pergunta ao usuário. Depois que o usuário responde, o agente parte para redigir uma resposta levando em conta o contexto atual da página e a resposta do usuário.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="Captura de tela do aplicativo Dispatch mostrando a barra lateral de histórico de execuções"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Barra lateral de histórico de execuções do Dispatch."
+/>
+
+## Como funciona
+
+Usando os métodos auxiliares de cliente fornecidos pelo Agent-Native, sua UI pode fazer o agente interagir com o usuário de várias formas. O diagrama abaixo demonstra como um botão "Draft response" pode ser clicado pelo usuário, o que então leva o agente a interagir com o usuário antes de gerar uma resposta.
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="Diagrama de sequência intitulado 'quem é responsável por cada etapa', mostrando três linhas de vida: App Code, UI e Agent. O usuário clica em 'draft response', disparando askUserQuestion(). Uma nota explica que isso renderiza inline no painel do agente. O usuário responde, então sendDraftRequest() é chamado no Agent, que chama draft-ticket-reply e retorna uma resposta redigida ao composer da UI."
+  align="full"
+  width={600}
+  caption="Diagrama de sequência visualizando o fluxo de um botão 'Draft response'."
+/>
+
+A experiência do usuário é a seguinte:
+
+1. O usuário clica no botão **Draft response**, o que faz com que a função `askUserQuestion()` seja chamada. A pergunta é respondida inline no painel do agente.
+
+1. O usuário escolhe **Offer a refund**, o que faz com que `sendDraftRequest()` envie o prompt e o contexto do ticket ao agente.
+
+1. O agente chama a [action](/docs/actions) `draft-ticket-reply`, e a resposta redigida aparece no composer de resposta.
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "A pergunta, suas opções, e como ela deve se comportar.",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description:
+            "A pergunta completa. Clara, específica, termina com um ponto de interrogação.",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            'Chip/cabeçalho muito curto, cerca de 12 caracteres, ex. `"Response"`.',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2-4 opções distintas. Cada uma é `{ label, value?, description?, preview?, recommended? }`. `value` tem como padrão `label`.",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description:
+            'Adiciona uma opção "Other" de texto livre em que o representante pode digitar.',
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "Seleção múltipla em vez de seleção única.",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description:
+            "Chave de estado do aplicativo que o painel do agente consulta.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      'O `value` escolhido (ou `value[]` quando `allowMultiple`), o texto "Other" digitado pelo representante, ou `null` se ele pular. Fica pendente até que ele responda. Requer que o painel do agente esteja montado, o que ocorre em todo template.',
+  }}
+/>
+
+Esta função faz ao usuário uma pergunta de múltipla escolha a partir do código do aplicativo, renderiza-a inline no painel do agente, e aguarda a resposta. Use-a quando a UI precisar de uma pequena decisão com duas a quatro opções antes de iniciar o trabalho do agente, em vez de construir um modal personalizado.
+
+No exemplo abaixo, um botão "Draft Response" na página de um ticket pergunta ao representante como ele gostaria de responder antes de enviar qualquer coisa ao agente:
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // chip/cabeçalho curto opcional (≈12 caracteres)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "Uma tupla `[isGenerating, send]`. `isGenerating` é `true` a partir do momento em que `send()` é chamado até que a execução do chat do agente reporte que parou. `send(opts)` tem a mesma assinatura de `sendToAgentChat()`, e retorna o id da aba para o qual foi despachado.",
+  }}
+/>
+
+Este gancho React envolve `sendToAgentChat()` com rastreamento de estado de carregamento.
+
+1. O primeiro argumento, `isGenerating`, se torna verdadeiro quando você o chama, e volta para falso quando o agente termina de gerar.
+
+2. O segundo argumento, `send()`, espelha a função `sendToAgentChat()`.
+
+`isGenerating` só volta ao estado inicial quando uma execução de fato começa e reporta que parou. Uma chamada com `submit: false` preenche previamente um rascunho sem iniciar uma execução, então `isGenerating` fica `true` para sempre depois de uma dessas chamadas. Use este gancho apenas para envios com `submit: true`; chame `sendToAgentChat()` diretamente para envios apenas de preenchimento prévio.
+
+Combinar isto com o exemplo de `askUserQuestion()` acima completa o manipulador do botão:
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="Completando o manipulador do Draft Response"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "Estado de carregamento + envio, juntos",
+      note: "`useAgentChatGenerating()` retorna a mesma forma de tupla de uma chamada `sendToAgentChat()` simples, mas adiciona `isDrafting` para que o botão possa se desativar enquanto a solicitação está em andamento.",
+    },
+    {
+      lines: "10-17",
+      label: "Reutiliza a etapa de pergunta",
+      note: "Esta é exatamente a chamada `askUserQuestion()` da seção acima, agora dentro do próprio manipulador do botão.",
+    },
+    {
+      lines: "18",
+      label: "Restrinja antes de usar a resposta",
+      note: "O tipo de retorno sempre permite `string[]` por causa de `allowMultiple`, então essa verificação é necessária mesmo que esta chamada nunca a defina.",
+    },
+    {
+      lines: "20-25",
+      label: "Transforme a escolha em uma frase",
+      note: "Mapeia o valor selecionado, ou o próprio texto digitado pelo representante, para a frase que o prompt abaixo lê naturalmente.",
+    },
+    {
+      lines: "27-32",
+      label: "Nomeie a action e a intenção",
+      note: "A mensagem informa ao agente exatamente qual action chamar (`draft-ticket-reply`) e o lembra de não enviar a resposta diretamente. `openSidebar: true` garante que a resposta redigida fique visível mesmo que a barra lateral estivesse fechada.",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting controla o botão",
+      note: "Desativado e renomeado apenas enquanto `sendDraftRequest()` está em andamento. O botão permanece clicável enquanto `askUserQuestion()` espera pelo representante, já que isso acontece antes que `sendDraftRequest()` seja chamado.",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+Envie uma mensagem para o chat do agente via `postMessage`. Esta é a primitiva de nível mais baixo que `useAgentChatGenerating()` acima encapsula, útil quando uma interação de UI não precisa de rastreamento de estado de carregamento próprio. Passe `context` para detalhes extras que a mensagem por si só não carrega. Ele é anexado à mesma mensagem visível, envolvido em tags `<context>`. Não fica oculto do usuário. Passe `submit: true` para enviar imediatamente, ou `submit: false` para preencher previamente um rascunho que o usuário revisa primeiro.
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| Opção         | Tipo       | Descrição                                                                                           |
+| ------------- | ---------- | --------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | O prompt enviado ao chat. `context`, se definido, é anexado a esta mesma mensagem visível           |
+| `context`     | `string?`  | Detalhe extra anexado à mensagem visível, envolvido em tags `<context>`. Não fica oculto do usuário |
+| `submit`      | `boolean?` | true = envio automático, false = apenas preenchimento prévio                                        |
+| `newTab`      | `boolean?` | Cria uma thread de chat separada para este prompt                                                   |
+| `openSidebar` | `boolean?` | Defina como false para enviar/preencher sem abrir a barra lateral                                   |
+
+Executar isso de dentro de um embed de MCP App, ou colocar a execução em segundo plano sem abrir a barra lateral, ambos são cobertos em [Avançado](/docs/client-advanced#background-send).
+
+## Sugestões dinâmicas {#dynamic-suggestions}
+
+Antes que uma conversa comece, `<AgentSidebar>`, `<AgentPanel>` e `<AssistantChat>` mostram chips de prompt no chat vazio. Por padrão, esses não são apenas sua lista fixa de `suggestions`: a estrutura lê `navigation`, `selection`, `pending-selection-context`, e a URL atual do estado do aplicativo, e mescla chips que correspondem ao que está de fato na tela.
+
+Ela faz isso com duas verificações. Se algo está selecionado, adiciona chips genéricos como "Summarize this selection". Separadamente, ela examina `navigation` por nomes de campo que aplicativos já usam com frequência, como `threadId`/`emailId` para uma thread de e-mail ou `dashboardId`/`chartId` para um gráfico, e adiciona chips adaptados a esse tipo de tela, como "Draft a reply" para uma thread ou "Find anomalies in this data" para um gráfico. O que quer que ela produza é mesclado com suas `suggestions` estáticas, desduplicado, e limitado a `max`.
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+Se a tela atual não corresponder a nada que a heurística reconheça e nada estiver selecionado, ela não contribui com nenhum chip, e o chat vazio recorre apenas às suas `suggestions` estáticas. Defina `dynamicSuggestions={false}` para manter apenas chips estáticos. Se o formato de navegação do seu aplicativo não corresponder à heurística integrada, ou você quiser chips específicos do aplicativo totalmente determinísticos, veja [Avançado](/docs/client-advanced#custom-suggestions).
+
+## openAgentSettings(section?) {#openagentsettings}
+
+Use `openAgentSettings()` quando uma página de configurações do aplicativo ou um card de setup
+deve abrir a aba Settings da barra lateral do agente. Passe um id de seção como `"llm"`, `"secrets"`,
+`"automations"`, `"voice"`, ou `"limits"` para abrir uma seção específica.
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+Prefira este auxiliar em vez de despachar `agent-panel:open-settings` diretamente.
+
+## Estado de contexto do chat do agente {#agent-chat-context-state}
+
+As APIs de estado de contexto são encanamento opcional para UI que precisa de sincronização bidirecional com chips de contexto preparado: renderizar os itens preparados atuais fora do composer, refletir se um item já está anexado, ou fornecer controles explícitos de remoção/limpeza.
+
+Não recorra a esses auxiliares para fluxos simples de "enviar isto ao agente" ou "preencher este rascunho para revisão". Use [`sendToAgentChat()`](#sendtoagentchat) com `context` e `submit` para esses casos.
+
+| API                               | Use quando                                                                           |
+| --------------------------------- | ------------------------------------------------------------------------------------ |
+| `useAgentChatContext()`           | Um componente React precisa da lista de contexto preparado em tempo real             |
+| `setAgentChatContextItem(item)`   | Código imperativo deve preparar ou substituir um item de contexto identificado       |
+| `listAgentChatContext()`          | Código não React precisa de uma captura pontual do contexto preparado                |
+| `removeAgentChatContextItem(key)` | UI deve remover um item de contexto preparado pela sua `key` estável                 |
+| `clearAgentChatContext()`         | UI deve limpar todo o contexto preparado, como após um reset de visualização ou modo |
+| `refreshAgentChatContext()`       | Código imperativo deve reler o snapshot de contexto persistido mais recente          |
+
+`useAgentChatContext()` retorna `{ items, set, remove, clear, refresh }`.
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` é para código imperativo que só precisa inspecionar os itens preparados atuais uma vez. `clearAgentChatContext()` é deliberadamente amplo. Use `removeAgentChatContextItem(key)` quando apenas uma seleção mudou.
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| Opção         | Tipo       | Descrição                                                               |
+| ------------- | ---------- | ----------------------------------------------------------------------- |
+| `key`         | `string`   | Identificador estável usado para substituir um item existente           |
+| `title`       | `string`   | Etiqueta curta mostrada no chip do composer                             |
+| `context`     | `string`   | Contexto oculto incluído com o próximo prompt enviado                   |
+| `openSidebar` | `boolean?` | Padrão verdadeiro. Passe false para preparar o contexto silenciosamente |
+
+## O que vem a seguir
+
+- [**Visão geral**](/docs/client-overview) — onde esses auxiliares se encaixam em `app/`
+- [**Dados e sincronização**](/docs/client-data) — os ganchos de action e `useDbSync` que mantêm a própria UI atualizada
+- [**Agente de visita**](/docs/drop-in-agent) — montando `<AgentSidebar>`/`<AgentPanel>` para que esses auxiliares tenham onde renderizar
+- [**Avançado**](/docs/client-advanced) — envios em segundo plano, chips de sugestão personalizados, e a ponte de host do MCP App
+- [**Generative UI**](/docs/generative-ui) — construindo controles de chat inline mais ricos além de `askUserQuestion`
diff --git a/packages/core/docs/content/locales/pt-BR/client-data.mdx b/packages/core/docs/content/locales/pt-BR/client-data.mdx
new file mode 100644
index 0000000000..8dcf6194a9
--- /dev/null
+++ b/packages/core/docs/content/locales/pt-BR/client-data.mdx
@@ -0,0 +1,434 @@
+---
+title: "Dados e sincronização"
+description: "Os ganchos de action que app/ usa para ler, gravar e permanecer sincronizado em tempo real com as mesmas actions que o agente chama."
+---
+
+# Dados e sincronização
+
+A principal forma de ler e gravar dados do aplicativo a partir do cliente é através dos ganchos de [action](/docs/actions). Ao incorporar solicitações em actions, tanto seu cliente quanto o agente podem interagir com seu aplicativo da mesma maneira.
+
+No exemplo abaixo, um ticket é atribuído ao usuário atual manualmente através de um dropdown, e depois através do agente de chat. Tanto a UI quanto o agente acessam a mesma action.
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="Exemplo de uma action de UI e uma action de agente tendo o mesmo resultado."
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Exemplo de uma action de UI e uma action de agente tendo o mesmo resultado."
+/>
+
+## Buscar e mutar dados {#fetching-mutating}
+
+Um aplicativo típico constrói sua própria camada de API e a chama com solicitações `fetch` escritas manualmente. Um aplicativo nativo do agente pula essa camada: `app/` chama as mesmas actions que o agente já tem como ferramentas, através dos ganchos abaixo.
+
+<Diagram id="doc-block-client-data-fm-1" title="Fetch típico vs. um gancho de action" summary="Um componente típico chama uma rota que só ele pode acessar. Um componente nativo do agente chama uma action que o agente também pode chamar.">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Típico</div>
+    <div class="diagram-node">Componente</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Sua rota de API</strong>
+      <small class="diagram-muted">só o front-end pode chamá-la</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Banco de dados</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">Componente</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">action get-lead</span>
+      <small class="diagram-muted">também uma ferramenta do agente</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Banco de dados SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Ganchos de action {#action-hooks}
+
+Existem dois ganchos de action que você provavelmente vai usar: `useActionQuery()` e `useActionMutation()`. Esses dois ganchos dão acesso às actions do seu aplicativo.
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "O nome registrado da action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "A entrada da action, tipada a partir do esquema de `defineAction()`.",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "Tudo das [opções de useQuery](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery), exceto `queryKey` e `queryFn`, que o gancho define por conta própria.",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      'Armazenado em cache sob `["action", name, params]`. Busca novamente de forma automática sempre que uma action de mutação é concluída, sem necessidade de invalidação manual.',
+  }}
+/>
+
+Este gancho é destinado a actions somente leitura. É um wrapper leve em torno da função [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery).
+
+No exemplo abaixo, a action `list-tickets` é chamada. Isso é semelhante a fazer uma solicitação GET para todos os tickets.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+O exemplo a seguir mostra uma solicitação para buscar um único ticket, através da action `get-ticket`. Um `ticketId` é fornecido para restringir a consulta a retornar apenas um ticket específico. A opção adicional `enabled` é fornecida para garantir que a consulta não seja executada automaticamente, e sim apenas quando um `ticketId` estiver presente.
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "O nome registrado da action.",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "Tudo das [opções de useMutation](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation), exceto `mutationFn`, que o gancho define por conta própria.",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Substitui o método de solicitação padrão.",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Desativa a atualização automática do cache em caso de sucesso.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      'Em caso de sucesso, emite um evento de mudança com `source: "action"`, para que toda `useActionQuery()` que lê dados afetados busque novamente de forma automática. Nenhuma invalidação manual é necessária.',
+  }}
+/>
+
+Este gancho é destinado a actions que alteram dados, como criar, atualizar ou enviar algo. É um wrapper leve em torno da função [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation).
+
+Diferente de `useActionQuery()`, a entrada da action não é passada para o gancho em si. Ela é passada para `mutate()` ou `mutateAsync()` quando você estiver pronto para executar a mutação.
+
+No exemplo abaixo, a action `send-ticket-reply` é chamada para postar uma resposta em um ticket. Chame `mutate()` a partir de um manipulador de evento, como o `onClick` de um botão.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+O exemplo a seguir mostra a mesma mutação com uma opção `onSuccess`. A invalidação de cache acontece automaticamente após cada mutação, então `onSuccess` só é necessário para efeitos colaterais locais, como limpar o composer de resposta depois que a resposta é enviada.
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "O nome registrado da action.",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description:
+        "A entrada da action, tipada a partir do esquema de `defineAction()`.",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "Tudo abaixo é opcional.",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "Substitui o método de solicitação padrão.",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "Cancela a solicitação.",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Substitui o tempo limite padrão de 60 segundos, para actions que legitimamente demoram mais.",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "Diferente dos ganchos acima, não há cache e nenhuma nova busca automática. Combine com uma invalidação manual se outra UI depender do resultado.",
+  }}
+/>
+
+Esta função é destinada a chamadas de action imperativas e pontuais fora de um fluxo de renderização React, como um manipulador de evento simples, um script, ou qualquer outro caminho de código que não seja React. Ela retorna uma promise diretamente, em vez de um resultado de gancho.
+
+No exemplo abaixo, a action `update-ticket` é chamada a partir de um manipulador de atalho de teclado fora do fluxo de renderização do React, atribuindo o ticket a um representante.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+O exemplo a seguir mostra a mesma chamada com uma opção `timeoutMs`, útil para actions que legitimamente demoram mais do que o tempo limite padrão de 60 segundos.
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+Toda solicitação `useActionQuery()`, `useActionMutation()` e `callAction()` é limitada por um tempo limite de 60 segundos, e os tempos limite surgem como erros em vez de tentar novamente silenciosamente. `useActionQuery()` também cancela solicitações substituídas automaticamente, usando o abort signal do React Query.
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "Todo campo é opcional.",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "Cliente React Query usado para invalidação de cache.",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "URL do endpoint de pesquisa.",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description:
+            "URL do endpoint SSE. Passe `false` para usar apenas pesquisa (polling).",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "Intervalo de pesquisa em ms.",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "Intervalo de pesquisa enquanto o SSE está conectado, como backup no caso de um evento ser perdido. Uma aba desconectada faz a pesquisa no ritmo mais rápido `interval` (ou um ritmo fixo ocioso) em vez disso.",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "Pausa a pesquisa quando a aba do navegador está oculta. Abas ocultas mantêm o SSE conectado e pesquisam no máximo a cada 10s enquanto ativas, 60s quando ociosas.",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "Origem de solicitação por aba a ser ignorada, para que uma aba não busque novamente a partir de suas próprias gravações.",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description:
+            "Callback opcional quando o SSE ou a pesquisa recebe um evento de mudança.",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "Filtra a invalidação ampla que um evento de action dispara. Raramente necessário. Use para manter uma consulta ativa cara em semântica de atualização explícita enquanto consultas normais versionadas por origem continuam reagindo através de `useChangeVersion`.",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "Nomes de actions cujos eventos de sincronização não devem invalidar todas as consultas de action. Apenas para actions de alto volume em segundo plano que já realizam sua própria invalidação restrita.",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description: "Obsoleto e ignorado. Mantido para call sites antigos.",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+Este gancho é destinado a manter a UI sincronizada com mudanças no banco de dados que ocorrem fora das suas próprias actions, como uma gravação do agente, um webhook, ou uma mudança feita em outra aba do navegador. Ele escuta mudanças por server-sent events, e recorre à pesquisa quando server-sent events não estão disponíveis.
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+Para CRUD normal, prefira `useActionQuery()` e `useActionMutation()`. Actions de mutação emitem `source: "action"`, então esses ganchos buscam novamente imediatamente. Mudanças do agente, de um webhook, ou de outra aba chegam através de `useDbSync()` em vez disso, via SSE ou o fallback de pesquisa. Se uma chamada `useQuery()` bruta precisa sincronizar em uma chave personalizada, veja [Sincronização interna](/docs/client-sync-internals). Se você precisa gravar diretamente em `application_state`, veja [Avançado](/docs/client-advanced).
+
+## O que vem a seguir
+
+- [**Visão geral**](/docs/client-overview) — o layout de diretórios `app/` e `public/` onde os ganchos desta página vivem
+- [**Chat do Agent**](/docs/client-agent-chat) — enviando prompts e preparando contexto para o agente
+- [**Actions**](/docs/actions) — a superfície `defineAction` por trás de cada gancho desta página
+- [**Avançado**](/docs/client-advanced) — acesso direto a `application_state`
+- [**Sincronização interna**](/docs/client-sync-internals) — sincronizando um `useQuery` bruto com `useChangeVersion`
+- [**Sincronização em tempo real**](/docs/key-concepts#polling-sync) — como `useDbSync` mantém a UI atualizada
diff --git a/packages/core/docs/content/locales/pt-BR/client-entry-points.mdx b/packages/core/docs/content/locales/pt-BR/client-entry-points.mdx
new file mode 100644
index 0000000000..cab61c60d0
--- /dev/null
+++ b/packages/core/docs/content/locales/pt-BR/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "Pontos de entrada"
+description: "app/entry.client.tsx e app/entry.server.tsx: os wrappers leves de bootstrap de hidratação e SSR, e quando personalizar o comportamento de streaming."
+---
+
+# Pontos de entrada
+
+`app/entry.client.tsx` hidrata o HTML renderizado pelo servidor no navegador, e `app/entry.server.tsx` renderiza esse HTML no servidor. Ambos são wrappers leves gerados pelo React Router. Você raramente precisa editá-los.
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+Recorra a eles apenas para personalização avançada de SSR, por exemplo mudando o comportamento de streaming. Páginas, layout e dados comuns não precisam de mudanças aqui. Veja [Roteamento](/docs/client-routing) para adicionar páginas em vez disso.
+
+## O que vem a seguir
+
+- [**Visão geral**](/docs/client-overview) — onde esses arquivos se encaixam em `app/`
+- [**Roteamento**](/docs/client-routing) — adicionando páginas, a forma normal de estender `app/`
+- [**Avançado**](/docs/client-advanced) — as outras primitivas de cliente de nível mais baixo e válvulas de escape
diff --git a/packages/core/docs/content/locales/pt-BR/client-overview.mdx b/packages/core/docs/content/locales/pt-BR/client-overview.mdx
new file mode 100644
index 0000000000..850fc4a176
--- /dev/null
+++ b/packages/core/docs/content/locales/pt-BR/client-overview.mdx
@@ -0,0 +1,206 @@
+---
+title: "Visão geral"
+description: "Os diretórios app/ e public/: onde você constrói a exibição de um aplicativo nativo do agente, e as APIs de navegador que ele usa para se manter sincronizado com o agente."
+---
+
+# Visão geral
+
+`app/` é onde você constrói a exibição real de um aplicativo nativo do agente: páginas, layout, componentes, estilos. `public/` armazena os ativos estáticos servidos junto com ela — ícones, manifesto, elementos de marca. Este é um aplicativo React Router v8 típico, não uma superfície exclusiva para agentes, e é onde a maior parte do tempo de desenvolvimento é gasto.
+
+A única diferença arquitetural em relação a um front-end típico: esta camada não tem seu próprio backend-for-frontend. Ela lê e grava dados através das mesmas actions que o agente chama, então qualquer coisa conectada aqui é automaticamente algo que o agente também pode fazer.
+
+<Diagram id="doc-block-client-overview-1" title="Front-end tradicional vs. Agent Native" summary="Um front-end tradicional chama sua própria camada de API, que só ele pode acessar. No Agent Native, app/ e o agente chamam as mesmas actions, então toda capacidade construída aqui é utilizável pelo agente de graça.">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Tradicional</div>
+    <div class="diagram-node">app/ (front-end React)</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>Camada de API</strong>
+      <small class="diagram-muted">somente o front-end a chama</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Banco de dados</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/ (front-end React)</div>
+      <div class="diagram-node">Agente</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">parceiros iguais, mesmas operações</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>Banco de dados SQL</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Onde o cliente se encaixa {#role}
+
+Solicitações do navegador, o loop do agente e clientes de API externos resolvem todos para as mesmas actions e o mesmo banco de dados SQL — não existe um "backend de aplicativo" separado com o qual esta camada conversa e que o agente não possa também alcançar. Construir um recurso aqui significa construir uma UI sobre uma operação que o agente já possui, ou definir uma nova action e ganhar uma UI para ela ao mesmo tempo. Veja [Actions](/docs/actions) para o lado da operação desse contrato.
+
+Esta página cobre os diretórios em que você constrói e as partes do runtime do navegador que nenhum outro lugar documenta (`root.tsx`, `public/`). Os ganchos React que conectam seus componentes às actions e ao agente vivem em suas próprias páginas focadas:
+
+| Página                                                   | O que ela cobre                                                                                                                      |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| **[Dados e sincronização](/docs/client-data)**           | `useActionQuery`, `useActionMutation`, `callAction` e `useDbSync`                                                                    |
+| **[Chat do Agent](/docs/client-agent-chat)**             | `sendToAgentChat`, `askUserQuestion`, `openAgentSettings`, sugestões dinâmicas, e o estado de contexto do chat do agente preparado   |
+| **[Avançado](/docs/client-advanced)**                    | Acesso direto a `application_state`, envios de chat em segundo plano, chips de sugestão personalizados, e a ponte de host do MCP App |
+| **[Sincronização interna](/docs/client-sync-internals)** | `useChangeVersion`/`useChangeVersions` para sincronizar um `useQuery` bruto                                                          |
+| **[Pontos de entrada](/docs/client-entry-points)**       | `app/entry.client.tsx`/`app/entry.server.tsx` e personalização de SSR                                                                |
+
+## O que há em app/ e public/ {#project-directories}
+
+| Caminho                                             | O que ela cobre                                                                                                                               |
+| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | O shell HTML e a pilha de provedores — veja [O Shell do Navegador](#app-shell) abaixo                                                         |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Bootstrap de hidratação e SSR — veja [Pontos de entrada](/docs/client-entry-points)                                                           |
+| **`app/routes.ts` + `app/routes/`**                 | Páginas baseadas em arquivo e navegação — veja [Roteamento](/docs/client-routing)                                                             |
+| **`app/components/`**                               | Sua UI: primitivas no estilo shadcn mais componentes específicos do aplicativo — veja [shadcn/ui](/docs/shadcn-ui)                            |
+| **`app/hooks/`**                                    | Ganchos de dados, sincronização e chat do agente — veja [Dados e sincronização](/docs/client-data) e [Chat do Agent](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | Utilitários de cliente compartilhados (config do app, id da aba, `cn`) — veja [Utilitários](#utilities) abaixo                                |
+| **`app/design-system.ts`**                          | Adaptador opcional de sistema de design personalizado — veja [Sistemas de design personalizados](/docs/custom-design-system)                  |
+| **`app/i18n/`**                                     | Catálogos de textos de UI localizados — veja [Internacionalização](/docs/internationalization)                                                |
+| **`app/global.css`**                                | Estilos base e o ponto de entrada do Tailwind                                                                                                 |
+| **`public/`**                                       | Ativos estáticos servidos como estão — veja [Ativos estáticos](#public-directory) abaixo                                                      |
+
+## O Shell do Navegador: root.tsx e AppProviders {#app-shell}
+
+`app/root.tsx` é o topo da árvore React: o shell do documento HTML (`<html>`, `<head>`, `<Meta>`, `<Links>`, `<Scripts>`) mais a pilha de provedores que toda rota renderiza dentro.
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` é o único wrapper que conecta:
+
+- O cliente React Query usado por `useActionQuery`/`useActionMutation` (veja [Dados e sincronização](/docs/client-data#fetching-mutating)).
+- O catálogo de i18n passado como `i18n.catalog` (veja [Internacionalização](/docs/internationalization)).
+- Verificações de sessão no lado do cliente: em um caminho privado, um visitante anônimo é redirecionado para o login antes que qualquer UI privada seja montada. Passe `isPublicPath` para rotas públicas/SEO, ou `sessionBypass` para uma superfície que se autentica de outra forma, como um token de embed MCP. Veja [Autenticação](/docs/authentication).
+
+A maioria dos aplicativos também monta `<AgentSidebar>` ou `<AgentPanel>` aqui, para que toda rota ganhe o painel do agente de graça. Veja [Agente de visita](/docs/drop-in-agent#sidebar).
+
+## Ativos estáticos: public/ {#public-directory}
+
+Tudo em `public/` é servido como está na raiz do site, sem processamento pelo build. Todo template inclui:
+
+```text
+public/
+  favicon.svg           -> ícone da aba do navegador
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> ícones PWA referenciados em manifest.json
+  manifest.json          -> manifesto de web app (nome, cor do tema, ícones)
+  *-logo-*.svg, *-icon-*.svg -> marcas usadas na UI padrão
+```
+
+`manifest.json` controla o que aparece se um visitante instalar o aplicativo em uma tela inicial ou dock — nome, nome curto, cor do tema/fundo, e o conjunto de ícones:
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+Rebatize um aplicativo substituindo esses arquivos e atualizando `manifest.json` e as tags `<link rel="icon">`/`<link rel="apple-touch-icon">` em `root.tsx` que os referenciam — não há uma etapa de registro separada. Para extrair um sistema de marca completo (cores, fontes, favicon) de um site existente em vez de editar esses arquivos manualmente, veja [Sistemas de marca e Figma](/docs/template-design-brand-and-figma).
+
+## Utilitários: cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` mescla nomes de classe (clsx + tailwind-merge) e é a maneira padrão de compor classes Tailwind condicionais em `app/components/`.
+
+## O que vem a seguir
+
+- [**Dados e sincronização**](/docs/client-data) — os ganchos de action e `useDbSync`
+- [**Chat do Agent**](/docs/client-agent-chat) — `sendToAgentChat`, `askUserQuestion`, e sugestões dinâmicas
+- [**Avançado**](/docs/client-advanced) — estado do aplicativo, envios de chat em segundo plano, e a ponte de host do MCP App
+- [**Sincronização interna**](/docs/client-sync-internals) — `useChangeVersion` para sincronizar um `useQuery` bruto
+- [**Pontos de entrada**](/docs/client-entry-points) — personalização do bootstrap de SSR
+- [**Roteamento**](/docs/client-routing) — páginas baseadas em arquivo, parâmetros dinâmicos e navegação
+- [**Actions**](/docs/actions) — a superfície `defineAction` por trás de cada gancho de dados
+- [**Sistemas de design personalizados**](/docs/custom-design-system) — trocando sua própria biblioteca de componentes via `app/design-system.ts`
+- [**Autenticação**](/docs/authentication) — as verificações de sessão que `AppProviders` executa em caminhos privados
diff --git a/packages/core/docs/content/locales/pt-BR/client-routing.mdx b/packages/core/docs/content/locales/pt-BR/client-routing.mdx
new file mode 100644
index 0000000000..b51d3950a9
--- /dev/null
+++ b/packages/core/docs/content/locales/pt-BR/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "Roteamento"
+description: "Roteamento baseado em arquivo para aplicativos nativos do agente com React Router v8: páginas, parâmetros dinâmicos e navegação."
+---
+
+# Roteamento
+
+Aplicativos nativos do agente usam **React Router v8** com roteamento baseado em arquivo via `flatRoutes()` de `@react-router/fs-routes`. Todo arquivo em `app/routes/` se torna uma URL. Templates usam a convenção de notação por ponto. Pontos separam segmentos de URL dentro de um único nome de arquivo.
+
+Esta página cobre as rotas de cliente, as páginas renderizadas no navegador a partir de `app/routes/`. Rotas de servidor são um sistema separado: rotas de arquivo Nitro sob `server/routes/`, além dos próprios endpoints `/_agent-native/*` da estrutura. Elas vivem na página [Rotas](/docs/server-routes). Os dois não compartilham um diretório, uma convenção de nomenclatura, ou um roteador, então um arquivo em `server/routes/` nunca se torna uma página aqui e um arquivo em `app/routes/` nunca se torna um endpoint de servidor.
+
+<Diagram id="doc-block-client-routing-1" title="Nome de arquivo → URL" summary="Cada arquivo em app/routes/ se torna uma URL. Pontos se tornam barras, e um segmento $ se torna um parâmetro dinâmico.">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Roteamento baseado em arquivo {#file-based-routing}
+
+### Mapeamento de arquivo → URL
+
+| Arquivo                    | URL                    | Notas                                                                                  |
+| -------------------------- | ---------------------- | -------------------------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | Rota de índice                                                                         |
+| `dashboard.tsx`            | `/dashboard`           | Página simples                                                                         |
+| `extensions.$id.tsx`       | `/extensions/:id`      | Aninha dentro do `<Outlet/>` de `extensions.tsx`. `$` é um parâmetro dinâmico          |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | O `_` no final pula o aninhamento sob `dashboard.tsx`, então esta é sua própria página |
+| `_app.tsx`                 | (sem segmento de URL)  | Layout sem caminho. Prefixe com `_`                                                    |
+| `inbox/route.tsx`          | `/inbox`               | Formato de pasta. `route.tsx` é o índice                                               |
+
+Prefixe um segmento com `$` para um parâmetro dinâmico. Prefixe com `_` para torná-lo uma rota de layout sem caminho (sem segmento de URL), ou adicione um `_` no final antes de um ponto para tirar um caminho que parece aninhado do aninhamento sob o layout do seu pai. Templates usam `flatRoutes()`. O arquivo em notação por ponto acima é o principal. O formato de pasta aninhada `inbox/route.tsx` também funciona.
+
+## Adicionando uma nova página {#adding-a-page}
+
+Crie o arquivo e exporte um componente padrão:
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+É isso. O React Router a detecta automaticamente, sem necessidade de registro.
+
+## Parâmetros dinâmicos {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+O `_` no final antes do ponto impede que esta página aninhe dentro do `<Outlet/>` de `dashboard.tsx`, então ela renderiza como sua própria página completa em `/dashboard/:ticketId` em vez de aparecer dentro do layout da fila de tickets.
+
+## Navegação {#navigation}
+
+Use `<Link>` para navegação do lado do cliente e `useNavigate()` para navegação programática:
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+Nenhum dos dois informa ao agente o que o usuário está vendo por conta própria. Essa é uma preocupação separada, tratada por `useAgentRouteState()` gravando a rota atual no estado do aplicativo. Veja [Consciência do Contexto](/docs/context-awareness).
+
+## O que vem a seguir
+
+- [**Visão geral**](/docs/client-overview) — onde `app/routes/` se encaixa entre o resto de `app/` e `public/`
+- [**Dados e sincronização**](/docs/client-data) — lendo e gravando dados dentro de uma rota
+- [**Chat do Agent**](/docs/client-agent-chat) — enviando prompts e preparando contexto a partir de uma rota
+- [**Rotas**](/docs/server-routes) — o sistema separado de roteamento de servidor: rotas de arquivo sob `server/routes/` e o namespace `/_agent-native/` da estrutura
+- [**Consciência do Contexto**](/docs/context-awareness) — como o agente aprende a rota e a seleção atuais
diff --git a/packages/core/docs/content/locales/pt-BR/client-sync-internals.mdx b/packages/core/docs/content/locales/pt-BR/client-sync-internals.mdx
new file mode 100644
index 0000000000..69dec4a825
--- /dev/null
+++ b/packages/core/docs/content/locales/pt-BR/client-sync-internals.mdx
@@ -0,0 +1,127 @@
+---
+title: "Sincronização interna"
+description: "O mecanismo de versão de mudança por trás de useDbSync: useChangeVersion/useChangeVersions para sincronizar um useQuery bruto, e os dois caminhos de latência que uma nova busca pode seguir."
+---
+
+# Sincronização interna
+
+[Sincronização ao vivo](/docs/key-concepts#polling-sync) cobre o modelo mental: uma gravação do agente se torna um evento de mudança, `useDbSync()` a capta, e as consultas afetadas buscam novamente. Esta página cobre o mecanismo por trás disso que a maioria dos aplicativos nunca toca diretamente: os contadores de versão de mudança que `useDbSync()` incrementa, e como incorporá-los em uma chamada `useQuery()` bruta que não está passando por `useActionQuery()`.
+
+`useActionQuery()` já busca novamente automaticamente quando uma action de mutação é concluída (veja [Dados e sincronização](/docs/client-data#fetching-mutating)). Recorra a `useChangeVersion()`/`useChangeVersions()` apenas quando você estiver sincronizando uma chamada `useQuery()` bruta fora desse caminho, como um auxiliar de cliente de nível mais baixo lendo o status de uma integração.
+
+## Como funcionam as versões de mudança {#how-it-works}
+
+Quando uma mutação de banco de dados do lado do servidor ocorre, o servidor registra um evento de mudança marcado com uma chave `source`. `useDbSync()` recebe esse evento e incrementa um contador local para essa origem. Incorporar o contador em uma chave do React Query faz a consulta buscar novamente automaticamente sempre que o backend reportar nova atividade para essa origem.
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description:
+        'A origem de evento de mudança a observar, ex. `"dashboards"`.',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description:
+      "Um contador que incrementa sempre que a origem informada sofre mutação.",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description:
+        "Múltiplas origens de evento de mudança a observar de uma vez.",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "A soma dos contadores de versão para cada origem informada.",
+  }}
+/>
+
+No exemplo abaixo, uma chamada `useQuery()` bruta lê um dashboard diretamente, incorporando o contador de versão da origem `"dashboards"` em sua chave de consulta para que ela busque novamente sempre que essa origem mudar:
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` mantém os dados anteriores na tela durante a nova busca, então a visualização não pisca para um estado de carregamento.
+
+## Dois caminhos para uma nova busca {#latency-models}
+
+Uma mutação chega à UI de uma de duas formas, e elas têm latências diferentes.
+
+Uma mutação local, uma que sua própria chamada `useActionMutation()` acabou de fazer, dispara um evento `source: "action"` no momento em que tem sucesso. Toda consulta que depende dessa action busca novamente imediatamente. Não há atraso de ida e volta, já que a aba que fez a gravação já sabe sobre ela.
+
+Uma mutação remota, do agente, um webhook, outra aba, ou outro usuário, precisa chegar a esta aba primeiro. `useDbSync()` a capta via SSE quase imediatamente, ou via o fallback de pesquisa em cerca de dois segundos se o SSE não estiver disponível. Somente quando esse evento chega é que o contador de versão relevante incrementa e a consulta busca novamente em segundo plano.
+
+<Diagram id="doc-block-client-sync-internals-3" title="Dois caminhos para uma nova busca" summary="Uma mutação local invalida seus próprios caches instantaneamente. Uma gravação remota chega a esta aba via SSE, ou o tick de pesquisa como fallback.">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">Esta aba</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >dispara source: "action" no sucesso &rarr; nova busca local
+        instantânea</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">Agente · webhook · outra aba</span
+      ><strong>Gravação remota</strong
+      ><small class="diagram-muted"
+        >push via SSE, ou o tick de pesquisa de ~2s como fallback &rarr;
+        contador de versão incrementa &rarr; nova busca em segundo plano</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## O que vem a seguir
+
+- [**Sincronização ao vivo**](/docs/key-concepts#polling-sync) — o modelo mental conceitual por baixo do qual esta página vai
+- [**Dados e sincronização**](/docs/client-data) — `useActionQuery`/`useDbSync`, que a maioria das páginas deve usar em vez dessas primitivas
+- [**Avançado**](/docs/client-advanced) — as outras primitivas de cliente de nível mais baixo e válvulas de escape
diff --git a/packages/core/docs/content/locales/pt-BR/client.mdx b/packages/core/docs/content/locales/pt-BR/client.mdx
deleted file mode 100644
index 588e955679..0000000000
--- a/packages/core/docs/content/locales/pt-BR/client.mdx
+++ /dev/null
@@ -1,472 +0,0 @@
----
-title: "Cliente"
-description: "Ganchos e utilitários React para aplicativos nativos do agente: sendToAgentChat, estado de contexto de bate-papo do agente opcional, useDbSync, useAgentChatGenerating e cn."
----
-
-# Cliente
-
-`@agent-native/core` fornece ganchos e utilitários React para o lado do navegador de aplicativos nativos do agente.
-
-Esses clientes/React APIs são exportados de `@agent-native/core` e `@agent-native/core/client`. Importe-os de `@agent-native/core/client` (a entrada do navegador) para maior clareza e agrupamento correto, já que a raiz `@agent-native/core` simples é resolvida para a compilação do Node por padrão.
-
-Para roteamento baseado em arquivo — adição de páginas, parâmetros dinâmicos e navegação — consulte [Routing](/docs/routing).
-
-## Busca e mutação de dados {#fetching-mutating}
-
-A principal maneira de ler e gravar dados de aplicativos no navegador é por meio de ganchos de ação. Nunca escreva manualmente chamadas `fetch` para rotas `/_agent-native/*`; em vez disso, use os auxiliares nomeados (consulte [Actions](/docs/actions)).
-
-<Diagram id="doc-block-1ojowdw" title="O loop de dados do navegador" summary={"Ganchos leem e escrevem por meio de ações; useDbSync observa o banco de dados para que as gravações do agente e em segundo plano busquem novamente os mesmos caches automaticamente."}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough>
-    <strong>banco de dados SQL</strong>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat(opções) {#sendtoagentchat}
-
-Envie uma mensagem para o chat do agente via postMessage — a maneira comum de delegar uma tarefa de IA de uma interação UI. Passe `context` para contexto de modelo oculto e `submit: true` para enviar imediatamente ou `submit: false` para preencher previamente um rascunho que o usuário analisará primeiro.
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-Dentro de um aplicativo MCP incorporado criado com `embedApp()`, mensagens enviadas automaticamente
-(`submit` omitido ou `true`) são encaminhados para a ponte de host do aplicativo MCP, que
-pede ao host que o contém para adicionar contexto oculto e enviar a vez do usuário visível.
-`context` permanece visível para o modelo sem ser postado como bate-papo voltado para o usuário.
-`submit: false` mantém o comportamento de pré-preenchimento/revisão local porque os aplicativos MCP não o fazem
-defina um rascunho pré-preenchido API padrão. Internamente, este é o caminho do chat enviado
-às vezes aparecia como `agentNative.submitChat`; o código do aplicativo deve chamar
-`sendToAgentChat()` em vez de postar esse evento diretamente.
-
-### Envios silenciosos em segundo plano {#background-send}
-
-Use `background: true` quando uma ação UI iniciar o trabalho real do agente sem
-abrindo ou focando a barra lateral. Isso ainda cria uma conversa/execução de bate-papo normal,
-usa as ferramentas/actions/contexto do agente e mantém o trabalho observável por meio
-a bandeja de corridas; não é uma chamada de modelo única e bruta.
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` deve ser emparelhado com `newTab` para que o trabalho oculto não ocorra
-substituir a conversa ativa do usuário. Use o `tabId` retornado se o UI
-precisa correlacionar o status de acompanhamento ou criar um link direto para a execução posteriormente.
-
-### AgentChatMessage {#agentchatmessage}
-
-| Opção                 | Tipo        | Descrição                                                               |
-| --------------------- | ----------- | ----------------------------------------------------------------------- |
-| `message`             | `string`    | O prompt visível enviado para o chat                                    |
-| `context`             | `string?`   | Contexto oculto anexado (não mostrado no chat UI)                       |
-| `submit`              | `boolean?`  | true = envio automático, false = somente preenchimento prévio           |
-| `newTab`              | `boolean?`  | Crie um tópico de bate-papo separado para este prompt                   |
-| `background`          | `boolean?`  | Com `newTab`, execute sem focar a aba e mostre a execução em `RunsTray` |
-| `openSidebar`         | `boolean?`  | Defina false para enviar/preencher sem abrir a barra lateral            |
-| `projectSlug`         | `string?`   | Slug de projeto opcional para contexto estruturado                      |
-| `preset`              | `string?`   | Nome predefinido opcional para consumidores downstream                  |
-| `referenceImagePaths` | `string[]?` | Caminhos de imagem de referência opcionais                              |
-
-## Estado do contexto do chat do agente (avançado) {#agent-chat-context-state}
-
-Os APIs de estado de contexto são encanamentos opcionais para UI que precisam de sincronização bidirecional com
-chips de contexto de teste: renderizando os itens de teste atuais fora do compositor,
-refletindo se um item já está anexado ou fornecendo informações explícitas
-remover/limpar controles.
-
-Não procure esses ajudantes para simplesmente "enviar isto para o agente" ou
-"preencher este rascunho para revisão". Use `sendToAgentChat()` com `context`
-e `submit` para esses.
-
-| API                               | Usar quando                                                                                 |
-| --------------------------------- | ------------------------------------------------------------------------------------------- |
-| `useAgentChatContext()`           | Um componente React precisa da lista de contexto preparada ao vivo                          |
-| `setAgentChatContextItem(item)`   | O código imperativo deve preparar ou substituir um item de contexto digitado                |
-| `listAgentChatContext()`          | O código não React precisa de um instantâneo único do contexto preparado                    |
-| `removeAgentChatContextItem(key)` | UI deve remover um item de contexto preparado por seu `key` estável                         |
-| `clearAgentChatContext()`         | UI deve limpar todo o contexto preparado, como após uma visualização ou redefinição de modo |
-| `refreshAgentChatContext()`       | O código imperativo deve reler o instantâneo de contexto persistido mais recente            |
-
-`useAgentChatContext()` retorna `{ items, set, remove, clear, refresh }`.
-
-## openAgentSettings(seção?) {#openagentsettings}
-
-Use `openAgentSettings()` quando uma página de configurações de aplicativo ou um cartão de configuração for aberto
-guia Configurações da barra lateral do agente. Passe um ID de seção como `"llm"`, `"secrets"`,
-`"automations"`, `"voice"` ou `"limits"` para abrir uma seção específica.
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-Prefira este auxiliar ao despachar `agent-panel:open-settings` diretamente.
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` é para código imperativo que só precisa inspecionar o
-itens atualmente preparados uma vez. `clearAgentChatContext()` é intencionalmente amplo; usar
-`removeAgentChatContextItem(key)` quando apenas uma seleção foi alterada.
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| Opção         | Tipo       | Descrição                                                                   |
-| ------------- | ---------- | --------------------------------------------------------------------------- |
-| `key`         | `string`   | Identificador estável usado para substituir um nugget existente             |
-| `title`       | `string`   | Etiqueta abreviada mostrada no chip do compositor                           |
-| `context`     | `string`   | Contexto oculto incluído no próximo prompt enviado                          |
-| `openSidebar` | `boolean?` | O padrão é verdadeiro; passe false para preparar o contexto silenciosamente |
-
-## askUserQuestion(opções) {#ask-user-question}
-
-Faça ao usuário uma pergunta de múltipla escolha no código do aplicativo e coloque-a em linha no
-painel do agente e **aguarde a resposta**. É o gêmeo do lado do cliente do
-ferramenta `ask-question` integrada do agente: ela grava um `GuidedQuestionPayload` no
-Chave de estado do aplicativo `"guided-questions"` (onde está montada
-`GuidedQuestionFlow` renderiza) e revela o painel do agente, então a pergunta é
-visível. Ao contrário da ferramenta do agente — cuja resposta retorna ao agente —
-`askUserQuestion()` **resolve com a resposta ao chamador**, então o UI pode
-ramifique-o.
-
-Use-o quando o UI precisar de exatamente uma pequena decisão (2–4 opções) antes dele
-inicia o trabalho do agente — em vez de criar um modal personalizado. Alcance o
-composer para detalhes de forma livre e um formulário/popover para entrada de vários campos.
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-Cada opção é `{ label, value?, description?, preview?, recommended? }`; `value`
-o padrão é `label` e `preview` renderiza um pequeno trecho de maquete/código sob o
-opção. A promessa é resolvida com o `value` selecionado (ou `value[]` quando
-`allowMultiple`), a string de texto livre quando o usuário escolhe "Outro" ou `null`
-se pularem — fica pendente até que o usuário responda. Requer o painel do agente
-para ser montado (está em todos os modelos).
-
-O agente chega ao mesmo UI através de sua ferramenta `ask-question`: prefira deixar o
-o agente pergunta quando _it_ atinge uma bifurcação genuína que não consegue resolver no contexto; usar
-`askUserQuestion()` quando _UI_ precisa definir uma ação em uma escolha.
-
-## Ponte de host do aplicativo MCP {#mcp-app-host-bridge}
-
-As rotas incorporadas como aplicativos MCP devem ser URL primeiro: carregue o artefato atual de
-parâmetros de caminho/consulta, renderize a rota React real ou um componente compartilhado focado,
-e use a ponte de host apenas para comportamento de propriedade do host. `@agent-native/core/client`
-exporta a chamada de rotas incorporadas dos auxiliares:
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()` lê o último instantâneo de contexto do host enviado;
-`useMcpAppHostContext()` subscreve componentes React para alterações. A solicitação
-ajudantes (`openMcpAppHostLink`, `requestMcpAppDisplayMode`,
-`updateMcpAppModelContext`) retorna `false` fora de um quadro de aplicativo MCP incorporado ou
-`Promise<boolean>` dentro de um quadro. `sendToAgentChat()` usa a mesma ponte para
-prompts enviados automaticamente a partir de rotas incorporadas.
-
-A ponte em si — as mensagens `ui/*` JSON-RPC, o `agentNative.mcpHost.*`
-retransmissão de wrapper, transplante versus renderização de quadro controlado, contexto de host e
-solicitações de modo de exibição — propriedade de
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## Sugestões dinâmicas {#dynamic-suggestions}
-
-`<AgentSidebar>`, `<AgentPanel>` e `<AssistantChat>` mesclam `suggestions` estático com sugestões baseadas no contexto por padrão. A estrutura lê `navigation`, `selection`, `pending-selection-context` e o URL atual do estado do aplicativo enquanto um bate-papo vazio está visível e, em seguida, oferece chips de prompt que correspondem à tela atual.
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-Defina `dynamicSuggestions={false}` para manter apenas chips estáticos. Passe `getSuggestions` quando um aplicativo deseja chips determinísticos específicos de domínio do mesmo contexto de estado do aplicativo.
-
-## useAgentChatGenerating() {#useagentchatgenerating}
-
-Gancho React que envolve sendToAgentChat com rastreamento de estado de carregamento:
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-`isGenerating` se torna verdadeiro quando você chama `send()` e é redefinido automaticamente para falso quando o agente termina de gerar.
-
-## useDbSync(opções?) {#usedbsync}
-
-Gancho React (anteriormente `useFileWatcher`) que escuta alterações no banco de dados em SSE, recorre à pesquisa e invalida os caches de consulta da estrutura que mantêm o UI alinhado com as gravações do agente:
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### Opções {#usedbsync-options}
-
-| Opção              | Tipo               | Descrição                                                                                                      |
-| ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | Cliente de consulta React para invalidação de cache                                                            |
-| `queryKeys`        | `string[]?`        | Obsoleto e ignorado; mantido para sites de chamada antigos                                                     |
-| `pollUrl`          | `string?`          | Polling endpoint URL. Padrão: `"/_agent-native/poll"`                                                          |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only                         |
-| `interval`         | `number?`          | Intervalo de pesquisa em ms. Padrão: `2000`                                                                    |
-| `fallbackInterval` | `number?`          | Intervalo de pesquisa de fallback quando SSE não está disponível. Padrão: `15000`                              |
-| `pauseWhenHidden`  | `boolean?`         | Pausar a pesquisa quando a guia do navegador estiver oculta. Padrão: `true`                                    |
-| `ignoreSource`     | `string?`          | Origem de solicitação por guia a ser ignorada para que uma guia não seja recuperada de suas próprias gravações |
-| `onEvent`          | `(data) => void`   | Retorno de chamada opcional quando SSE/polling recebe um evento de alteração                                   |
-
-Para CRUD normal, prefira `useActionQuery` e `useActionMutation`; actions mutante emite `source: "action"` e esses ganchos são buscados novamente automaticamente.
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-A estrutura usa versões alteradas para sincronizar caches de consulta React com alterações feitas por agentes em segundo plano, cron jobs ou outros usuários.
-
-Quando ocorre qualquer mutação no banco de dados do lado do servidor, o servidor registra um evento de alteração com uma chave `source` específica. O ouvinte `useDbSync` do cliente recebe esses eventos e aumenta o contador de versão de alteração local dessa origem. Ao incluir o contador de versões em suas chaves de consulta React, as consultas são buscadas automaticamente sempre que o back-end notifica o cliente sobre novas atividades.
-
-- **`useChangeVersion(source: string): number`** — retorna um contador que aumenta sempre que o `source` especificado sofre mutação.
-- **`useChangeVersions(sources: readonly string[]): number`** — retorna a soma dos contadores de versão para múltiplas fontes.
-
-### Exemplo: sincronizando uma consulta bruta com o banco de dados
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### Modelos de latência e comportamento de invalidação
-
-- **Mutações iniciadas por UI:** Quando você executa uma ação do UI usando `useActionMutation`, a mutação dispara imediatamente um evento local com `source: "action"` em caso de sucesso. Isso aciona uma **nova busca instantânea e otimista** de todas as chaves de consulta dependendo da ação, evitando atraso visual.
-- **Mutações em segundo plano ou de agente:** Quando o agente de IA, um webhook ou um trabalhador em segundo plano altera dados, a atualização é transmitida para o cliente. O `useDbSync` do cliente captura isso instantaneamente por meio de SSE (eventos enviados pelo servidor) ou recorre ao **tique de pesquisa de 2 segundos**. A versão da chave de consulta então falha, acionando uma nova busca em segundo plano.
-
-<Diagram id="doc-block-7z6lct" title="Dois caminhos para uma nova busca" summary={"Uma mutação local invalida instantaneamente seus próprios caches; uma gravação remota chega a esta guia por meio de SSE ou o tick de votação como substituto."}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">Esta aba</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">Agente · webhook · outra aba</span
-      ><strong>Escrita remota</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn(...entradas) {#cn}
-
-Utilitário para mesclar nomes de classes (clsx + tailwind-merge):
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/pt-BR/drop-in-agent.mdx b/packages/core/docs/content/locales/pt-BR/drop-in-agent.mdx
index 5a4297d379..349f8f02e4 100644
--- a/packages/core/docs/content/locales/pt-BR/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/pt-BR/drop-in-agent.mdx
@@ -225,7 +225,7 @@ rastreamento. Ele simplesmente não rouba o foco do estado atual da barra latera
 
 Quando a mesma rota é incorporada como um aplicativo MCP, enviado
 As chamadas `sendToAgentChat()` são encaminhadas para o chat do host quando houver suporte; veja
-[Client](/docs/client#sendtoagentchat) para o comportamento da ponte do aplicativo MCP.
+[Chat do Agent](/docs/client-agent-chat#sendtoagentchat) para o comportamento da ponte do aplicativo MCP.
 
 Se você deseja um estado de carregamento, use o gancho `useSendToAgentChat()` — ele retorna `send` e `isGenerating`:
 
diff --git a/packages/core/docs/content/locales/pt-BR/notifications.mdx b/packages/core/docs/content/locales/pt-BR/notifications.mdx
index 352be6cadb..f3c05750f8 100644
--- a/packages/core/docs/content/locales/pt-BR/notifications.mdx
+++ b/packages/core/docs/content/locales/pt-BR/notifications.mdx
@@ -363,7 +363,7 @@ As automações podem encadear isso - por exemplo. _"se uma notificação críti
 ## Como funciona {#internals}
 
 - **Escopo do proprietário** — cada linha tem uma coluna `owner`; cada consulta é filtrada; cada rota usa o email da sessão autenticada. Os usuários nunca veem as notificações uns dos outros.
-- **Integração de pesquisa** — cada mutação chama `recordChange()` para que os modelos que usam [`useDbSync`](/docs/client) sejam invalidados automaticamente sem qualquer conexão extra.
+- **Integração de pesquisa** — cada mutação chama `recordChange()` para que os modelos que usam [`useDbSync`](/docs/client-data#usedbsync) sejam invalidados automaticamente sem qualquer conexão extra.
 - **Distribuição de melhor esforço** — erros de canal são detectados e registrados; um canal com falha não bloqueia outros ou a gravação da caixa de entrada.
 - **Disparar e esquecer** — `notify()` retorna após a conclusão da gravação da caixa de entrada; canais personalizados são executados em segundo plano.
 
diff --git a/packages/core/docs/content/locales/pt-BR/progress.mdx b/packages/core/docs/content/locales/pt-BR/progress.mdx
index 04b77ec954..282f4f6da6 100644
--- a/packages/core/docs/content/locales/pt-BR/progress.mdx
+++ b/packages/core/docs/content/locales/pt-BR/progress.mdx
@@ -233,7 +233,7 @@ Notificar me that run {{runId}} has failed.
 ## Como funciona {#internals}
 
 - **Escopo do proprietário** — cada linha tem uma coluna `owner`; cada consulta é filtrada nela. Os usuários veem apenas suas próprias corridas.
-- **Integração de pesquisa** — cada mutação chama `recordChange()` para que os modelos que usam [`useDbSync`](/docs/client) sejam invalidados automaticamente sem qualquer conexão extra.
+- **Integração de pesquisa** — cada mutação chama `recordChange()` para que os modelos que usam [`useDbSync`](/docs/client-data#usedbsync) sejam invalidados automaticamente sem qualquer conexão extra.
 - **Nome da tabela** — a estrutura também possui uma tabela `agent_runs` para rastreamento interno do ciclo de vida do turno de bate-papo entre agentes. A primitiva de progresso usa `progress_runs` para manter os dois interesses separados.
 - **Ajuste percentual** — os valores são fixados em `[0, 100]` e arredondados para um número inteiro na gravação.
 
@@ -241,4 +241,4 @@ Notificar me that run {{runId}} has failed.
 
 - [**Notifications**](/docs/notifications) — emparelhe com `manage-progress` (`action=complete`) para informar ao usuário quando o trabalho terminar
 - [**Automations**](/docs/automations) — execuções lentas do watchdog via `run.progress.updated`
-- [**Client**](/docs/client) — `useDbSync` para invalidação de cache em tempo real
+- [**Dados e sincronização**](/docs/client-data) — `useDbSync` para invalidação de cache em tempo real
diff --git a/packages/core/docs/content/locales/pt-BR/real-time-collaboration.mdx b/packages/core/docs/content/locales/pt-BR/real-time-collaboration.mdx
index 9819907b12..ce533020a4 100644
--- a/packages/core/docs/content/locales/pt-BR/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/pt-BR/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ modelo de colaboração nativo do agente.
 Editar junto com o agente é como trabalhar em um editor colaborativo com
 um colega de trabalho instantâneo e incansável:
 
-Se você só precisa que UI seja atualizado quando o agente ou outro usuário grava em SQL, você não precisa de nada disso - use [`useDbSync`](/docs/client). Esta página é para coedição em nível de caractere de um único documento rich text (cursores compartilhados, mesclagem sem conflitos). Ambos utilizam o mesmo canal `/_agent-native/poll`.
+Se você só precisa que UI seja atualizado quando o agente ou outro usuário grava em SQL, você não precisa de nada disso - use [`useDbSync`](/docs/client-data#usedbsync). Esta página é para coedição em nível de caractere de um único documento rich text (cursores compartilhados, mesclagem sem conflitos). Ambos utilizam o mesmo canal `/_agent-native/poll`.
 
 Isso se baseia em três tecnologias testadas em batalha: **Yjs** (CRDT para fusão sem conflitos), **TipTap** (editor de rich text) e **sincronização baseada em polling** (funciona em todos os ambientes de implantação, inclusive sem servidor e de borda).
 
@@ -776,7 +776,7 @@ camadas acima do mesmo estado de reconhecimento.
 
 ## Documentos relacionados {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) — o `useDbSync` + `useChangeVersion`
+- [Sincronização interna](/docs/client-sync-internals) — o `useDbSync` + `useChangeVersion`
   sistema que fornece a reconciliação do editor de colisão `updatedAt`.
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   e `assertAccess` para colaboração com escopo de recurso.
diff --git a/packages/core/docs/content/locales/pt-BR/routing.mdx b/packages/core/docs/content/locales/pt-BR/routing.mdx
deleted file mode 100644
index ae0524131b..0000000000
--- a/packages/core/docs/content/locales/pt-BR/routing.mdx
+++ /dev/null
@@ -1,118 +0,0 @@
----
-title: "Roteamento"
-description: "Roteamento baseado em arquivo para aplicativos nativos de agente com React Router v8 — páginas, parâmetros dinâmicos e navegação."
----
-
-# Roteamento
-
-Os aplicativos nativos do agente usam o **React Router v8** com roteamento baseado em arquivo via `flatRoutes()` de `@react-router/fs-routes`. Cada arquivo em `app/routes/` se torna um URL. Os modelos usam a convenção de notação de ponto: os pontos separam os segmentos URL dentro de um único nome de arquivo.
-
-## Roteamento baseado em arquivo {#file-based-routing}
-
-### Arquivo → Mapeamento URL
-
-| Arquivo               | URL                | Notas                                        |
-| --------------------- | ------------------ | -------------------------------------------- |
-| `_index.tsx`          | `/`                | Rota de índice                               |
-| `settings.tsx`        | `/settings`        | Página simples                               |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | Ponto = `/`, `$` = parâmetro dinâmico        |
-| `_app.tsx`            | (sem segmento URL) | Layout sem caminho — prefixo com `_`         |
-| `inbox/route.tsx`     | `/inbox`           | Formulário de pasta — `route.tsx` é o índice |
-
-Prefixe um segmento com `$` para um parâmetro dinâmico. Prefixe com `_` para torná-la uma rota de layout sem caminho (sem segmento URL). Os modelos usam `flatRoutes()` — o arquivo de notação de ponto acima é o principal; o formato de pasta aninhada `inbox/route.tsx` também funciona.
-
-<Diagram id="doc-block-1kqvwtx" title={"Layout sem caminho envolve as páginas"} summary={"Um layout _app.tsx (sem segmento URL) renderiza o shell compartilhado uma vez; as páginas correspondentes são renderizadas dentro de seu <Outlet/>, para que a barra lateral do agente nunca seja remontada na navegação."}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >layout sem rota · shell persistente + barra do agente</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## Adicionando uma nova página {#adding-a-page}
-
-Crie o arquivo e exporte um componente padrão:
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-É isso aí - o roteador React coleta automaticamente, sem necessidade de registro.
-
-## Parâmetros dinâmicos {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## Navegação {#navigation}
-
-Use `<Link>` para navegação no lado do cliente e `useNavigate()` para navegação programática:
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## O que vem a seguir
-
-- [**Client**](/docs/client) — os ganchos e utilitários do navegador nativos do agente
-- [**Server**](/docs/server) — rotas de servidor baseadas em arquivo e o namespace `/_agent-native/`
diff --git a/packages/core/docs/content/locales/zh-CN/client-advanced.mdx b/packages/core/docs/content/locales/zh-CN/client-advanced.mdx
new file mode 100644
index 0000000000..d5898c1d8e
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-CN/client-advanced.mdx
@@ -0,0 +1,177 @@
+---
+title: "高级"
+description: "更底层的 app/ 原语与逃生舱：直接访问应用程序状态、后台聊天发送、自定义建议芯片，以及 MCP App 主桥。"
+---
+
+# 高级
+
+概览、数据与同步、Agent 聊天和路由这几页涵盖的是典型场景：大多数页面所需要的钩子和辅助函数。本页涵盖它们底层更细粒度的原语和更窄的逃生舱。大多数应用永远不需要直接接触这些。当您要构建比默认钩子所支持的更定制化的东西时——例如自定义选择同步或一个内嵌的 MCP App——才需要用到它们。若要用手写的 key 同步一个原始的 `useQuery`，请改看 [同步内部机制](/docs/client-sync-internals)。
+
+## 应用程序状态 {#application-state}
+
+`application_state` 是一个由 SQL 支持的键/值存储，代理通过读取它来了解 UI 当前正在看什么，包括导航、选择，以及其他被聚焦对象的上下文（见 [Context Awareness](/docs/context-awareness)）。`useAgentRouteState` 和 `useSemanticNavigationState`（同样在 Context Awareness 中介绍）已经为常见的导航场景包装了这些内容。当您要同步它们没有覆盖的内容——例如自定义选择，或从组件渲染之外进行写入——时，才直接使用下面这些原语。
+
+### readClientAppState {#read-client-app-state}
+
+读取某个 key 的当前值。解析为该 key 最后一次写入的内容，如果该 key 从未被写入过，则为 `null`。
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+为某个 key 写入一个值。与下面的 `setClientAppState` 不同，它总是会写入，即使您传入 `null` 也是如此。传入 `undefined` 则会抛出异常，因为 `undefined` 不是合法的 JSON。使用 `setClientAppState(key, undefined)` 或 `deleteClientAppState()` 来清除一个 key。
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+大多数 UI 代码应该使用的便捷封装：写入该值，或者当您传入 `null`/`undefined` 时删除该 key。除非某个调用点确实需要“始终写入，从不删除”，否则都应使用它而不是 `writeClientAppState`。
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+彻底移除一个 key。
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+在一次请求中读取多个 key。返回 `{ values, missing }`。`values` 为服务器上有记录的每个 key 保存一个条目，包括被显式写入为 `null` 的 key。`missing` 列出那些从未被写入过的 key。这样“从未写入”就能与“写入为 null”区分开来。
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+超过 100 个 key 的请求会自动被分块。`readClientAppState()` 本身就是构建在这个机制之上的：在同一个 tick 中发出的调用会在后台被合并成一个批量请求，因此在一次渲染过程中多次调用它，成本只是一次往返，而不是每次调用一次往返。
+
+### 选项 {#application-state-options}
+
+上面这五个函数都接受 `signal`，用于取消进行中的调用。`requestSource` 和 `keepalive` 只适用于三个写入函数，因为它们对读取没有意义。
+
+| 选项            | 类型           | 适用于                                                             | 描述                                                                                |
+| --------------- | -------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`、`setClientAppState`、`deleteClientAppState` | 用一个 id 标记该写入，使匹配的 `useDbSync({ ignoreSource })` 可以跳过对它的重新获取 |
+| `keepalive`     | `boolean?`     | `writeClientAppState`、`setClientAppState`、`deleteClientAppState` | 让请求能在页面卸载之后继续存活。用于清理性写入，例如清除选择                        |
+| `signal`        | `AbortSignal?` | 全部五个函数                                                       | 取消该请求                                                                          |
+
+### 失败行为 {#failure-behavior}
+
+这五个函数在请求失败、响应非 2xx，或响应体无法解析时都会抛出异常。当服务器有响应时，抛出的 `Error` 会带有一个 `.status` 属性，方便调用方在需要时基于 HTTP 状态分支处理。用 `try`/`catch` 包裹调用，或让它像任何其他网络调用一样传播到错误边界。
+
+### TAB_ID 是什么 {#tab-id}
+
+`requestSource` 通常会被设为 `TAB_ID`，这是每个模板都从 `app/lib/tab-id.ts` 导出的一个普通常量：一个在标签页生命周期内保持不变、且不同标签页之间互不相同的短随机字符串。在写入端配对 `requestSource: TAB_ID`，在读取端配对 `useDbSync({ ignoreSource: TAB_ID })`，正是一个标签页避免重新获取自己写入的内容、同时仍能响应其他所有人的方式。完整讲解见 [Context Awareness](/docs/context-awareness#jitter-prevention)。
+
+## sendToAgentChat：后台发送 {#background-send}
+
+当一个 UI 操作应该启动真正的代理工作、但不打开或聚焦侧边栏时，使用 `background: true`。这仍然会创建一个正常的聊天线程/运行，使用代理的工具/actions/上下文，并让这项工作可以通过运行托盘观察到。它不是一次原始的一次性模型调用。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` 设计上应与 `newTab` 配对使用，这样隐藏的工作就不会覆盖用户当前活跃的对话。如果 UI 后续需要关联状态或深链到该运行，请使用返回的 `tabId`。
+
+除了 [Agent 聊天](/docs/client-agent-chat#agentchatmessage) 中介绍的选项之外，`AgentChatMessage` 还有几个选项，主要用于嵌入式或下游集成场景：
+
+| 选项                  | 类型        | 描述                                                                      |
+| --------------------- | ----------- | ------------------------------------------------------------------------- |
+| `background`          | `boolean?`  | 配合 `newTab`，在不聚焦该标签页的情况下运行，并在 `RunsTray` 中显示该运行 |
+| `projectSlug`         | `string?`   | 用于结构化上下文的可选项目 slug                                           |
+| `preset`              | `string?`   | 供下游消费者使用的可选预设名称                                            |
+| `referenceImagePaths` | `string[]?` | 可选的参考图片路径                                                        |
+
+## MCP App 主桥 {#mcp-app-host-bridge}
+
+以 MCP App 形式嵌入的路由应该遵循 URL 优先原则：从路径/查询参数加载当前工件，渲染真正的 React 路由或一个聚焦的共享组件，并只在涉及主机自身行为时才使用主桥。`@agent-native/core/client` 导出了这些被嵌入路由调用的辅助函数：
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` 读取最近一次推送的主机上下文快照。`useMcpAppHostContext()` 让 React 组件订阅其变化。这些请求类辅助函数（`openMcpAppHostLink`、`requestMcpAppDisplayMode`、`updateMcpAppModelContext`）在嵌入式 MCP App frame 之外返回 `false`，在 frame 内部则返回 `Promise<boolean>`。
+
+`sendToAgentChat()`（见 [Agent 聊天](/docs/client-agent-chat#sendtoagentchat)）对来自嵌入式路由的自动提交提示，使用的是同一个主桥。在用 `embedApp()` 创建的 MCP App embed 内部，自动提交的消息（`submit` 省略或为 `true`）会被转发给主桥，由主桥要求容纳它的主机添加隐藏上下文并发送可见的用户回合。`context` 对模型保持可见，但不会作为面向用户的聊天内容发出。`submit: false` 保留本地的预填充/审阅行为，因为 MCP Apps 并没有定义标准的草稿预填充 API。在内部，这是有时会以 `agentNative.submitChat` 形式出现的已提交聊天路径。应用代码仍应调用 `sendToAgentChat()`，而不要直接发出该事件。
+
+主桥本身、`ui/*` JSON-RPC 消息、`agentNative.mcpHost.*` 包装器中继、移植与受控帧渲染、主机上下文，以及显示模式请求，均归 [External Agents](/docs/external-agents#mcp-app-bridge) 所有。完整协议见 [MCP Apps](/docs/mcp-apps)。
+
+## 自定义建议芯片 {#custom-suggestions}
+
+`<AgentSidebar>` 的 `dynamicSuggestions`（见 [Agent 聊天](/docs/client-agent-chat#dynamic-suggestions)）已经将静态 `suggestions` 与框架自身的上下文感知启发式规则合并在一起。当应用希望从同一份 `application_state` 上下文中计算出确定性的、领域专属的芯片，而不是使用框架的默认启发式规则时，改为传入 `getSuggestions`。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` 接收到的，与内置启发式规则读取的是同一份 `navigation`/`selection`/`pending-selection-context` 快照，因此自定义实现可以对与默认实现完全相同的状态做出反应，只是使用应用专属的规则，而不是通用规则。
+
+## 下一步
+
+- [**概览**](/docs/client-overview) — 这些原语所在的 `app/` 与 `public/` 目录布局
+- [**数据与同步**](/docs/client-data) — 大多数页面应改用的默认 action 钩子和 `useDbSync`
+- [**同步内部机制**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions`，以及重新获取可能经过的两条延迟路径
+- [**Agent 聊天**](/docs/client-agent-chat) — 大多数 UI 应改用的默认 `sendToAgentChat`/`askUserQuestion` 辅助函数，以及暂存的代理聊天上下文状态 API
+- [**入口点**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` 与 SSR 流式自定义
+- [**Context Awareness**](/docs/context-awareness) — 构建在 `application_state` 之上的 `navigation`/`selection` 语义，以及 `TAB_ID`/抖动预防讲解
+- [**Generative UI**](/docs/generative-ui) — 超越 `askUserQuestion` 的更丰富内联聊天控件
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — 完整的 MCP App 主桥内部机制
diff --git a/packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx b/packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx
new file mode 100644
index 0000000000..ae2fdb2b3c
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx
@@ -0,0 +1,310 @@
+---
+title: "Agent 聊天"
+description: "进入代理聊天的客户端入口：sendToAgentChat、openAgentSettings、askUserQuestion、动态建议、useAgentChatGenerating，以及暂存的代理聊天上下文状态。"
+---
+
+# Agent 聊天
+
+您应用的客户端可以通过一小组客户端辅助函数与代理对话。它们涵盖发送提示、暂存隐藏上下文、向用户提出阻塞式问题，以及打开代理面板。
+
+在下面的示例中，一个**起草回复**按钮会提示代理向用户提出一个问题。一旦用户回答，代理就会在起草回复时同时考虑当前页面上下文和用户的回答。
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="显示运行历史侧边栏的 Dispatch 应用截图"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Dispatch 的运行历史侧边栏。"
+/>
+
+## 工作原理
+
+通过使用 Agent-Native 提供的客户端辅助方法，您的 UI 可以提示代理以多种方式与用户互动。下面的图示展示了用户点击"起草回复"按钮后，代理如何在生成回复之前先与用户互动。
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="标题为“谁负责每一步”的序列图，展示了三条生命线：App Code、UI 和 Agent。用户点击“起草回复”，触发 askUserQuestion()。一条说明指出这会内联渲染在代理面板中。用户回复后，Agent 上的 sendDraftRequest() 被调用，它会调用 draft-ticket-reply 并将起草好的回复返回给 UI 的回复输入框。"
+  align="full"
+  width={600}
+  caption="将“起草回复”按钮流程可视化的序列图。"
+/>
+
+用户体验流程如下：
+
+1. 用户点击**起草回复**按钮，这会导致 `askUserQuestion()` 函数被调用。该问题会在代理面板中以内联方式得到回答。
+
+1. 用户选择**提供退款**，这会导致 `sendDraftRequest()` 将提示和工单上下文发送给代理。
+
+1. 代理调用 `draft-ticket-reply` [action](/docs/actions)，起草好的回复随即出现在回复输入框中。
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "问题本身、它的选项，以及它应有的行为方式。",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description: "完整的问题。清晰、具体，以问号结尾。",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description:
+            '非常简短的芯片/标题，大约 12 个字符，例如 `"Response"`。',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2-4 个不同的选项。每个选项都是 `{ label, value?, description?, preview?, recommended? }`。`value` 默认等于 `label`。",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description: "添加一个客服可以自由输入的“其他”文本选项。",
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "多选而非单选。",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description: "代理面板轮询的应用程序状态 key。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      "被选中的 `value`（若 `allowMultiple` 则为 `value[]`）、客服输入的“其他”文本，或者如果他们跳过则为 `null`。在他们回答之前会一直保持 pending。需要代理面板已挂载，而每个模板中它都已挂载。",
+  }}
+/>
+
+该函数从应用代码中向用户提出一个多选题，将其内联渲染在代理面板中，并等待用户的回答。当 UI 在启动代理工作之前需要用户做出一个只有两到四个选项的小决定时，用它代替构建一个自定义弹窗。
+
+在下面的示例中，工单页面上的一个“起草回复”按钮会先询问客服希望如何回复，然后才向代理发送任何内容：
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "一个 `[isGenerating, send]` 元组。`isGenerating` 从调用 `send()` 的那一刻起为 `true`，直到代理聊天运行报告已停止。`send(opts)` 与 `sendToAgentChat()` 的签名相同，并返回它派发到的 tab id。",
+  }}
+/>
+
+这个 React 钩子在 `sendToAgentChat()` 之上包装了加载状态跟踪。
+
+1. 第一个返回值 `isGenerating`，在您调用它时变为 true，代理完成生成后重置为 false。
+
+2. 第二个返回值 `send()`，与 `sendToAgentChat()` 函数一致。
+
+`isGenerating` 只有在一次运行真正开始并报告已停止之后才会重置。`submit: false` 的调用只会预填充一份草稿而不会启动运行，因此在这样的调用之后 `isGenerating` 会永远保持 `true`。该钩子只应用于 `submit: true` 的发送；仅需预填充时请直接调用 `sendToAgentChat()`。
+
+将其与上面的 `askUserQuestion()` 示例结合，就完成了这个按钮的处理函数：
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="补全起草回复处理函数"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "加载状态与发送，合而为一",
+      note: "`useAgentChatGenerating()` 返回与裸调用 `sendToAgentChat()` 相同形状的元组，但额外提供了 `isDrafting`，让按钮可以在请求进行中时自我禁用。",
+    },
+    {
+      lines: "10-17",
+      label: "复用提问步骤",
+      note: "这正是上一节中的 `askUserQuestion()` 调用，现在被放进了按钮自己的处理函数里。",
+    },
+    {
+      lines: "18",
+      label: "使用答案前先做类型收窄",
+      note: "返回类型始终允许 `allowMultiple` 带来的 `string[]`，因此即便这次调用从未设置它，这个检查也是必需的。",
+    },
+    {
+      lines: "20-25",
+      label: "把选择转换成一句话",
+      note: "将选中的值，或客服自己输入的文本，映射成下面提示中读起来自然的短语。",
+    },
+    {
+      lines: "27-32",
+      label: "指明 action 和意图",
+      note: "该消息明确告诉代理要调用哪个 action（`draft-ticket-reply`），并提醒它不要直接发出回复。`openSidebar: true` 确保即使侧边栏此前是关闭的，起草好的回复也是可见的。",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting 驱动按钮",
+      note: "只有在 `sendDraftRequest()` 进行中时按钮才会被禁用并更换文案。当 `askUserQuestion()` 在等待客服作答时，按钮仍可点击，因为那发生在 `sendDraftRequest()` 被调用之前。",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+通过 `postMessage` 向代理聊天发送一条消息。这是上面 `useAgentChatGenerating()` 所包装的更底层原语，适用于 UI 交互本身不需要加载状态跟踪的场景。传入 `context` 可以携带消息本身无法承载的额外细节，它会被追加到同一条可见消息中，并用 `<context>` 标签包裹——对用户并不隐藏。传入 `submit: true` 立即发送，或传入 `submit: false` 预填充一份草稿供用户先审阅。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| 选项          | 类型       | 描述                                                                   |
+| ------------- | ---------- | ---------------------------------------------------------------------- |
+| `message`     | `string`   | 发送到聊天中的提示。如果设置了 `context`，会被追加到这同一条可见消息中 |
+| `context`     | `string?`  | 追加到可见消息中的额外细节，用 `<context>` 标签包裹。对用户并不隐藏    |
+| `submit`      | `boolean?` | true = 自动提交，false = 仅预填充                                      |
+| `newTab`      | `boolean?` | 为此提示创建一个单独的聊天线程                                         |
+| `openSidebar` | `boolean?` | 设为 false 可在不打开侧边栏的情况下提交/预填充                         |
+
+在 MCP App embed 内部运行它，或者在不打开侧边栏的情况下将运行放到后台，这两种情况都在 [高级](/docs/client-advanced#background-send) 中有介绍。
+
+## 动态建议 {#dynamic-suggestions}
+
+在对话开始之前，`<AgentSidebar>`、`<AgentPanel>` 和 `<AssistantChat>` 会在空聊天上显示提示芯片。默认情况下，这些芯片不只是您固定的 `suggestions` 列表：框架会从应用程序状态中读取 `navigation`、`selection`、`pending-selection-context` 和当前 URL，并合并进与屏幕上实际内容相匹配的芯片。
+
+它通过两项检查来完成这件事。如果有内容被选中，它会添加通用芯片，例如“总结这个选择”。另外，它会在 `navigation` 中查找常见应用已经在用的字段名，例如邮件线程的 `threadId`/`emailId`，或图表的 `dashboardId`/`chartId`，并添加针对该类屏幕定制的芯片，例如线程的“起草回复”，或图表的“在这份数据中查找异常”。无论得到什么结果，都会与您的静态 `suggestions` 合并、去重，并被 `max` 限制上限。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+如果当前屏幕与启发式规则识别的任何内容都不匹配，且没有内容被选中，它就不会贡献任何芯片，空聊天会仅回退到您的静态 `suggestions`。设置 `dynamicSuggestions={false}` 可只保留静态芯片。如果您应用的导航结构与内置启发式规则不匹配，或者您想要完全确定性的、应用专属的芯片，见 [高级](/docs/client-advanced#custom-suggestions)。
+
+## openAgentSettings(section?) {#openagentsettings}
+
+当某个应用设置页面或设置卡需要打开代理侧边栏的设置选项卡时，使用 `openAgentSettings()`。传入一个区块 id，例如 `"llm"`、`"secrets"`、`"automations"`、`"voice"` 或 `"limits"`，可以打开特定的区块。
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+优先使用这个辅助函数，而不要直接派发 `agent-panel:open-settings`。
+
+## 代理聊天上下文状态 {#agent-chat-context-state}
+
+上下文状态 API 是为需要与暂存上下文芯片进行双向同步的 UI 提供的可选管道：在输入框之外渲染当前暂存的项目、反映某个项目是否已经被附加，或提供明确的移除/清除控件。
+
+对于简单的“把这个发给代理”或“预填充这份草稿供审阅”的流程，不要使用这些辅助函数，而应改用带有 `context` 和 `submit` 的 [`sendToAgentChat()`](#sendtoagentchat)。
+
+| API                               | 何时使用                                            |
+| --------------------------------- | --------------------------------------------------- |
+| `useAgentChatContext()`           | React 组件需要实时的暂存上下文列表                  |
+| `setAgentChatContextItem(item)`   | 命令式代码需要暂存或替换一个带 key 的上下文项       |
+| `listAgentChatContext()`          | 非 React 代码需要一次性获取暂存上下文的快照         |
+| `removeAgentChatContextItem(key)` | UI 需要通过稳定的 `key` 移除一个暂存的上下文项      |
+| `clearAgentChatContext()`         | UI 需要清除所有暂存上下文，例如在视图或模式重置之后 |
+| `refreshAgentChatContext()`       | 命令式代码需要重新读取最新的持久化上下文快照        |
+
+`useAgentChatContext()` 返回 `{ items, set, remove, clear, refresh }`。
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` 用于只需要检查一次当前暂存项目的命令式代码。`clearAgentChatContext()` 有意设计得比较宽泛；当只有一个选择发生变化时，使用 `removeAgentChatContextItem(key)`。
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| 选项          | 类型       | 描述                                       |
+| ------------- | ---------- | ------------------------------------------ |
+| `key`         | `string`   | 用于替换现有块的稳定标识符                 |
+| `title`       | `string`   | 显示在输入框芯片中的简短标签               |
+| `context`     | `string`   | 随下一次提交的提示一起包含的隐藏上下文     |
+| `openSidebar` | `boolean?` | 默认为 true。传入 false 可静默地暂存上下文 |
+
+## 下一步
+
+- [**概览**](/docs/client-overview) — 这些辅助函数在 `app/` 中的位置
+- [**数据与同步**](/docs/client-data) — 让 UI 本身保持最新的 action 钩子和 `useDbSync`
+- [**Drop-in Agent**](/docs/drop-in-agent) — 挂载 `<AgentSidebar>`/`<AgentPanel>`，让这些辅助函数有地方可以渲染
+- [**高级**](/docs/client-advanced) — 后台发送、自定义建议芯片，以及 MCP App 主桥
+- [**Generative UI**](/docs/generative-ui) — 构建超越 `askUserQuestion` 的更丰富的内联聊天控件
diff --git a/packages/core/docs/content/locales/zh-CN/client-data.mdx b/packages/core/docs/content/locales/zh-CN/client-data.mdx
new file mode 100644
index 0000000000..268ae07ee4
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-CN/client-data.mdx
@@ -0,0 +1,429 @@
+---
+title: "数据与同步"
+description: "app/ 用来读取、写入数据，并与代理调用的同一批 actions 保持实时同步的 action 钩子。"
+---
+
+# 数据与同步
+
+从客户端应用读取和写入应用数据的主要方式是通过 [action](/docs/actions) 钩子。通过将请求封装进 actions，您的客户端和代理都能以相同的方式与应用交互。
+
+在下面的示例中，一个工单先通过下拉菜单手动分配给当前用户，然后再通过聊天代理分配。UI 和代理访问的是同一个 action。
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="UI action 和 agent action 产生相同结果的示例。"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="UI action 和 agent action 产生相同结果的示例。"
+/>
+
+## 获取和修改数据 {#fetching-mutating}
+
+典型的应用会构建自己的 API 层，并用手写的 `fetch` 请求调用它。代理本机应用则跳过这一层：`app/` 通过下面这些钩子，调用代理已经拥有的同一批 actions 作为工具。
+
+<Diagram id="doc-block-client-data-fm-1" title="典型的 fetch 与 action 钩子对比" summary="典型组件调用一个只有它自己能访问的路由。代理本机组件调用的是一个代理也能调用的 action。">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">典型</div>
+    <div class="diagram-node">组件</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>您的 API 路由</strong>
+      <small class="diagram-muted">只有前端才能调用它</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>数据库</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">组件</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead action</span>
+      <small class="diagram-muted">同时也是一个 Agent 工具</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL 数据库</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Action 钩子 {#action-hooks}
+
+您最可能用到的两个 action 钩子是：`useActionQuery()` 和 `useActionMutation()`。这两个钩子提供对您应用中 actions 的访问。
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "该 action 注册时使用的名称。",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description: "该 action 的输入，类型来自其 `defineAction()` schema。",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "[useQuery 选项](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) 中除 `queryKey` 和 `queryFn`（由该钩子自行设置）之外的所有内容。",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      '缓存于 `["action", name, params]` 下。每当有变更类 action 完成时会自动重新获取，无需手动失效。',
+  }}
+/>
+
+该钩子用于只读 actions，是围绕 [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) 函数的一层轻量封装。
+
+在下面的示例中，调用了 `list-tickets` action，这类似于对所有工单发起一次 GET 请求。
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+下面的示例展示了通过 `get-ticket` action 获取单个工单的请求。提供 `ticketId` 用于将查询限定为只返回特定工单。额外提供的 `enabled` 选项确保该查询不会自动运行，而是只在存在 `ticketId` 时才运行。
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "该 action 注册时使用的名称。",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "[useMutation 选项](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) 中除 `mutationFn`（由该钩子自行设置）之外的所有内容。",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "覆盖默认的请求方法。",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "在成功时跳过自动缓存刷新。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      '成功后会发出一个 `source: "action"` 的变更事件，因此每个读取了受影响数据的 `useActionQuery()` 都会自动重新获取，无需手动失效。',
+  }}
+/>
+
+该钩子用于会改变数据的 actions，例如创建、更新或发送某些内容，是围绕 [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) 函数的一层轻量封装。
+
+与 `useActionQuery()` 不同，action 的输入不会传给钩子本身，而是在您准备运行该变更时传给 `mutate()` 或 `mutateAsync()`。
+
+在下面的示例中，调用 `send-ticket-reply` action 来为工单发布一条回复。从事件处理函数（例如按钮的 `onClick`）中调用 `mutate()`。
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+下面的示例展示了带有 `onSuccess` 选项的同一个变更。每次变更后缓存失效都会自动发生，所以 `onSuccess` 只在需要处理本地副作用时才用到，例如回复发送后清空回复输入框。
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "该 action 注册时使用的名称。",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description: "该 action 的输入，类型来自其 `defineAction()` schema。",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "下面的内容全部可选。",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "覆盖默认的请求方法。",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "取消该请求。",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "覆盖默认的 60 秒超时，用于那些确实需要更长时间的 actions。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "与上面的钩子不同，这里没有缓存也没有自动重新获取。如果其他 UI 依赖该结果，请配合手动失效一起使用。",
+  }}
+/>
+
+该函数用于 React 渲染流程之外的一次性命令式 action 调用，例如普通的事件处理函数、脚本，或任何其他非 React 代码路径。它直接返回一个 promise，而不是一个钩子结果。
+
+在下面的示例中，`update-ticket` action 在 React 渲染流程之外，从一个键盘快捷键处理函数中被调用，将工单分配给一名客服。
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+下面的示例展示了带有 `timeoutMs` 选项的同一个调用，适用于那些确实需要比默认 60 秒超时更长时间的 actions。
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+每个 `useActionQuery()`、`useActionMutation()` 和 `callAction()` 请求都受 60 秒超时限制，超时会以错误的形式呈现，而不会静默重试。`useActionQuery()` 还会使用 React Query 的 abort signal 自动取消被替代的请求。
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "每个字段都是可选的。",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "用于缓存失效的 React Query 客户端。",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "轮询端点 URL。",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description: "SSE 端点 URL。传入 `false` 则只使用轮询。",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "轮询间隔，单位毫秒。",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "SSE 已连接时的轮询间隔，作为遗漏事件时的备用手段。已断开连接的标签页则会以更快的 `interval`（或固定的空闲节奏）进行轮询。",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "当浏览器标签页隐藏时暂停轮询。隐藏的标签页会保持 SSE 连接，活动时轮询间隔不超过每 10 秒一次，进入空闲后为每 60 秒一次。",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "要忽略的每个标签页的请求来源，这样一个标签页就不会因为自己的写入而重新获取。",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description: "当 SSE 或轮询收到变更事件时的可选回调。",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "过滤 action 事件触发的大范围失效。很少需要用到。用它可以让某个开销较大的活动查询保持显式刷新语义，同时让普通的按来源版本化的查询依然通过 `useChangeVersion` 响应。",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "其同步事件不应使所有 action 查询失效的 action 名称列表。仅用于那些已经自行执行了精确失效的高频后台 actions。",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description: "已弃用并被忽略。为旧的调用点保留。",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+该钩子用于让 UI 与发生在您自己的 actions 之外的数据库变更保持同步，例如代理写入、webhook，或来自另一个浏览器标签页的变更。它通过 server-sent events 监听变更，在 server-sent events 不可用时回退到轮询。
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+对于普通的 CRUD，优先使用 `useActionQuery()` 和 `useActionMutation()`。变更类 actions 会发出 `source: "action"`，因此这些钩子会立即重新获取。来自代理、webhook 或另一个标签页的变更，则是通过 `useDbSync()`（经由 SSE 或轮询回退）到达的。如果某个原始 `useQuery()` 调用需要基于自定义 key 同步，见 [同步内部机制](/docs/client-sync-internals)。如果您需要直接写入 `application_state`，见 [高级](/docs/client-advanced)。
+
+## 下一步
+
+- [**概览**](/docs/client-overview) — 本页这些钩子所在的 `app/` 与 `public/` 目录布局
+- [**Agent 聊天**](/docs/client-agent-chat) — 向代理发送提示并暂存上下文
+- [**Actions**](/docs/actions) — 本页每个钩子背后的 `defineAction` 界面
+- [**高级**](/docs/client-advanced) — 直接访问 `application_state`
+- [**同步内部机制**](/docs/client-sync-internals) — 使用 `useChangeVersion` 同步原始 `useQuery`
+- [**实时同步**](/docs/key-concepts#polling-sync) — `useDbSync` 如何让 UI 保持最新
diff --git a/packages/core/docs/content/locales/zh-CN/client-entry-points.mdx b/packages/core/docs/content/locales/zh-CN/client-entry-points.mdx
new file mode 100644
index 0000000000..1f4a15d371
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-CN/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "入口点"
+description: "app/entry.client.tsx 和 app/entry.server.tsx：轻量的 hydration 与 SSR 引导包装器，以及何时需要自定义流式行为。"
+---
+
+# 入口点
+
+`app/entry.client.tsx` 在浏览器中对服务器渲染的 HTML 进行 hydrate，`app/entry.server.tsx` 则在服务器上渲染该 HTML。二者都是由 React Router 生成的轻量包装器，您很少需要修改它们。
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+只有在需要高级 SSR 自定义时才需要用到它们，例如更改流式行为。普通的页面、布局和数据都不需要修改这里的内容。添加页面请改看 [路由](/docs/client-routing)。
+
+## 下一步
+
+- [**概览**](/docs/client-overview) — 这些文件在 `app/` 中的位置
+- [**路由**](/docs/client-routing) — 添加页面，扩展 `app/` 的正常方式
+- [**高级**](/docs/client-advanced) — 其他更底层的客户端原语和逃生舱
diff --git a/packages/core/docs/content/locales/zh-CN/client-overview.mdx b/packages/core/docs/content/locales/zh-CN/client-overview.mdx
new file mode 100644
index 0000000000..7fcd01728a
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-CN/client-overview.mdx
@@ -0,0 +1,206 @@
+---
+title: "概览"
+description: "app/ 和 public/ 目录：您在其中构建代理本机应用程序显示界面的位置，以及它用于与代理保持同步的浏览器 API。"
+---
+
+# 概览
+
+`app/` 是您构建代理本机应用程序实际显示界面的位置：页面、布局、组件、样式。`public/` 保存与之一起提供的静态资源——图标、manifest、品牌标识。这是一个典型的 React Router v8 应用，不是特殊的仅供代理使用的界面，也是大部分开发时间投入的地方。
+
+与典型前端唯一的架构差异在于：这一层没有属于自己的 backend-for-frontend。它通过代理调用的同一批 actions 读写数据，因此在这里接入的任何功能，代理也自动能够执行。
+
+<Diagram id="doc-block-client-overview-1" title="传统前端 vs. Agent Native" summary="传统前端调用只有它自己能访问的 API 层。在 Agent Native 中，app/ 和代理都调用相同的 actions，因此在这里构建的每一项能力都可以免费供代理调用。">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">传统</div>
+    <div class="diagram-node">app/（React 前端）</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API 层</strong>
+      <small class="diagram-muted">只有前端才能调用它</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>数据库</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/（React 前端）</div>
+      <div class="diagram-node">Agent</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">平等的伙伴，相同的操作</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL 数据库</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## 客户端的定位 {#role}
+
+浏览器请求、代理循环和外部 API 客户端都会解析到相同的 actions 和相同的 SQL 数据库——这一层并没有一个代理无法访问的独立"应用后端"。在这里构建功能，意味着在代理已经拥有的操作之上构建 UI，或者定义一个新 action 并同时为它获得一个 UI。关于这份契约中操作那一侧的内容，请参阅 [Actions](/docs/actions)。
+
+本页涵盖您在其中构建的目录，以及没有其他文档介绍的浏览器运行时部分（`root.tsx`、`public/`）。将您的组件与 actions 和代理连接起来的 React 钩子则位于各自专门的页面上：
+
+| 页面                                            | 涵盖内容                                                                                          |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| **[数据与同步](/docs/client-data)**             | `useActionQuery`、`useActionMutation`、`callAction` 和 `useDbSync`                                |
+| **[Agent 聊天](/docs/client-agent-chat)**       | `sendToAgentChat`、`askUserQuestion`、`openAgentSettings`、动态建议，以及暂存的代理聊天上下文状态 |
+| **[高级](/docs/client-advanced)**               | 直接访问 `application_state`、后台聊天发送、自定义建议芯片，以及 MCP App 主桥                     |
+| **[同步内部机制](/docs/client-sync-internals)** | 用于同步原始 `useQuery` 的 `useChangeVersion`/`useChangeVersions`                                 |
+| **[入口点](/docs/client-entry-points)**         | `app/entry.client.tsx`/`app/entry.server.tsx` 和 SSR 自定义                                       |
+
+## app/ 和 public/ 中有什么 {#project-directories}
+
+| 路径                                                | 涵盖内容                                                                                              |
+| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | HTML 外壳与 provider 栈——见下方 [浏览器外壳](#app-shell)                                              |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration 与 SSR 引导——见 [入口点](/docs/client-entry-points)                                         |
+| **`app/routes.ts` + `app/routes/`**                 | 基于文件的页面与导航——见 [路由](/docs/client-routing)                                                 |
+| **`app/components/`**                               | 您的 UI：shadcn 风格的基础组件加上应用专属组件——见 [shadcn/ui](/docs/shadcn-ui)                       |
+| **`app/hooks/`**                                    | 数据、同步和代理聊天钩子——见 [数据与同步](/docs/client-data) 和 [Agent 聊天](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | 共享客户端工具（应用配置、tab id、`cn`）——见下方 [工具函数](#utilities)                               |
+| **`app/design-system.ts`**                          | 可选的自定义设计系统适配器——见 [自定义设计系统](/docs/custom-design-system)                           |
+| **`app/i18n/`**                                     | 本地化 UI 文案目录——见 [国际化](/docs/internationalization)                                           |
+| **`app/global.css`**                                | 基础样式与 Tailwind 入口                                                                              |
+| **`public/`**                                       | 原样提供的静态资源——见下方 [静态资源](#public-directory)                                              |
+
+## 浏览器外壳：root.tsx 和 AppProviders {#app-shell}
+
+`app/root.tsx` 是 React 树的顶端：HTML 文档外壳（`<html>`、`<head>`、`<Meta>`、`<Links>`、`<Scripts>`）加上每个路由都在其中渲染的 provider 栈。
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` 是接好以下所有内容的唯一包装器：
+
+- `useActionQuery`/`useActionMutation` 所使用的 React Query 客户端（见 [数据与同步](/docs/client-data#fetching-mutating)）。
+- 以 `i18n.catalog` 传入的 i18n 目录（见 [国际化](/docs/internationalization)）。
+- 客户端会话检查：在私有路径上，匿名访客会在任何私有 UI 挂载之前被重定向到登录页。为公共/SEO 路由传入 `isPublicPath`，或为以其他方式验证身份的界面（例如 MCP embed token）传入 `sessionBypass`。见 [身份验证](/docs/authentication)。
+
+大多数应用也会在这里挂载 `<AgentSidebar>` 或 `<AgentPanel>`，这样每个路由都能免费获得代理面板。见 [Drop-in Agent](/docs/drop-in-agent#sidebar)。
+
+## 静态资源：public/ {#public-directory}
+
+`public/` 中的所有内容都会在站点根目录原样提供，不经过构建处理。每个模板都自带：
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+`manifest.json` 控制访客将应用安装到主屏幕或程序坞时显示的内容——名称、短名称、主题/背景颜色，以及图标集：
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+要为应用重新设计品牌，替换这些文件并更新 `root.tsx` 中引用它们的 `manifest.json` 以及 `<link rel="icon">`/`<link rel="apple-touch-icon">` 标签——不需要单独的注册步骤。如果想从现有站点提取完整的品牌系统（颜色、字体、favicon）而不是手动编辑这些文件，见 [品牌系统与 Figma](/docs/template-design-brand-and-figma)。
+
+## 工具函数：cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` 合并类名（clsx + tailwind-merge），是在 `app/components/` 中组合条件性 Tailwind 类的标准方式。
+
+## 下一步
+
+- [**数据与同步**](/docs/client-data) — action 钩子和 `useDbSync`
+- [**Agent 聊天**](/docs/client-agent-chat) — `sendToAgentChat`、`askUserQuestion` 和动态建议
+- [**高级**](/docs/client-advanced) — 应用程序状态、后台聊天发送，以及 MCP App 主桥
+- [**同步内部机制**](/docs/client-sync-internals) — 用于同步原始 `useQuery` 的 `useChangeVersion`
+- [**入口点**](/docs/client-entry-points) — SSR 引导自定义
+- [**路由**](/docs/client-routing) — 基于文件的页面、动态参数与导航
+- [**Actions**](/docs/actions) — 每个数据钩子背后的 `defineAction` 界面
+- [**自定义设计系统**](/docs/custom-design-system) — 通过 `app/design-system.ts` 换入您自己的组件库
+- [**身份验证**](/docs/authentication) — `AppProviders` 在私有路径上运行的会话检查
diff --git a/packages/core/docs/content/locales/zh-CN/client-routing.mdx b/packages/core/docs/content/locales/zh-CN/client-routing.mdx
new file mode 100644
index 0000000000..b11a85a5ec
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-CN/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "路由"
+description: "基于 React Router v8 为代理本机应用提供的文件式路由：页面、动态参数与导航。"
+---
+
+# 路由
+
+代理本机应用使用 **React Router v8**，通过来自 `@react-router/fs-routes` 的 `flatRoutes()` 实现文件式路由。`app/routes/` 中的每个文件都会变成一个 URL。模板使用点号命名约定：点号在单个文件名内分隔 URL 段。
+
+本页涵盖客户端路由，即从 `app/routes/` 在浏览器中渲染的页面。服务器路由是一个独立的系统：`server/routes/` 下的 Nitro 文件路由，加上框架自己的 `/_agent-native/*` 端点，它们位于 [Routes](/docs/server-routes) 页面。这两者不共享目录、命名约定或路由器，因此 `server/routes/` 中的文件永远不会在这里变成页面，`app/routes/` 中的文件也永远不会变成服务器端点。
+
+<Diagram id="doc-block-client-routing-1" title="文件名 → URL" summary="app/routes/ 中的每个文件都会变成一个 URL。点号变成斜杠，$ 段变成动态参数。">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## 基于文件的路由 {#file-based-routing}
+
+### 文件 → URL 映射
+
+| 文件                       | URL                    | 说明                                                                 |
+| -------------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | 索引路由                                                             |
+| `dashboard.tsx`            | `/dashboard`           | 简单页面                                                             |
+| `extensions.$id.tsx`       | `/extensions/:id`      | 嵌套在 `extensions.tsx` 的 `<Outlet/>` 中。`$` 是动态参数            |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | 结尾的 `_` 跳过在 `dashboard.tsx` 下的嵌套，因此这是它自己的独立页面 |
+| `_app.tsx`                 | （无 URL 段）          | 无路径布局。以 `_` 作前缀                                            |
+| `inbox/route.tsx`          | `/inbox`               | 文件夹形式。`route.tsx` 即索引                                       |
+
+为某个段加上 `$` 前缀即可得到动态参数。加上 `_` 前缀可使其成为无路径布局路由（没有 URL 段），或者在点号前加上结尾的 `_`，可以让一个看起来是嵌套的路径退出在其父级布局下的嵌套。模板使用 `flatRoutes()`。上面的点号命名文件是主要形式，嵌套文件夹形式 `inbox/route.tsx` 同样可用。
+
+## 添加新页面 {#adding-a-page}
+
+创建文件并导出一个默认组件：
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+就是这样。React Router 会自动识别它，无需注册。
+
+## 动态参数 {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+点号前结尾的 `_` 使这个页面不会嵌套在 `dashboard.tsx` 的 `<Outlet/>` 中，因此它会作为自己完整的页面渲染在 `/dashboard/:ticketId`，而不是出现在工单队列的布局里面。
+
+## 导航 {#navigation}
+
+使用 `<Link>` 进行客户端导航，使用 `useNavigate()` 进行编程式导航：
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+这两者本身都不会告诉代理用户正在看什么。这是一个独立的问题，由 `useAgentRouteState()` 将当前路由写入应用程序状态来处理。见 [Context Awareness](/docs/context-awareness)。
+
+## 下一步
+
+- [**概览**](/docs/client-overview) — `app/routes/` 在 `app/` 和 `public/` 其余部分中的位置
+- [**数据与同步**](/docs/client-data) — 在路由内部读写数据
+- [**Agent 聊天**](/docs/client-agent-chat) — 从路由中发送提示并暂存上下文
+- [**Routes**](/docs/server-routes) — 独立的服务器路由系统：`server/routes/` 下的文件路由，以及框架的 `/_agent-native/` 命名空间
+- [**Context Awareness**](/docs/context-awareness) — 代理如何得知当前路由与选择
diff --git a/packages/core/docs/content/locales/zh-CN/client-sync-internals.mdx b/packages/core/docs/content/locales/zh-CN/client-sync-internals.mdx
new file mode 100644
index 0000000000..b669a0bd4c
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-CN/client-sync-internals.mdx
@@ -0,0 +1,123 @@
+---
+title: "同步内部机制"
+description: "useDbSync 背后的变更版本机制：用于同步原始 useQuery 的 useChangeVersion/useChangeVersions，以及重新获取可能经过的两条延迟路径。"
+---
+
+# 同步内部机制
+
+[实时同步](/docs/key-concepts#polling-sync) 介绍了心智模型：一次代理写入变成一个变更事件，`useDbSync()` 捕获它，受影响的查询随之重新获取。本页介绍这背后大多数应用都不会直接接触的机制：`useDbSync()` 递增的变更版本计数器，以及如何把它们折叠进一个不经过 `useActionQuery()` 的原始 `useQuery()` 调用中。
+
+`useActionQuery()` 在一个变更类 action 完成时已经会自动重新获取（见 [数据与同步](/docs/client-data#fetching-mutating)）。只有当您在这条路径之外同步一个原始的 `useQuery()` 调用时——例如读取集成状态的底层客户端辅助函数——才需要用到 `useChangeVersion()`/`useChangeVersions()`。
+
+## 变更版本的工作原理 {#how-it-works}
+
+当服务器端发生一次数据库变更时，服务器会记录一个带有 `source` key 标记的变更事件。`useDbSync()` 接收该事件，并递增该 source 对应的本地计数器。把这个计数器折叠进 React Query 的 key 中，就能让查询在后端报告该 source 有新活动时自动重新获取。
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description: '要监视的变更事件 source，例如 `"dashboards"`。',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "一个计数器，每当给定的 source 发生变更时就会递增。",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "要同时监视的多个变更事件 source。",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "所有给定 source 的版本计数器之和。",
+  }}
+/>
+
+在下面的示例中，一个原始的 `useQuery()` 调用直接读取一个 dashboard，并将 `"dashboards"` 这个 source 的版本计数器折叠进它的 query key，这样每当该 source 发生变化时它就会重新获取：
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` 在重新获取期间让屏幕上保留之前的数据，这样视图就不会闪烁进入加载状态。
+
+## 重新获取的两条路径 {#latency-models}
+
+一次变更会以两种方式之一到达 UI，二者的延迟不同。
+
+本地变更——即您自己的 `useActionMutation()` 调用刚刚发起的那次——一旦成功就会立即触发一个 `source: "action"` 事件。依赖该 action 的每个查询都会立即重新获取。这里没有往返延迟，因为发起写入的那个标签页已经知道这次写入了。
+
+远程变更——来自代理、webhook、另一个标签页，或另一个用户——则必须先到达这个标签页。`useDbSync()` 几乎会立即通过 SSE 捕获它，或者如果 SSE 不可用，则在大约两秒内通过轮询回退捕获它。只有当该事件到达之后，相关的版本计数器才会递增，查询才会在后台重新获取。
+
+<Diagram id="doc-block-client-sync-internals-3" title="重新获取的两条路径" summary="本地变更会立即使自己的缓存失效。远程写入通过 SSE 到达这个标签页，或作为回退经由轮询周期到达。">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">此标签页</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >成功时触发 source: "action" &rarr; 立即在本地重新获取</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">代理 · webhook · 其他标签页</span
+      ><strong>远程写入</strong
+      ><small class="diagram-muted"
+        >SSE 推送，或约 2 秒的轮询周期作为回退 &rarr; 版本递增 &rarr;
+        后台重新获取</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## 下一步
+
+- [**实时同步**](/docs/key-concepts#polling-sync) — 本页所深入探讨的概念心智模型
+- [**数据与同步**](/docs/client-data) — `useActionQuery`/`useDbSync`，大多数页面应使用它们而不是这些原语
+- [**高级**](/docs/client-advanced) — 其他更底层的客户端原语和逃生舱
diff --git a/packages/core/docs/content/locales/zh-CN/client.mdx b/packages/core/docs/content/locales/zh-CN/client.mdx
deleted file mode 100644
index 3d337f4fc2..0000000000
--- a/packages/core/docs/content/locales/zh-CN/client.mdx
+++ /dev/null
@@ -1,470 +0,0 @@
----
-title: "客户端"
-description: "用于代理本机应用程序的 React 挂钩和实用程序：sendToAgentChat、可选代理聊天上下文状态、useDbSync、useAgentChatGenerate 和 cn。"
----
-
-# 客户端
-
-`@agent-native/core` 为代理本机应用程序的浏览器端提供 React 挂钩和实用程序。
-
-这些客户端/React API 是从 `@agent-native/core` 和 `@agent-native/core/client` 导出的。为了清晰和正确的捆绑，从 `@agent-native/core/client`（浏览器条目）导入它们，因为默认情况下裸 `@agent-native/core` 根解析为 Node 构建。
-
-对于基于文件的路由 - 添加页面、动态参数和导航 - 请参阅 [Routing](/docs/routing)。
-
-## 获取和修改数据 {#fetching-mutating}
-
-从浏览器读取和写入应用程序数据的主要方式是通过操作挂钩。切勿手写 `fetch` 调用 `/_agent-native/*` 路由 - 请改用命名助手（请参阅 [Actions](/docs/actions)）。
-
-<Diagram id="doc-block-18d663e" title={"浏览器数据循环"} summary={"钩子通过动作进行读写； useDbSync 监视数据库，以便代理和后台写入自动重新获取相同的缓存。"}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>SQL 数据库</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat（选择） {#sendtoagentchat}
-
-通过 postMessage 向代理聊天发送消息——这是从 UI 交互中委派 AI 任务的常用方法。传递 `context` 来隐藏模型上下文，传递 `submit: true` 来立即发送，或者传递 `submit: false` 来预先填写用户首先审阅的草稿。
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-在使用 `embedApp()` 创建的 MCP 应用嵌入中，自动提交消息
-（`submit`省略或`true`）被转发到MCP应用程序主桥，这
-要求包含主机添加隐藏上下文并发送可见用户回合。
-`context` 保持模型可见，而不发布为面向用户的聊天。
-`submit: false` 保留本地预填充/审核行为，因为 MCP 应用不会
-定义标准草稿预填充 API。在内部，这是提交的聊天路径
-有时会以 `agentNative.submitChat` 的形式出现；应用代码应该调用
-`sendToAgentChat()` 而不是直接发布该事件。
-
-### 后台静默发送 {#background-send}
-
-当 UI 操作应该启动真正的代理工作时，请使用 `background: true`
-打开或聚焦侧边栏。这仍然会创建一个正常的聊天线程/运行，
-使用代理的工具/actions/context，并通过以下方式保持工作可观察
-运行托盘；它不是原始的一次性模型调用。
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` 旨在与 `newTab` 配对，因此隐藏的工作不会
-overwrite the user's active conversation. Use the returned `tabId` if the UI
-需要将后续状态或深层链接关联到稍后的运行。
-
-### 代理聊天消息 {#agentchatmessage}
-
-| 选项                  | 类型        | 描述                                                                |
-| --------------------- | ----------- | ------------------------------------------------------------------- |
-| `message`             | `string`    | 发送到聊天的可见提示                                                |
-| `context`             | `string?`   | 附加隐藏上下文（聊天UI中未显示）                                    |
-| `submit`              | `boolean?`  | true = 自动提交，false = 仅预填充                                   |
-| `newTab`              | `boolean?`  | 为此提示创建单独的聊天线程                                          |
-| `background`          | `boolean?`  | 使用 `newTab`，在不聚焦选项卡的情况下运行并在 `RunsTray` 中显示运行 |
-| `openSidebar`         | `boolean?`  | 设置 false 来提交/预填充而不打开侧边栏                              |
-| `projectSlug`         | `string?`   | 结构化上下文的可选项目段                                            |
-| `preset`              | `string?`   | 下游消费者的可选预设名称                                            |
-| `referenceImagePaths` | `string[]?` | 可选的参考图像路径                                                  |
-
-## 客服人员聊天上下文状态（高级） {#agent-chat-context-state}
-
-上下文状态 API 是 UI 的可选管道，需要双向同步
-暂存上下文芯片：在编辑器之外渲染当前暂存项目，
-反映某个项目是否已附加，或提供明确的
-删除/清除控件。
-
-不要为了简单的“将其发送给代理”而联系这些助手，或者
-“预填写此草稿以供审核”流程。将 `sendToAgentChat()` 与 `context` 结合使用
-还有 `submit`。
-
-| API                               | 何时使用                                        |
-| --------------------------------- | ----------------------------------------------- |
-| `useAgentChatContext()`           | React 组件需要实时暂存上下文列表                |
-| `setAgentChatContextItem(item)`   | 命令式代码应暂存或替换一个键控上下文项          |
-| `listAgentChatContext()`          | 非 React 代码需要暂存上下文的一次性快照         |
-| `removeAgentChatContextItem(key)` | UI 应通过其稳定的 `key` 删除一个暂存上下文项    |
-| `clearAgentChatContext()`         | UI 应清除所有暂存上下文，例如在视图或模式重置后 |
-| `refreshAgentChatContext()`       | 命令代码应该重新读取最新的持久上下文快照        |
-
-`useAgentChatContext()` 返回 `{ items, set, remove, clear, refresh }`。
-
-## openAgentSettings（部分？） {#openagentsettings}
-
-当应用设置页面或设置卡打开时使用 `openAgentSettings()`
-代理侧边栏的“设置”选项卡。传递一个部分id，例如`"llm"`，`"secrets"`，
-`"automations"`、`"voice"` 或 `"limits"` 打开特定部分。
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-更喜欢这个助手而不是直接调度 `agent-panel:open-settings`。
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` 用于仅需要检查的命令式代码
-当前暂存项目一次。 `clearAgentChatContext()` 故意宽泛；使用
-仅更改一项选择时为 `removeAgentChatContextItem(key)`。
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| 选项          | 类型       | 描述                                        |
-| ------------- | ---------- | ------------------------------------------- |
-| `key`         | `string`   | 用于替换现有块的稳定标识符                  |
-| `title`       | `string`   | 作曲家芯片中显示的短标签                    |
-| `context`     | `string`   | 下一个提交的提示中包含隐藏上下文            |
-| `openSidebar` | `boolean?` | 默认为true；静默地将 false 传递给舞台上下文 |
-
-## 询问用户问题（选择） {#ask-user-question}
-
-通过应用代码向用户提出多项选择问题，并将其内联呈现
-代理小组，并**等待他们的答复**。它是客户端的孪生
-代理的内置`ask-question`工具：它将`GuidedQuestionPayload`写入
-`"guided-questions"` 应用程序状态密钥（已安装的位置
-`GuidedQuestionFlow` 渲染它）并显示代理面板，所以问题是
-可见。与代理工具不同——其答案会返回给代理——
-`askUserQuestion()` **解析调用者的答案**，因此 UI 可以
-在上面分支。
-
-当 UI 之前需要做出一个小决定（2-4 个选项）时使用它
-开始代理工作——而不是构建自定义模式。到达
-用于自由形式细节的组合器，以及用于多字段输入的表单/弹出框。
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-每个选项都是`{ label, value?, description?, preview?, recommended? }`； `value`
-默认为`label`，`preview`在
-选项。承诺以选定的 `value`（或 `value[]` 时）解析
-`allowMultiple`)，用户选择“其他”时的自由文本字符串，或 `null`
-如果他们跳过——它将保持待定状态，直到用户回答。需要代理面板
-要安装（每个模板中都有）。
-
-代理通过其 `ask-question` 工具到达相同的 UI：更愿意让
-当 _it_ 遇到一个无法从上下文解析的真正分叉时，代理会询问；使用
-`askUserQuestion()`，当 _UI_ 需要对选择进行操作时。
-
-## MCP应用程序主桥 {#mcp-app-host-bridge}
-
-作为 MCP 应用嵌入的路由应该是 URL-first：加载当前工件
-路径/查询参数，渲染真实的React路由或聚焦的共享组件，
-并且仅将主机桥用于主机拥有的行为。 `@agent-native/core/client`
-导出助手嵌入的路由调用：
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()`读取最新推送的主机上下文快照；
-`useMcpAppHostContext()` 订阅 React 组件的更改。请求
-助手（`openMcpAppHostLink`、`requestMcpAppDisplayMode`，
-`updateMcpAppModelContext`) 在嵌入式 MCP 应用框架之外返回 `false`，或
-`Promise<boolean>` 在框架内。 `sendToAgentChat()` 使用相同的桥
-从嵌入式路由自动提交提示。
-
-桥本身 - `ui/*` JSON-RPC 消息、`agentNative.mcpHost.*`
-包装器中继、移植与受控帧渲染、主机上下文以及
-显示模式请求 — 属于
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## 动态建议 {#dynamic-suggestions}
-
-`<AgentSidebar>`、`<AgentPanel>` 和 `<AssistantChat>` 默认将静态 `suggestions` 与上下文感知建议合并。当可见空聊天时，框架从应用程序状态中读取 `navigation`、`selection`、`pending-selection-context` 和当前 URL，然后提供与当前屏幕匹配的提示芯片。
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-设置 `dynamicSuggestions={false}` 仅保留静态芯片。当应用程序需要来自同一应用程序状态上下文的确定性特定于域的芯片时，传递 `getSuggestions`。
-
-## useAgentChatGenerate() {#useagentchatgenerating}
-
-React 钩子，通过加载状态跟踪包装 sendToAgentChat：
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-当您调用 `send()` 时，`isGenerating` 变为 true，并在代理完成生成时自动重置为 false。
-
-## useDbSync（选项？） {#usedbsync}
-
-React 挂钩（以前称为 `useFileWatcher`），用于侦听 SSE 上的数据库更改，回退到轮询，并使保持 UI 与代理写入保持一致的框架查询缓存无效：
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### 选项 {#usedbsync-options}
-
-| 选项               | 类型               | 描述                                                                                   |
-| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | React-查询客户端缓存失效                                                               |
-| `queryKeys`        | `string[]?`        | 已弃用并被忽略；为旧的调用站点保留                                                     |
-| `pollUrl`          | `string?`          | 轮询端点 URL。默认值：`"/_agent-native/poll"`                                          |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
-| `interval`         | `number?`          | 轮询间隔（以毫秒为单位）。默认值：`2000`                                               |
-| `fallbackInterval` | `number?`          | SSE 不可用时的回退轮询间隔。默认值：`15000`                                            |
-| `pauseWhenHidden`  | `boolean?`         | 当浏览器选项卡隐藏时暂停轮询。默认值：`true`                                           |
-| `ignoreSource`     | `string?`          | 要忽略的每个选项卡请求源，以便选项卡不会从其自己的写入中重新获取                       |
-| `onEvent`          | `(data) => void`   | SSE/polling 收到更改事件时的可选回调                                                   |
-
-对于普通CRUD，优先选择`useActionQuery`和`useActionMutation`；变异 actions 会发出 `source: "action"` 并且这些钩子会自动重新获取。
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-框架使用更改版本将 React 查询缓存与后台代理、cron 作业或其他用户所做的更改同步。
-
-当任何服务器端数据库发生突变时，服务器都会使用特定的 `source` 密钥记录更改事件。客户端的 `useDbSync` 侦听器接收这些事件并增加该源的本地更改版本计数器。通过将版本计数器折叠到 React 查询键中，每当后端通知客户端新活动时，查询就会自动重新获取。
-
-- **`useChangeVersion(source: string): number`** — 返回一个计数器，每当指定的 `source` 发生突变时该计数器就会递增。
-- **`useChangeVersions(sources: readonly string[]): number`** — 返回多个源的版本计数器之和。
-
-### 示例：将原始查询与数据库同步
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### 延迟模型和失效行为
-
-- **UI-发起的突变：**当您使用 `useActionMutation` 从 UI 执行操作时，突变会在成功时立即触发 `source: "action"` 本地事件。这会根据该操作触发所有查询键的**即时、乐观的重新获取**，从而避免视觉延迟。
-- **后台或代理突变：** 当 AI 代理、Webhook 或后台工作人员突变数据时，更新会广播到客户端。客户端的 `useDbSync` 可以立即通过 SSE（服务器发送的事件）捕获此信息，也可以回退到 **2 秒轮询滴答**。然后查询密钥版本会发生变化，从而触发后台重新获取。
-
-<Diagram id="doc-block-1nhkvht" title={"重新获取的两条路径"} summary={"本地突变会立即使自己的缓存失效；远程写入通过 SSE 到达此选项卡，或作为后备的轮询标记。"}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">此标签页</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">代理 · webhook · 其他标签页</span
-      ><strong>远程写入</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn（...输入） {#cn}
-
-合并类名的实用程序（clsx + tailwind-merge）：
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/zh-CN/drop-in-agent.mdx b/packages/core/docs/content/locales/zh-CN/drop-in-agent.mdx
index fc6bfada04..d6152882d4 100644
--- a/packages/core/docs/content/locales/zh-CN/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/zh-CN/drop-in-agent.mdx
@@ -225,7 +225,7 @@ sendToAgentChat({
 
 当嵌入相同的路由作为MCP App时，提交
 `sendToAgentChat()` 呼叫将转发至支持的聊天主机；参见
-[Client](/docs/client#sendtoagentchat) 用于 MCP 应用桥接行为。
+[Agent 聊天](/docs/client-agent-chat#sendtoagentchat) 用于 MCP 应用桥接行为。
 
 如果您想要加载状态，请使用 `useSendToAgentChat()` 钩子 - 它返回 `send` 和 `isGenerating`：
 
diff --git a/packages/core/docs/content/locales/zh-CN/notifications.mdx b/packages/core/docs/content/locales/zh-CN/notifications.mdx
index 4635492e72..f99e000559 100644
--- a/packages/core/docs/content/locales/zh-CN/notifications.mdx
+++ b/packages/core/docs/content/locales/zh-CN/notifications.mdx
@@ -363,7 +363,7 @@ export function HeaderBar() {
 ## 它是如何工作的 {#internals}
 
 - **所有者范围** — 每行都有一个 `owner` 列；每个查询都会对其进行过滤；每个路由都使用经过身份验证的会话的电子邮件。用户永远不会看到彼此的通知。
-- **轮询集成** - 每个突变都会调用 `recordChange()`，因此使用 [`useDbSync`](/docs/client) 的模板会自动失效，无需任何额外的接线。
+- **轮询集成** - 每个突变都会调用 `recordChange()`，因此使用 [`useDbSync`](/docs/client-data#usedbsync) 的模板会自动失效，无需任何额外的接线。
 - **尽力扇出** — 捕获并记录通道错误；一个失败的通道不会阻止其他通道或收件箱写入。
 - **即发即忘** — `notify()` 在收件箱写入完成后返回；自定义通道在后台运行。
 
diff --git a/packages/core/docs/content/locales/zh-CN/progress.mdx b/packages/core/docs/content/locales/zh-CN/progress.mdx
index 3f65a7f976..883cf5e3f4 100644
--- a/packages/core/docs/content/locales/zh-CN/progress.mdx
+++ b/packages/core/docs/content/locales/zh-CN/progress.mdx
@@ -233,7 +233,7 @@ mode: agentic
 ## 它是如何工作的 {#internals}
 
 - **所有者范围** — 每行都有一个 `owner` 列；每个查询都会对其进行过滤。用户只能看到自己的跑步。
-- **轮询集成** - 每个突变都会调用 `recordChange()`，因此使用 [`useDbSync`](/docs/client) 的模板会自动失效，无需任何额外的接线。
+- **轮询集成** - 每个突变都会调用 `recordChange()`，因此使用 [`useDbSync`](/docs/client-data#usedbsync) 的模板会自动失效，无需任何额外的接线。
 - **表名称** — 该框架还有一个 `agent_runs` 表，用于内部代理聊天回合生命周期跟踪。进度原语使用 `progress_runs` 将两个关注点分开。
 - **百分比限制** — 值被限制为 `[0, 100]` 并在写入时四舍五入为整数。
 
@@ -241,4 +241,4 @@ mode: agentic
 
 - [**Notifications**](/docs/notifications) — 与 `manage-progress` (`action=complete`) 配对，告诉用户工作何时完成
 - [**Automations**](/docs/automations) — 看门狗通过 `run.progress.updated` 缓慢运行
-- [**Client**](/docs/client) — `useDbSync` 用于实时缓存失效
+- [**数据与同步**](/docs/client-data) — `useDbSync` 用于实时缓存失效
diff --git a/packages/core/docs/content/locales/zh-CN/real-time-collaboration.mdx b/packages/core/docs/content/locales/zh-CN/real-time-collaboration.mdx
index 4b53838ee1..778cdbf5c2 100644
--- a/packages/core/docs/content/locales/zh-CN/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/zh-CN/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ description: "多用户协作编辑，其中 AI 代理是一流的同行：CRDT
 与代理一起编辑感觉就像在协作编辑器中工作
 一位既快速又不知疲倦的同事：
 
-如果您只需要在代理或其他用户写入 SQL 时刷新 UI，则不需要任何这些 — 使用 [`useDbSync`](/docs/client)。此页面用于对单个富文本文档进行字符级共同编辑（共享光标、无冲突合并）。两者都使用相同的 `/_agent-native/poll` 通道。
+如果您只需要在代理或其他用户写入 SQL 时刷新 UI，则不需要任何这些 — 使用 [`useDbSync`](/docs/client-data#usedbsync)。此页面用于对单个富文本文档进行字符级共同编辑（共享光标、无冲突合并）。两者都使用相同的 `/_agent-native/poll` 通道。
 
 它建立在三项经过实战检验的技术之上：**Yjs**（CRDT，用于无冲突合并）、**TipTap**（富文本编辑器）和**基于轮询的同步**（适用于所有部署环境，包括无服务器和边缘）。
 
@@ -764,7 +764,7 @@ Use `emailToColor(email)` and `emailToName(email)` from
 
 ## 相关文档 {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) — `useDbSync` + `useChangeVersion`
+- [同步内部机制](/docs/client-sync-internals) — `useDbSync` + `useChangeVersion`
   提供 `updatedAt` 碰撞驱动编辑器协调的系统。
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   和 `assertAccess`，用于资源范围内的协作。
diff --git a/packages/core/docs/content/locales/zh-CN/routing.mdx b/packages/core/docs/content/locales/zh-CN/routing.mdx
deleted file mode 100644
index 4bfeb1d361..0000000000
--- a/packages/core/docs/content/locales/zh-CN/routing.mdx
+++ /dev/null
@@ -1,116 +0,0 @@
----
-title: "路由"
-description: "使用 React Router v8 为代理本机应用程序提供基于文件的路由 - 页面、动态参数和导航。"
----
-
-# 路由
-
-代理本机应用程序使用 **React Router v8** 以及通过来自 `@react-router/fs-routes` 的 `flatRoutes()` 的基于文件的路由。 `app/routes/` 中的每个文件都会变成 URL。模板使用点符号约定 - 点在单个文件名内分隔 URL 段。
-
-## 基于文件的路由 {#file-based-routing}
-
-### 文件→URL映射
-
-| 文件                  | URL                | 注释                          |
-| --------------------- | ------------------ | ----------------------------- |
-| `_index.tsx`          | `/`                | 索引路线                      |
-| `settings.tsx`        | `/settings`        | 简单页面                      |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | 点 = `/`，`$` = 动态参数      |
-| `_app.tsx`            | （无 URL 段）      | 无路径布局 - 前缀为 `_`       |
-| `inbox/route.tsx`     | `/inbox`           | 文件夹形式——`route.tsx`为索引 |
-
-为动态参数添加 `$` 前缀。以 `_` 为前缀，使其成为无路径布局路线（无 URL 段）。模板使用 `flatRoutes()` — 上面的点符号文件是主要的；嵌套文件夹形式 `inbox/route.tsx` 也适用。
-
-<Diagram id="doc-block-1t5h7ch" title={"无路径布局包裹页面"} summary={"_app.tsx 布局（无 URL 段）渲染共享 shell 一次；匹配的页面在其 <Outlet/> 内呈现，因此代理侧边栏永远不会在导航时重新安装。"}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted">无路径布局 · 持久外壳 + Agent 侧边栏</small>
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## 添加新页面 {#adding-a-page}
-
-创建文件并导出默认组件：
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-就是这样 - React 路由器会自动选择它，无需注册。
-
-## 动态参数 {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## 导航 {#navigation}
-
-使用 `<Link>` 进行客户端导航，使用 `useNavigate()` 进行编程导航：
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## 下一步是什么
-
-- [**Client**](/docs/client) - 代理本机浏览器挂钩和实用程序
-- [**Server**](/docs/server) — 基于文件的服务器路由和 `/_agent-native/` 命名空间
diff --git a/packages/core/docs/content/locales/zh-TW/client-advanced.mdx b/packages/core/docs/content/locales/zh-TW/client-advanced.mdx
new file mode 100644
index 0000000000..90ba05ff38
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-TW/client-advanced.mdx
@@ -0,0 +1,192 @@
+---
+title: "進階"
+description: "較低階的 app/ 原語與逃生口：直接存取應用程式狀態、背景聊天傳送、自訂建議標籤，以及 MCP App 主機橋接。"
+---
+
+# 進階
+
+總覽、資料與同步、Agent 聊天和路由涵蓋了典型情況：大多數頁面所需的掛鉤與輔助函式。此頁面涵蓋它們底下較低階的原語，以及範圍更窄的逃生口。大多數應用程式從不直接碰觸這些內容。當您要建置比預設掛鉤所支援的更為自訂的東西時，例如自訂選取同步或嵌入式 MCP App，才需要用到這些。若要以自訂鍵同步原始的 `useQuery`，請改參閱[同步內部機制](/docs/client-sync-internals)。
+
+## 應用程式狀態 {#application-state}
+
+`application_state` 是 SQL 支援的鍵/值儲存區，代理透過它得知 UI 目前正在看什麼，包括導覽、選取，以及其他聚焦物件的脈絡（請參閱[脈絡感知](/docs/context-awareness)）。`useAgentRouteState` 和 `useSemanticNavigationState`（同樣在脈絡感知中涵蓋）已經為常見的導覽情境包裝了這些內容。當您要同步它們未涵蓋的內容時，例如自訂選取，或是從元件渲染之外進行寫入，才直接使用下方的原語。
+
+### readClientAppState {#read-client-app-state}
+
+讀取某個鍵目前的值。解析為該鍵最後一次被寫入的內容，若該鍵從未被寫入過則為 `null`。
+
+```ts
+import { readClientAppState } from "@agent-native/core/client/hooks";
+
+const selection = await readClientAppState("selection");
+// selection is exactly what was last written to that key, e.g.:
+// { kind: "tickets.rows", ids: ["tik_182", "tik_209"] }
+//
+// or, if nothing has written "selection" yet:
+// null
+```
+
+### writeClientAppState {#write-client-app-state}
+
+寫入某個鍵的值。與下方的 `setClientAppState` 不同，它總是會寫入，即使您傳入 `null`。傳入 `undefined` 會擲出錯誤，因為 `undefined` 不是有效的 JSON。使用 `setClientAppState(key, undefined)` 或 `deleteClientAppState()` 來清除一個鍵。
+
+```ts
+import { writeClientAppState } from "@agent-native/core/client/hooks";
+
+await writeClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+```
+
+### setClientAppState {#set-client-app-state}
+
+大多數 UI 程式碼應該使用的便利包裝器：寫入該值，或在您傳入 `null`/`undefined` 時刪除該鍵。除非某個呼叫端確實需要「總是寫入、永不刪除」，否則請改用這個函式，而不是 `writeClientAppState`。
+
+```ts
+import { setClientAppState } from "@agent-native/core/client/hooks";
+
+await setClientAppState(
+  "selection",
+  { id: recordId },
+  { requestSource: TAB_ID },
+);
+await setClientAppState("selection", null); // clears the key, same as deleteClientAppState
+```
+
+### deleteClientAppState {#delete-client-app-state}
+
+完全移除一個鍵。
+
+```ts
+import { deleteClientAppState } from "@agent-native/core/client/hooks";
+
+await deleteClientAppState("pending-selection-context");
+```
+
+### readClientAppStateMany {#read-client-app-state-many}
+
+在一次請求中讀取多個鍵。回傳 `{ values, missing }`。`values` 為伺服器有資料列的每個鍵保存一個項目，包括明確寫入為 `null` 的鍵。`missing` 列出從未被寫入過的鍵。這就是「從未寫入」如何與「寫入為 null」保持可區分的方式。
+
+```ts
+import { readClientAppStateMany } from "@agent-native/core/client/hooks";
+
+const { values, missing } = await readClientAppStateMany([
+  "selection",
+  "pending-selection-context",
+]);
+```
+
+超過 100 個鍵的請求會自動分批處理。`readClientAppState()` 本身就是建立在這之上：在同一個 tick 中發出的呼叫會在幕後合併為一次批次請求，因此在單一渲染流程中多次呼叫它的成本是一次來回，而不是每次呼叫都要一次。
+
+### 選項 {#application-state-options}
+
+上方五個函式都接受 `signal`，用於取消進行中的呼叫。`requestSource` 和 `keepalive` 只適用於三個寫入函式，因為它們對讀取沒有意義。
+
+| 選項            | 型別           | 適用於                                                             | 描述                                                                              |
+| --------------- | -------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `requestSource` | `string?`      | `writeClientAppState`、`setClientAppState`、`deleteClientAppState` | 用一個 id 標記此次寫入，讓相符的 `useDbSync({ ignoreSource })` 可以跳過重新取得它 |
+| `keepalive`     | `boolean?`     | `writeClientAppState`、`setClientAppState`、`deleteClientAppState` | 讓請求在頁面卸載後仍能存活。用於清理性寫入，例如清除選取內容                      |
+| `signal`        | `AbortSignal?` | 全部五個函式                                                       | 取消請求                                                                          |
+
+### 失敗行為 {#failure-behavior}
+
+上方五個函式在請求失敗、非 2xx 回應，或無法解析的內文時都會擲出錯誤。擲出的 `Error` 在伺服器有回應時會帶有 `.status` 屬性，讓呼叫端可以根據 HTTP 狀態進行分支。將呼叫包裝在 `try`/`catch` 中，或讓它傳播到錯誤邊界，就像任何其他網路呼叫一樣。
+
+### TAB_ID 是什麼 {#tab-id}
+
+`requestSource` 通常設為 `TAB_ID`，這是每個範本都會從 `app/lib/tab-id.ts` 匯出的一個純常數：一個在分頁的生命週期內保持不變、且在不同分頁之間不同的短隨機字串。在寫入端配對 `requestSource: TAB_ID`，並在讀取端配對 `useDbSync({ ignoreSource: TAB_ID })`，就是分頁避免重新取得自己的寫入、同時仍對其他所有人的變化有反應的方式。完整走過此流程請參閱[脈絡感知](/docs/context-awareness#jitter-prevention)。
+
+## sendToAgentChat：背景傳送 {#background-send}
+
+當 UI 動作應該啟動真正的代理工作，卻不開啟或聚焦側邊欄時，使用
+`background: true`。這仍然會建立一個正常的聊天對話串/執行，
+使用代理的工具/actions/脈絡，並透過執行匣讓工作保持可觀察。
+它不是原始的一次性模型呼叫。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+
+const tabId = sendToAgentChat({
+  message: "Analyze this import and create any missing records",
+  context: `Import batch id: ${batchId}`,
+  submit: true,
+  newTab: true,
+  background: true,
+  openSidebar: false,
+});
+```
+
+`background` 旨在與 `newTab` 配對使用，讓隱藏的工作不會
+覆蓋使用者目前正在進行的對話。若 UI 需要關聯後續狀態，
+或稍後深層連結到該執行，請使用回傳的 `tabId`。
+
+除了在[Agent 聊天](/docs/client-agent-chat#agentchatmessage)中涵蓋的選項之外，還有一些其他的 `AgentChatMessage` 選項，主要用於嵌入式或下游整合的情境：
+
+| 選項                  | 型別        | 描述                                                                  |
+| --------------------- | ----------- | --------------------------------------------------------------------- |
+| `background`          | `boolean?`  | 搭配 `newTab`，在不聚焦分頁的情況下執行，並在 `RunsTray` 中顯示該執行 |
+| `projectSlug`         | `string?`   | 用於結構化脈絡的選用專案 slug                                         |
+| `preset`              | `string?`   | 供下游消費者使用的選用預設名稱                                        |
+| `referenceImagePaths` | `string[]?` | 選用的參考圖片路徑                                                    |
+
+## MCP App 主機橋接 {#mcp-app-host-bridge}
+
+以 MCP App 形式嵌入的路由應該是 URL-first 的：從
+路徑/查詢參數載入目前的成品，渲染真正的 React 路由或聚焦的共用元件，
+並僅在主機自有的行為上使用主機橋接。`@agent-native/core/client`
+匯出嵌入路由所呼叫的輔助函式：
+
+```ts
+import {
+  getMcpAppHostContext,
+  openMcpAppHostLink,
+  requestMcpAppDisplayMode,
+  updateMcpAppModelContext,
+  useMcpAppHostContext,
+} from "@agent-native/core/client/agent-chat";
+```
+
+`getMcpAppHostContext()` 讀取最新推送的主機脈絡快照。
+`useMcpAppHostContext()` 讓 React 元件訂閱變更。這些請求
+輔助函式（`openMcpAppHostLink`、`requestMcpAppDisplayMode`、
+`updateMcpAppModelContext`）在嵌入式 MCP App 框架之外回傳 `false`，或在框架內回傳
+`Promise<boolean>`。
+
+`sendToAgentChat()`（請參閱[Agent 聊天](/docs/client-agent-chat#sendtoagentchat)）為自動提交的提示使用相同的橋接，適用於嵌入式路由。在使用 `embedApp()` 建立的 MCP App 嵌入內，自動提交的訊息（`submit` 省略或為 `true`）會被轉發到橋接，此橋接會要求包含此內容的主機新增隱藏脈絡並傳送可見的使用者回合。`context` 對模型保持可見，而不會以面向使用者的聊天形式發布。`submit: false` 會保留本機的預填/審閱行為，因為 MCP App 沒有定義標準的草稿預填 API。內部而言，這是有時會以 `agentNative.submitChat` 形式呈現的已提交聊天路徑。應用程式碼應該仍呼叫 `sendToAgentChat()`，而不是直接發布該事件。
+
+橋接本身、`ui/*` JSON-RPC 訊息、`agentNative.mcpHost.*`
+包裝轉送、移植與受控框架渲染、主機脈絡，以及
+顯示模式請求，都歸屬於
+[External Agents](/docs/external-agents#mcp-app-bridge)。完整協議請參閱[MCP Apps](/docs/mcp-apps)。
+
+## 自訂建議標籤 {#custom-suggestions}
+
+`<AgentSidebar>` 的 `dynamicSuggestions`（請參閱[Agent 聊天](/docs/client-agent-chat#dynamic-suggestions)）已經將靜態 `suggestions` 與框架自身的脈絡感知啟發式方法合併。當應用程式想要根據相同的 `application_state` 脈絡計算出確定性、特定領域的標籤，而非使用框架的預設啟發式方法時，改傳入 `getSuggestions`。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  getSuggestions={(state) =>
+    state.navigation?.view === "inbox"
+      ? [`Summarize ${state.navigation.label ?? "this"} label`]
+      : []
+  }
+>
+  <App />
+</AgentSidebar>
+```
+
+`getSuggestions` 收到的 `navigation`/`selection`/`pending-selection-context` 快照，與內建啟發式方法讀取的完全相同，因此自訂實作可以對內建方法所讀取的相同狀態做出反應，只是使用應用專屬的規則，而非通用規則。
+
+## 下一步是什麼
+
+- [**總覽**](/docs/client-overview) — 這些原語所在的 `app/` 和 `public/` 目錄配置
+- [**資料與同步**](/docs/client-data) — 大多數頁面應改用的預設 action 掛鉤與 `useDbSync`
+- [**同步內部機制**](/docs/client-sync-internals) — `useChangeVersion`/`useChangeVersions`，以及重新取得可能經過的兩條延遲路徑
+- [**Agent 聊天**](/docs/client-agent-chat) — 大多數 UI 應改用的預設 `sendToAgentChat`/`askUserQuestion` 輔助函式，以及暫存的代理聊天脈絡狀態 API
+- [**入口點**](/docs/client-entry-points) — `app/entry.client.tsx`/`app/entry.server.tsx` 與 SSR 串流自訂
+- [**脈絡感知**](/docs/context-awareness) — 建立在 `application_state` 之上的 `navigation`/`selection` 語意，以及 `TAB_ID`/防抖動走查
+- [**Generative UI**](/docs/generative-ui) — 超越 `askUserQuestion` 的更豐富行內聊天控制項
+- [**External Agents**](/docs/external-agents#mcp-app-bridge) — 完整的 MCP App 主機橋接內部機制
diff --git a/packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx b/packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx
new file mode 100644
index 0000000000..6f9deda6f3
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx
@@ -0,0 +1,310 @@
+---
+title: "Agent 聊天"
+description: "進入代理聊天的用戶端進入點：sendToAgentChat、openAgentSettings、askUserQuestion、動態建議、useAgentChatGenerating，以及暫存的代理聊天脈絡狀態。"
+---
+
+# Agent 聊天
+
+您應用程式的用戶端可以透過一小組用戶端輔助函式與代理對話。這些涵蓋傳送提示、暫存隱藏脈絡、向使用者提出阻塞式問題，以及開啟代理面板。
+
+在下方的範例中，一個**草擬回覆**按鈕會提示代理向使用者提出問題。使用者回答後，代理會在記住目前頁面脈絡與使用者回覆的情況下開始草擬回覆。
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fcc3c9ccac6c6404f99fc27336b78a6d8?alt=media&token=d7aa0f72-eec3-4495-99c2-0d9bea11022e&apiKey=YJIGb4i01jvw0SRdL5Bt"
+  alt="Dispatch 應用程式截圖，顯示執行歷史側邊欄"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="Dispatch 的執行歷史側邊欄。"
+/>
+
+## 運作方式
+
+透過使用 Agent-Native 提供的用戶端輔助方法，您的 UI 可以提示代理以多種方式與使用者互動。下方的圖表展示了使用者點選「草擬回覆」按鈕後，如何提示代理在產生回覆之前與使用者互動。
+
+<Image
+  src="https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F59e297f868244e39ba5ad9c62a32281e?width=500&height=500"
+  alt="標題為「每個步驟由誰負責」的序列圖，顯示三條生命線：App Code、UI 和 Agent。使用者點選「草擬回覆」，觸發 askUserQuestion()。一則註記說明這會在代理面板中以行內方式呈現。使用者回覆後，會在 Agent 上呼叫 sendDraftRequest()，此函式呼叫 draft-ticket-reply 並將草擬的回覆回傳給 UI 的編輯器。"
+  align="full"
+  width={600}
+  caption="視覺化「草擬回覆」按鈕流程的序列圖。"
+/>
+
+使用者體驗如下：
+
+1. 使用者點選**草擬回覆**按鈕，觸發 `askUserQuestion()` 函式的呼叫。問題會在代理面板中以行內方式獲得回答。
+
+1. 使用者選取**提供退款**，觸發 `sendDraftRequest()` 將提示與工單脈絡傳送給代理。
+
+1. 代理呼叫 `draft-ticket-reply` [action](/docs/actions)，草擬的回覆會出現在回覆編輯器中。
+
+## askUserQuestion(opts) {#ask-user-question}
+
+<Signature
+  id="doc-block-client-agent-chat-3"
+  name="askUserQuestion"
+  params={[
+    {
+      name: "input",
+      type: "AskUserQuestionInput",
+      description: "問題、選項，以及它應如何運作。",
+      fields: [
+        {
+          name: "question",
+          type: "string",
+          description: "完整的問題。清楚、具體，以問號結尾。",
+        },
+        {
+          name: "header",
+          type: "string",
+          optional: true,
+          description: '極短的標籤/標題，約 12 個字元，例如 `"Response"`。',
+        },
+        {
+          name: "options",
+          type: "AskUserQuestionOption[]",
+          description:
+            "2 到 4 個不同的選項。每個選項為 `{ label, value?, description?, preview?, recommended? }`。`value` 預設為 `label`。",
+        },
+        {
+          name: "allowFreeText",
+          type: "boolean",
+          optional: true,
+          default: "true",
+          description: "新增一個自由文字的「其他」選項，供使用者輸入。",
+        },
+        {
+          name: "allowMultiple",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "多選而非單選。",
+        },
+        {
+          name: "stateKey",
+          type: "string",
+          optional: true,
+          default: '"guided-questions"',
+          description: "代理面板輪詢的應用程式狀態鍵。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<AskUserQuestionResult>",
+    description:
+      "所選的 `value`（或 `allowMultiple` 時的 `value[]`）、使用者輸入的「其他」文字，或若他們跳過則為 `null`。在他們回答之前保持待定狀態。需要代理面板已掛載，而每個範本中都已掛載。",
+  }}
+/>
+
+此函式從應用程式碼向使用者提出多選問題，將其以行內方式渲染在代理面板中，並等待他們的回答。當 UI 需要在啟動代理工作之前先做出一個包含兩到四個選項的小決定時使用它，而不是建置一個自訂彈出視窗。
+
+在下方的範例中，工單頁面上的「草擬回覆」按鈕會在向代理傳送任何內容之前，先詢問代表想如何回應：
+
+```ts
+import { askUserQuestion } from "@agent-native/core/client/agent-chat";
+
+const answer = await askUserQuestion({
+  question: "How would you like to respond to this ticket?",
+  header: "Response", // optional short chip/heading (≈12 chars)
+  options: [
+    { label: "Offer a refund", value: "refund" },
+    { label: "Offer a reprint", value: "reprint" },
+  ],
+});
+```
+
+## useAgentChatGenerating() {#useagentchatgenerating}
+
+<Signature
+  id="doc-block-client-agent-chat-4"
+  name="useAgentChatGenerating"
+  params={[]}
+  returns={{
+    type: "[boolean, (opts: AgentChatMessage) => string]",
+    description:
+      "一個 `[isGenerating, send]` 二元組。`isGenerating` 從呼叫 `send()` 的那一刻起為 `true`，直到代理聊天執行回報已停止為止。`send(opts)` 與 `sendToAgentChat()` 的簽章相同，並回傳它所派送到的分頁 id。",
+  }}
+/>
+
+此 React 掛鉤以載入狀態追蹤包裝 `sendToAgentChat()`。
+
+1. 第一個引數 `isGenerating`，在您呼叫它時變為 true，然後在代理完成生成後重設為 false。
+
+2. 第二個引數 `send()`，其行為與 `sendToAgentChat()` 函式相同。
+
+`isGenerating` 只有在一次執行實際開始並回報已停止後才會重設。`submit: false` 的呼叫只會預填一份草稿而不啟動執行，因此在這種呼叫之後 `isGenerating` 會永遠保持 `true`。只在 `submit: true` 的傳送上使用此掛鉤；針對僅預填的呼叫請直接呼叫 `sendToAgentChat()`。
+
+將此掛鉤與上方的 `askUserQuestion()` 範例結合，即可完成此按鈕的處理常式：
+
+<AnnotatedCode
+  id="doc-block-client-agent-chat-2"
+  title="完成草擬回覆處理常式"
+  language="tsx"
+  code={
+    'import {\n  askUserQuestion,\n  useAgentChatGenerating,\n} from "@agent-native/core/client/agent-chat";\n\nfunction useDraftResponseButton(ticket: { id: string; subject: string }) {\n  const [isDrafting, sendDraftRequest] = useAgentChatGenerating();\n\n  async function requestDraft() {\n    const answer = await askUserQuestion({\n      question: "How would you like to respond to this ticket?",\n      header: "Response",\n      options: [\n        { label: "Offer a refund", value: "refund" },\n        { label: "Offer a reprint", value: "reprint" },\n      ],\n    });\n    if (!answer || Array.isArray(answer)) return;\n\n    const intent =\n      answer === "refund"\n        ? "offering a refund"\n        : answer === "reprint"\n          ? "offering a reprint"\n          : `taking this direction from the rep: "${answer}"`;\n\n    sendDraftRequest({\n      message: `Draft a reply to this ticket ${intent}. Place it in the reply composer with draft-ticket-reply for ticket ${ticket.id}, don\'t send it.`,\n      context: `Ticket ${ticket.id}: "${ticket.subject}"`,\n      submit: true,\n      openSidebar: true,\n    });\n  }\n\n  return { isDrafting, requestDraft };\n}\n\nfunction DraftResponseButton({\n  ticket,\n}: {\n  ticket: { id: string; subject: string };\n}) {\n  const { isDrafting, requestDraft } = useDraftResponseButton(ticket);\n\n  return (\n    <button disabled={isDrafting} onClick={requestDraft}>\n      {isDrafting ? "Drafting..." : "Draft Response"}\n    </button>\n  );\n}'
+  }
+  annotations={[
+    {
+      lines: "7",
+      label: "載入狀態 + 傳送，合而為一",
+      note: "`useAgentChatGenerating()` 回傳與純粹呼叫 `sendToAgentChat()` 相同形狀的二元組，但加上了 `isDrafting`，讓按鈕在請求進行中時可以停用自己。",
+    },
+    {
+      lines: "10-17",
+      label: "重複使用詢問步驟",
+      note: "這正是上方章節中的 `askUserQuestion()` 呼叫，現在放在按鈕自己的處理常式中。",
+    },
+    {
+      lines: "18",
+      label: "在使用答案之前先做窄化",
+      note: "回傳型別總是允許 `allowMultiple` 帶來的 `string[]`，因此即使此呼叫從未設定它，這個檢查仍是必要的。",
+    },
+    {
+      lines: "20-25",
+      label: "把選擇變成一句話",
+      note: "將選定的值，或代表自己輸入的文字，映射成下方提示可以自然閱讀的措辭。",
+    },
+    {
+      lines: "27-32",
+      label: "點出 action 名稱與意圖",
+      note: "此訊息告訴代理確切要呼叫哪個 action（`draft-ticket-reply`），並提醒它不要直接把回覆傳送出去。`openSidebar: true` 確保即使側邊欄原本是關閉的，草擬的回覆仍能被看見。",
+    },
+    {
+      lines: "46-48",
+      label: "isDrafting 驅動按鈕",
+      note: "只在 `sendDraftRequest()` 進行中時才停用並重新標示。按鈕在 `askUserQuestion()` 等待代表回答時仍保持可點選，因為這發生在 `sendDraftRequest()` 被呼叫之前。",
+    },
+  ]}
+/>
+
+## sendToAgentChat(opts) {#sendtoagentchat}
+
+透過 `postMessage` 向代理聊天傳送一則訊息。這是 `useAgentChatGenerating()` 在上方包裝的較低階原語，適用於不需要自己的載入狀態追蹤的 UI 互動。傳入 `context` 以提供訊息本身未涵蓋的額外細節。它會被附加到同一則可見訊息上，並用 `<context>` 標籤包裹。它並不會對使用者隱藏。傳入 `submit: true` 立即傳送，或傳入 `submit: false` 預填一份草稿供使用者先審閱。
+
+```ts
+import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
+// Auto-submit a prompt with appended context
+sendToAgentChat({
+  message: "Generate alt text for this image",
+  context: "Image path: /api/projects/hero.jpg",
+  submit: true,
+});
+
+// Prefill without submitting (user reviews first)
+sendToAgentChat({
+  message: "Rewrite this in a conversational tone",
+  context: selectedText,
+  submit: false,
+});
+```
+
+### AgentChatMessage {#agentchatmessage}
+
+| 選項          | 型別       | 描述                                                                |
+| ------------- | ---------- | ------------------------------------------------------------------- |
+| `message`     | `string`   | 傳送到聊天的提示。若設定了 `context`，會附加到同一則可見訊息上      |
+| `context`     | `string?`  | 附加到可見訊息的額外細節，用 `<context>` 標籤包裹。不會對使用者隱藏 |
+| `submit`      | `boolean?` | true = 自動提交，false = 僅預填                                     |
+| `newTab`      | `boolean?` | 為此提示建立一個獨立的聊天對話串                                    |
+| `openSidebar` | `boolean?` | 設為 false 可在不開啟側邊欄的情況下提交/預填                        |
+
+從 MCP App 嵌入內部執行此操作，或在不開啟側邊欄的情況下將執行放到背景，這兩者都在[進階](/docs/client-advanced#background-send)中涵蓋。
+
+## 動態建議 {#dynamic-suggestions}
+
+在對話開始之前，`<AgentSidebar>`、`<AgentPanel>` 和 `<AssistantChat>` 會在空白聊天上顯示提示標籤。預設情況下，這些標籤不只是您固定的 `suggestions` 清單：框架會從應用程式狀態讀取 `navigation`、`selection`、`pending-selection-context` 與目前的 URL，並合併進符合畫面實際內容的標籤。
+
+它透過兩項檢查來完成這件事。若有內容被選取，它會加入通用標籤，例如「總結此選取範圍」。另外，它會查看 `navigation` 中現有應用程式已在使用的常見欄位名稱，例如電子郵件對話串的 `threadId`/`emailId`，或圖表的 `dashboardId`/`chartId`，並加入針對該類畫面的標籤，例如對話串的「草擬回覆」，或圖表的「在此資料中找出異常」。它產生的結果會與您的靜態 `suggestions` 合併、去除重複，並限制在 `max` 之內。
+
+```tsx
+<AgentSidebar
+  suggestions={["Summarize my inbox"]}
+  dynamicSuggestions={{ max: 4 }}
+>
+  <App />
+</AgentSidebar>
+```
+
+若目前畫面不符合此啟發式方法所認得的任何內容，且沒有任何內容被選取，它就不會提供任何標籤，空白聊天會回退為只顯示您的靜態 `suggestions`。設定 `dynamicSuggestions={false}` 可只保留靜態標籤。若您應用程式的導覽結構不符合內建的啟發式方法，或您想要完全確定性的應用專屬標籤，請參閱[進階](/docs/client-advanced#custom-suggestions)。
+
+## openAgentSettings(section?) {#openagentsettings}
+
+當應用程式設定頁面或設定卡應該開啟代理側邊欄的「設定」分頁時，使用 `openAgentSettings()`。傳入一個區段 id，例如 `"llm"`、`"secrets"`、
+`"automations"`、`"voice"` 或 `"limits"`，以開啟特定區段。
+
+```ts
+import { openAgentSettings } from "@agent-native/core/client/navigation";
+openAgentSettings();
+openAgentSettings("secrets");
+```
+
+優先使用此輔助函式，而不是直接派送 `agent-panel:open-settings`。
+
+## 代理聊天脈絡狀態 {#agent-chat-context-state}
+
+脈絡狀態 API 是選用的管道，適用於需要與暫存脈絡標籤雙向同步的 UI：在編輯器之外渲染目前暫存的項目、反映某個項目是否已附加，或提供明確的移除/清除控制項。
+
+對於單純的「將此傳送給代理」或「預填此草稿供審閱」流程，不要使用這些輔助函式。請針對這類情況使用搭配 `context` 和 `submit` 的 [`sendToAgentChat()`](#sendtoagentchat)。
+
+| API                               | 使用時機                                        |
+| --------------------------------- | ----------------------------------------------- |
+| `useAgentChatContext()`           | React 元件需要即時的暫存脈絡清單                |
+| `setAgentChatContextItem(item)`   | 指令式程式碼應暫存或替換一個具鍵的脈絡項目      |
+| `listAgentChatContext()`          | 非 React 程式碼需要暫存脈絡的一次性快照         |
+| `removeAgentChatContextItem(key)` | UI 應透過其穩定的 `key` 移除一個暫存脈絡項目    |
+| `clearAgentChatContext()`         | UI 應清除所有暫存脈絡，例如在檢視或模式重設之後 |
+| `refreshAgentChatContext()`       | 指令式程式碼應重新讀取最新的持久化脈絡快照      |
+
+`useAgentChatContext()` 回傳 `{ items, set, remove, clear, refresh }`。
+
+```tsx
+import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
+
+function SelectedTicketContextButton({ ticket }: { ticket: { id: string } }) {
+  const chatContext = useAgentChatContext();
+  const contextKey = `selected-ticket:${ticket.id}`;
+  const isAttached = chatContext.items.some((item) => item.key === contextKey);
+
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        if (isAttached) {
+          chatContext.remove(contextKey);
+          return;
+        }
+
+        chatContext.set({
+          key: contextKey,
+          title: "Selected Ticket",
+          context: JSON.stringify(ticket, null, 2),
+          openSidebar: false,
+        });
+      }}
+    >
+      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
+    </button>
+  );
+}
+```
+
+`listAgentChatContext()` 適用於只需要檢查一次目前暫存項目的指令式程式碼。`clearAgentChatContext()` 刻意設計得較為廣泛。當只有一項選取內容改變時，使用 `removeAgentChatContextItem(key)`。
+
+### AgentChatContextSetOptions {#agentchatcontextsetoptions}
+
+| 選項          | 型別       | 描述                                   |
+| ------------- | ---------- | -------------------------------------- |
+| `key`         | `string`   | 用於替換現有項目的穩定識別碼           |
+| `title`       | `string`   | 在編輯器標籤中顯示的短標籤             |
+| `context`     | `string`   | 隨下一則提交的提示一起附上的隱藏脈絡   |
+| `openSidebar` | `boolean?` | 預設為 true。傳入 false 可靜默暫存脈絡 |
+
+## 下一步是什麼
+
+- [**總覽**](/docs/client-overview) — 這些輔助函式在 `app/` 中的位置
+- [**資料與同步**](/docs/client-data) — 讓 UI 自身保持最新的 action 掛鉤與 `useDbSync`
+- [**臨時代理**](/docs/drop-in-agent) — 掛載 `<AgentSidebar>`/`<AgentPanel>`，讓這些輔助函式有地方可以渲染
+- [**進階**](/docs/client-advanced) — 背景傳送、自訂建議標籤，以及 MCP App 主機橋接
+- [**Generative UI**](/docs/generative-ui) — 在應用內聊天中建置超越 `askUserQuestion` 的更豐富行內控制項
diff --git a/packages/core/docs/content/locales/zh-TW/client-data.mdx b/packages/core/docs/content/locales/zh-TW/client-data.mdx
new file mode 100644
index 0000000000..7df7ab99c2
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-TW/client-data.mdx
@@ -0,0 +1,429 @@
+---
+title: "資料與同步"
+description: "app/ 用來讀取、寫入，並與代理所呼叫的相同 actions 保持即時同步的 action 掛鉤。"
+---
+
+# 資料與同步
+
+從用戶端應用程式讀取和寫入應用資料的主要方式是透過 [action](/docs/actions) 掛鉤。透過將請求嵌入到 actions 中，您的用戶端和代理都能以相同的方式與您的應用程式互動。
+
+在下方的範例中，一張工單先透過下拉選單手動指派給目前使用者，然後再透過聊天代理指派。UI 和代理存取的是同一個 action。
+
+<Video
+  src="https://cdn.builder.io/o/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fa5548a35d1494c1f8a4f960fbe8d9b2c%2Fcompressed?apiKey=YJIGb4i01jvw0SRdL5Bt&token=a5548a35d1494c1f8a4f960fbe8d9b2c&alt=media&optimized=true"
+  alt="UI action 與 agent action 產生相同結果的範例。"
+  align="full"
+  autoplay={true}
+  loop={true}
+  width={600}
+  caption="UI action 與 agent action 產生相同結果的範例。"
+/>
+
+## 取得與修改資料 {#fetching-mutating}
+
+典型的應用程式會建置自己的 API 層並透過手寫的 `fetch` 請求呼叫它。Agent-native 應用程式省去了那一層：`app/` 呼叫代理已經擁有的相同 actions，透過下方的掛鉤進行。
+
+<Diagram id="doc-block-client-data-fm-1" title="典型的 fetch vs. action 掛鉤" summary="典型元件呼叫一個只有自己能存取的路由。Agent-native 元件呼叫代理也能呼叫的 action。">
+
+```html
+<div class="diagram-fmcmp">
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">典型做法</div>
+    <div class="diagram-node">元件</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">fetch("/api/leads/:id")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>您的 API 路由</strong>
+      <small class="diagram-muted">只有前端能呼叫它</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>資料庫</div>
+  </div>
+  <div class="fmcmp-vs diagram-muted">vs</div>
+  <div class="fmcmp-col">
+    <div class="fmcmp-label diagram-muted">Agent Native</div>
+    <div class="diagram-node">元件</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-node">useActionQuery("get-lead")</div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">get-lead action</span>
+      <small class="diagram-muted">同時也是代理工具</small>
+    </div>
+    <div class="fmcmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL 資料庫</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-fmcmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.fmcmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 200px;
+}
+.fmcmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.fmcmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-fmcmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-items: center;
+}
+.fmcmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+### Action 掛鉤 {#action-hooks}
+
+最常用到的兩個 action 掛鉤是 `useActionQuery()` 和 `useActionMutation()`。這兩個掛鉤提供了存取您應用程式 actions 的方式。
+
+#### useActionQuery {#use-action-query}
+
+<Signature
+  id="doc-block-client-data-1"
+  name="useActionQuery"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "此 action 已註冊的名稱。",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description: "此 action 的輸入，型別來自其 `defineAction()` 架構。",
+    },
+    {
+      name: "options",
+      type: "UseQueryOptions",
+      optional: true,
+      description:
+        "來自 [useQuery options](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) 的所有內容，除了 `queryKey` 和 `queryFn`，這兩者由此掛鉤自行設定。",
+    },
+  ]}
+  returns={{
+    type: "UseQueryResult<TResult>",
+    description:
+      '快取於 `["action", name, params]` 之下。每當一個變異 action 完成時就會自動重新取得，不需要手動失效。',
+  }}
+/>
+
+此掛鉤旨在用於唯讀 actions。它是 [useQuery()](https://tanstack.com/query/latest/docs/framework/react/reference/useQuery) 函式的簡單包裝。
+
+在下方的範例中，呼叫了 `list-tickets` action。這類似於為所有工單發出一個 GET 請求。
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery("list-tickets", {});
+```
+
+以下範例展示透過 `get-ticket` action 取得單一工單的請求。傳入 `ticketId` 以將查詢範圍限定為只回傳特定工單。額外的 `enabled` 選項用於確保查詢不會自動執行，而只在 `ticketId` 存在時才執行。
+
+```ts
+import { useActionQuery } from "@agent-native/core/client/hooks";
+
+const { data, isLoading } = useActionQuery(
+  "get-ticket",
+  { ticketId: ticketId ?? "" },
+  { enabled: Boolean(ticketId) },
+);
+```
+
+#### useActionMutation {#use-action-mutation}
+
+<Signature
+  id="doc-block-client-data-2"
+  name="useActionMutation"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "此 action 已註冊的名稱。",
+    },
+    {
+      name: "options",
+      type: "UseMutationOptions",
+      optional: true,
+      description:
+        "來自 [useMutation options](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) 的所有內容，除了 `mutationFn`，此項由此掛鉤自行設定。",
+      fields: [
+        {
+          name: "method",
+          type: '"POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "覆蓋預設的請求方法。",
+        },
+        {
+          name: "skipActionQueryInvalidation",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description: "選擇退出成功後的自動快取重新整理。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "UseMutationResult",
+    description:
+      '成功後會發出 `source: "action"` 的變更事件，因此每個讀取受影響資料的 `useActionQuery()` 都會自動重新取得。不需要手動失效。',
+  }}
+/>
+
+此掛鉤旨在用於變更資料的 actions，例如建立、更新或傳送某項內容。它是 [useMutation()](https://tanstack.com/query/latest/docs/framework/react/reference/useMutation) 函式的簡單包裝。
+
+與 `useActionQuery()` 不同，此 action 的輸入不會傳給掛鉤本身，而是在您準備執行變異時傳給 `mutate()` 或 `mutateAsync()`。
+
+在下方的範例中，呼叫了 `send-ticket-reply` action 來對一則工單發布回覆。從事件處理常式（例如按鈕的 `onClick`）呼叫 `mutate()`。
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply");
+
+mutate({ ticketId, body: draft });
+```
+
+以下範例展示帶有 `onSuccess` 選項的相同變異。快取失效在每次變異後都會自動發生，因此 `onSuccess` 只在需要本機副作用時才需要，例如在回覆傳送後清空回覆編輯器。
+
+```ts
+import { useActionMutation } from "@agent-native/core/client/hooks";
+
+const { mutate, isPending } = useActionMutation("send-ticket-reply", {
+  onSuccess: () => setDraft(""),
+});
+
+mutate({ ticketId, body: draft });
+```
+
+### callAction {#call-action}
+
+<Signature
+  id="doc-block-client-data-3"
+  name="callAction"
+  params={[
+    {
+      name: "actionName",
+      type: "TName",
+      description: "此 action 已註冊的名稱。",
+    },
+    {
+      name: "params",
+      type: "ActionParams<TName>",
+      optional: true,
+      description: "此 action 的輸入，型別來自其 `defineAction()` 架構。",
+    },
+    {
+      name: "options",
+      type: "ClientActionCallOptions",
+      optional: true,
+      description: "以下所有項目都是選用的。",
+      fields: [
+        {
+          name: "method",
+          type: '"GET" | "POST" | "PUT" | "DELETE"',
+          optional: true,
+          default: '"POST"',
+          description: "覆蓋預設的請求方法。",
+        },
+        {
+          name: "signal",
+          type: "AbortSignal",
+          optional: true,
+          description: "取消請求。",
+        },
+        {
+          name: "timeoutMs",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "覆蓋預設的 60 秒逾時，適用於合理需要更長時間的 actions。",
+        },
+      ],
+    },
+  ]}
+  returns={{
+    type: "Promise<TResult>",
+    description:
+      "與上方的掛鉤不同，這裡沒有快取也沒有自動重新取得。若其他 UI 依賴此結果，請搭配手動失效。",
+  }}
+/>
+
+此函式用於 React 渲染流程之外的指令式一次性 action 呼叫，例如純粹的事件處理常式、腳本，或任何其他非 React 程式碼路徑。它直接回傳一個 promise，而不是掛鉤結果。
+
+在下方的範例中，`update-ticket` action 從一個鍵盤快速鍵處理常式中被呼叫，該處理常式位於 React 的渲染流程之外，將工單指派給一位代表。
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction("update-ticket", {
+  ticketId,
+  assignedToEmail: "jordan@example.com",
+});
+```
+
+以下範例展示帶有 `timeoutMs` 選項的相同呼叫，適用於合理需要超過預設 60 秒逾時的 actions。
+
+```ts
+import { callAction } from "@agent-native/core/client/hooks";
+
+await callAction(
+  "update-ticket",
+  { ticketId, assignedToEmail: "jordan@example.com" },
+  { timeoutMs: 120_000 },
+);
+```
+
+每個 `useActionQuery()`、`useActionMutation()` 和 `callAction()` 請求都受限於 60 秒逾時，逾時會以錯誤形式呈現，而不會靜默重試。`useActionQuery()` 也會使用 React Query 的中止信號自動取消被取代的請求。
+
+## useDbSync {#usedbsync}
+
+<Signature
+  id="doc-block-client-data-4"
+  name="useDbSync"
+  params={[
+    {
+      name: "options",
+      type: "UseDbSyncOptions",
+      description: "每個欄位都是選用的。",
+      fields: [
+        {
+          name: "queryClient",
+          type: "QueryClient",
+          optional: true,
+          description: "用於快取失效的 React Query 用戶端。",
+        },
+        {
+          name: "pollUrl",
+          type: "string",
+          optional: true,
+          default: '"/_agent-native/poll"',
+          description: "輪詢端點 URL。",
+        },
+        {
+          name: "sseUrl",
+          type: "string | false",
+          optional: true,
+          default: '"/_agent-native/events"',
+          description: "SSE 端點 URL。傳入 `false` 可只使用輪詢。",
+        },
+        {
+          name: "interval",
+          type: "number",
+          optional: true,
+          default: "2000",
+          description: "輪詢間隔（毫秒）。",
+        },
+        {
+          name: "fallbackInterval",
+          type: "number",
+          optional: true,
+          default: "60000",
+          description:
+            "SSE 已連線時的輪詢間隔，作為漏接事件時的備援。已斷線的分頁會以較快的 `interval`（或固定的閒置節奏）輪詢。",
+        },
+        {
+          name: "pauseWhenHidden",
+          type: "boolean",
+          optional: true,
+          default: "false",
+          description:
+            "當瀏覽器分頁隱藏時暫停輪詢。隱藏的分頁會保持 SSE 連線，並在活動時最多每 10 秒輪詢一次，閒置後每 60 秒一次。",
+        },
+        {
+          name: "ignoreSource",
+          type: "string",
+          optional: true,
+          description:
+            "要忽略的每個分頁請求來源，以便分頁不會因自己的寫入而重新取得。",
+        },
+        {
+          name: "onEvent",
+          type: "(data) => void",
+          optional: true,
+          description: "當 SSE 或輪詢收到變更事件時的選用回呼。",
+        },
+        {
+          name: "actionInvalidatePredicate",
+          type: "(query: Query) => boolean",
+          optional: true,
+          description:
+            "篩選一個 action 事件觸發的廣泛失效範圍。極少需要用到。用它讓某個昂貴的活動查詢維持明確重新整理的語意，而一般的來源版本化查詢仍透過 `useChangeVersion` 反應。",
+        },
+        {
+          name: "suppressActionInvalidationFor",
+          type: "string[]",
+          optional: true,
+          description:
+            "其同步事件不應使所有 action 查詢失效的 action 名稱。僅適用於已自行執行窄範圍失效的高流量背景 actions。",
+        },
+        {
+          name: "queryKeys",
+          type: "string[]",
+          optional: true,
+          description: "已淘汰並被忽略。為舊的呼叫端保留。",
+        },
+      ],
+    },
+  ]}
+  returns={{ type: "void" }}
+/>
+
+此掛鉤旨在讓 UI 與發生在您自己的 actions 之外的資料庫變更保持同步，例如代理的寫入、webhook，或來自另一個瀏覽器分頁的變更。它透過伺服器傳送事件監聽變更，並在伺服器傳送事件不可用時回退為輪詢。
+
+```ts
+import { useDbSync } from "@agent-native/core/client/hooks";
+import { useQueryClient } from "@tanstack/react-query";
+
+function App() {
+  const queryClient = useQueryClient();
+
+  useDbSync({
+    queryClient,
+    pollUrl: "/_agent-native/poll",
+    onEvent: (data) => console.log("Data changed:", data),
+  });
+
+  return <div>...</div>;
+}
+```
+
+對於一般的 CRUD，優先使用 `useActionQuery()` 和 `useActionMutation()`。變異 actions 會發出 `source: "action"`，因此這些掛鉤會立即重新取得。來自代理、webhook 或另一個分頁的變更則透過 `useDbSync()` 到來，經由 SSE 或輪詢備援。若原始的 `useQuery()` 呼叫需要以自訂鍵同步，請參閱[同步內部機制](/docs/client-sync-internals)。若您需要直接寫入 `application_state`，請參閱[進階](/docs/client-advanced)。
+
+## 下一步是什麼
+
+- [**總覽**](/docs/client-overview) — 此頁面掛鉤所在的 `app/` 和 `public/` 目錄配置
+- [**Agent 聊天**](/docs/client-agent-chat) — 傳送提示與為代理暫存脈絡
+- [**Actions**](/docs/actions) — 本頁每個掛鉤背後的 `defineAction` 介面
+- [**進階**](/docs/client-advanced) — 直接存取 `application_state`
+- [**同步內部機制**](/docs/client-sync-internals) — 用 `useChangeVersion` 同步原始 `useQuery`
+- [**即時同步**](/docs/key-concepts#polling-sync) — `useDbSync` 如何讓 UI 保持最新
diff --git a/packages/core/docs/content/locales/zh-TW/client-entry-points.mdx b/packages/core/docs/content/locales/zh-TW/client-entry-points.mdx
new file mode 100644
index 0000000000..fe56ece440
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-TW/client-entry-points.mdx
@@ -0,0 +1,27 @@
+---
+title: "入口點"
+description: "app/entry.client.tsx 與 app/entry.server.tsx：簡薄的水合與 SSR 啟動包裝器，以及何時自訂串流行為。"
+---
+
+# 入口點
+
+`app/entry.client.tsx` 在瀏覽器中水合伺服器渲染的 HTML，`app/entry.server.tsx` 則在伺服器上渲染該 HTML。兩者都是由 React Router 產生的簡薄包裝器。您很少需要編輯它們。
+
+```ts filename="app/entry.server.tsx"
+import {
+  createDocumentRequestHandler,
+  streamTimeout,
+} from "@agent-native/core/server/entry-server";
+import { ServerRouter } from "react-router";
+
+export default createDocumentRequestHandler(ServerRouter);
+export { streamTimeout };
+```
+
+只有在進行進階 SSR 自訂時才使用這些，例如變更串流行為。一般的頁面、版面配置和資料不需要在這裡做任何變更。若要新增頁面，請改參閱[路由](/docs/client-routing)。
+
+## 下一步是什麼
+
+- [**總覽**](/docs/client-overview) — 這些檔案在 `app/` 中的位置
+- [**路由**](/docs/client-routing) — 新增頁面，擴充 `app/` 的一般方式
+- [**進階**](/docs/client-advanced) — 其他較低階的用戶端原語與逃生口
diff --git a/packages/core/docs/content/locales/zh-TW/client-overview.mdx b/packages/core/docs/content/locales/zh-TW/client-overview.mdx
new file mode 100644
index 0000000000..a50573c3a0
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-TW/client-overview.mdx
@@ -0,0 +1,206 @@
+---
+title: "總覽"
+description: "app/ 與 public/ 目錄：您在此建置 agent-native 應用程式的實際外觀，以及它用來與代理保持同步的瀏覽器 API。"
+---
+
+# 總覽
+
+`app/` 是您建置 agent-native 應用程式實際外觀的地方：頁面、版面配置、元件、樣式。`public/` 存放與其一起提供的靜態資源 — 圖示、manifest、品牌標誌。這是一個典型的 React Router v8 應用程式，不是特殊的僅供代理使用的介面，也是大部分開發時間投入的地方。
+
+與典型前端唯一的架構差異：此層沒有屬於自己的 backend-for-frontend。它透過代理所呼叫的相同 actions 來讀取和寫入資料，因此在這裡連接的任何功能自動也是代理可以執行的功能。
+
+<Diagram id="doc-block-client-overview-1" title="傳統前端 vs. Agent Native" summary="傳統前端呼叫自己的 API 層，只有它自己能存取。在 Agent Native 中，app/ 和代理都呼叫相同的 actions，因此這裡建置的每項功能都能免費供代理呼叫。">
+
+```html
+<div class="diagram-cocmp">
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">傳統</div>
+    <div class="diagram-node">app/（React 前端）</div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <strong>API 層</strong>
+      <small class="diagram-muted">只有前端會呼叫它</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>資料庫</div>
+  </div>
+  <div class="cocmp-vs diagram-muted">vs</div>
+  <div class="cocmp-col">
+    <div class="cocmp-label diagram-muted">Agent Native</div>
+    <div class="cocmp-callers">
+      <div class="diagram-node">app/（React 前端）</div>
+      <div class="diagram-node">代理</div>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-panel" data-rough>
+      <span class="diagram-pill accent">Actions</span
+      ><small class="diagram-muted">平等的夥伴，相同的操作</small>
+    </div>
+    <div class="cocmp-arrow diagram-muted" aria-hidden="true">&#8595;</div>
+    <div class="diagram-box" data-rough>SQL 資料庫</div>
+  </div>
+</div>
+```
+
+```css
+.diagram-cocmp {
+  display: flex;
+  align-items: flex-start;
+  gap: 28px;
+  flex-wrap: wrap;
+}
+.cocmp-col {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 8px;
+  flex: 1;
+  min-width: 180px;
+}
+.cocmp-label {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-weight: 600;
+}
+.cocmp-callers {
+  display: flex;
+  gap: 8px;
+  flex-wrap: wrap;
+  justify-content: center;
+}
+.cocmp-vs {
+  font-size: 13px;
+  font-weight: 600;
+  padding-top: 52px;
+}
+.diagram-cocmp .diagram-panel {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 12px 16px;
+  align-self: stretch;
+  align-items: center;
+}
+.cocmp-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## Client 在架構中的位置 {#role}
+
+瀏覽器請求、代理迴圈和外部 API 用戶端都會解析到相同的 actions 和相同的 SQL 資料庫 — 這一層並沒有另一個代理無法觸及的獨立「應用後端」。在這裡建置一項功能，意味著在代理已經擁有的操作之上建置一個 UI，或是同時定義一個新的 action 並為它取得一個 UI。關於契約中操作端的內容，請參閱 [Actions](/docs/actions)。
+
+此頁面涵蓋您建置所在的目錄，以及沒有其他文件說明的瀏覽器執行階段部分（`root.tsx`、`public/`）。將您的元件連接到 actions 與代理的 React 掛鉤則各有專屬頁面：
+
+| 頁面                                            | 涵蓋內容                                                                                        |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| **[資料與同步](/docs/client-data)**             | `useActionQuery`、`useActionMutation`、`callAction` 和 `useDbSync`                              |
+| **[Agent 聊天](/docs/client-agent-chat)**       | `sendToAgentChat`、`askUserQuestion`、`openAgentSettings`、動態建議，以及暫存的代理聊天脈絡狀態 |
+| **[進階](/docs/client-advanced)**               | 直接存取 `application_state`、背景聊天傳送、自訂建議標籤，以及 MCP App 主機橋接                 |
+| **[同步內部機制](/docs/client-sync-internals)** | 用於同步原始 `useQuery` 的 `useChangeVersion`/`useChangeVersions`                               |
+| **[入口點](/docs/client-entry-points)**         | `app/entry.client.tsx`/`app/entry.server.tsx` 與 SSR 自訂                                       |
+
+## app/ 與 public/ 中的內容 {#project-directories}
+
+| 路徑                                                | 涵蓋內容                                                                                                |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| **`app/root.tsx`**                                  | HTML 外殼與提供者堆疊 — 請參閱下方[瀏覽器外殼](#app-shell)                                              |
+| **`app/entry.client.tsx` / `app/entry.server.tsx`** | 水合與 SSR 啟動 — 請參閱[入口點](/docs/client-entry-points)                                             |
+| **`app/routes.ts` + `app/routes/`**                 | 基於檔案的頁面與導覽 — 請參閱[路由](/docs/client-routing)                                               |
+| **`app/components/`**                               | 您的 UI：shadcn 風格的基礎元件與應用專屬元件 — 請參閱[shadcn/ui](/docs/shadcn-ui)                       |
+| **`app/hooks/`**                                    | 資料、同步與代理聊天掛鉤 — 請參閱[資料與同步](/docs/client-data)與[Agent 聊天](/docs/client-agent-chat) |
+| **`app/lib/`**                                      | 共用的用戶端工具（應用設定、分頁 id、`cn`）— 請參閱下方[實用工具](#utilities)                           |
+| **`app/design-system.ts`**                          | 選用的自訂設計系統適配器 — 請參閱[自訂設計系統](/docs/custom-design-system)                             |
+| **`app/i18n/`**                                     | 本地化的 UI 文字目錄 — 請參閱[國際化](/docs/internationalization)                                       |
+| **`app/global.css`**                                | 基礎樣式與 Tailwind 進入點                                                                              |
+| **`public/`**                                       | 原樣提供的靜態資源 — 請參閱下方[靜態資源](#public-directory)                                            |
+
+## 瀏覽器外殼：root.tsx 與 AppProviders {#app-shell}
+
+`app/root.tsx` 位於 React 樹的最上層：HTML 文件外殼（`<html>`、`<head>`、`<Meta>`、`<Links>`、`<Scripts>`）加上每個路由都會渲染在其中的提供者堆疊。
+
+```tsx filename="app/root.tsx"
+import {
+  AppProviders,
+  createAgentNativeQueryClient,
+} from "@agent-native/core/client/hooks";
+import { useState } from "react";
+import { Outlet } from "react-router";
+import { i18nCatalog } from "./i18n";
+
+export default function Root() {
+  const [queryClient] = useState(() => createAgentNativeQueryClient());
+
+  return (
+    <AppProviders queryClient={queryClient} i18n={{ catalog: i18nCatalog }}>
+      <Outlet />
+    </AppProviders>
+  );
+}
+```
+
+`AppProviders` 是連接以下項目的單一包裝器：
+
+- `useActionQuery`/`useActionMutation` 使用的 React Query 用戶端（請參閱[資料與同步](/docs/client-data#fetching-mutating)）。
+- 以 `i18n.catalog` 形式傳入的 i18n 目錄（請參閱[國際化](/docs/internationalization)）。
+- 用戶端工作階段檢查：在私人路徑上，匿名訪客會在任何私人 UI 掛載之前被重新導向到登入頁面。針對公開/SEO 路由傳入 `isPublicPath`，或針對以其他方式驗證的介面（例如 MCP 嵌入權杖）傳入 `sessionBypass`。請參閱[驗證](/docs/authentication)。
+
+大多數應用程式也會在這裡掛載 `<AgentSidebar>` 或 `<AgentPanel>`，讓每個路由都能免費取得代理面板。請參閱[臨時代理](/docs/drop-in-agent#sidebar)。
+
+## 靜態資源：public/ {#public-directory}
+
+`public/` 中的每個檔案都會原樣在網站根目錄提供，不經過建置處理。每個範本都會提供：
+
+```text
+public/
+  favicon.svg           -> browser tab icon
+  icon-180.svg           -> apple-touch-icon
+  icon-192.svg, icon-512.svg -> PWA icons referenced from manifest.json
+  manifest.json          -> web app manifest (name, theme color, icons)
+  *-logo-*.svg, *-icon-*.svg -> brand marks used in the default UI
+```
+
+`manifest.json` 控制訪客將應用程式安裝到主畫面或應用程式列時顯示的內容 — 名稱、簡稱、主題/背景顏色，以及圖示集：
+
+```json filename="public/manifest.json"
+{
+  "name": "My App",
+  "short_name": "My App",
+  "theme_color": "#18181B",
+  "icons": [
+    { "src": "icon-192.svg", "sizes": "192x192", "type": "image/svg+xml" }
+  ]
+}
+```
+
+透過替換這些檔案並更新 `manifest.json`，以及 `root.tsx` 中引用它們的 `<link rel="icon">`/`<link rel="apple-touch-icon">` 標籤，即可為應用程式換牌 — 沒有另外的註冊步驟。若要從現有網站拉取完整的品牌系統（顏色、字型、favicon），而不是手動編輯這些檔案，請參閱[品牌系統與 Figma](/docs/template-design-brand-and-figma)。
+
+## 實用工具：cn {#utilities}
+
+```ts
+import { cn } from "@agent-native/toolkit/utils";
+
+<div className={cn(
+  "px-4 py-2 rounded",
+  isActive && "bg-primary text-primary-foreground",
+  className
+)} />
+```
+
+`cn` 合併類別名稱（clsx + tailwind-merge），是在整個 `app/components/` 中組合條件式 Tailwind 類別的標準方式。
+
+## 下一步是什麼
+
+- [**資料與同步**](/docs/client-data) — action 掛鉤與 `useDbSync`
+- [**Agent 聊天**](/docs/client-agent-chat) — `sendToAgentChat`、`askUserQuestion` 與動態建議
+- [**進階**](/docs/client-advanced) — 應用程式狀態、背景聊天傳送，以及 MCP App 主機橋接
+- [**同步內部機制**](/docs/client-sync-internals) — 用於同步 `useQuery` 的 `useChangeVersion`
+- [**入口點**](/docs/client-entry-points) — SSR 啟動自訂
+- [**路由**](/docs/client-routing) — 基於檔案的頁面、動態參數與導覽
+- [**Actions**](/docs/actions) — 每個資料掛鉤背後的 `defineAction` 介面
+- [**自訂設計系統**](/docs/custom-design-system) — 透過 `app/design-system.ts` 換入您自己的元件庫
+- [**驗證**](/docs/authentication) — `AppProviders` 在私人路徑上執行的工作階段檢查
diff --git a/packages/core/docs/content/locales/zh-TW/client-routing.mdx b/packages/core/docs/content/locales/zh-TW/client-routing.mdx
new file mode 100644
index 0000000000..5dbc73aba7
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-TW/client-routing.mdx
@@ -0,0 +1,121 @@
+---
+title: "路由"
+description: "使用 React Router v8 為 agent-native 應用程式提供基於檔案的路由：頁面、動態參數與導覽。"
+---
+
+# 路由
+
+Agent-native 應用程式使用**React Router v8**，並透過來自 `@react-router/fs-routes` 的 `flatRoutes()` 進行基於檔案的路由。`app/routes/` 中的每個檔案都會變成一個 URL。範本使用點記號慣例。點在單一檔名內分隔 URL 區段。
+
+此頁面涵蓋用戶端路由，也就是從 `app/routes/` 在瀏覽器中渲染的頁面。伺服器路由是另一套系統：`server/routes/` 下的 Nitro 檔案路由，加上框架自身的 `/_agent-native/*` 端點。這些內容位於[路由](/docs/server-routes)頁面。這兩者不共用目錄、命名慣例，也不共用路由器，因此 `server/routes/` 中的檔案永遠不會變成這裡的頁面，`app/routes/` 中的檔案也永遠不會變成伺服器端點。
+
+<Diagram id="doc-block-client-routing-1" title="檔名 → URL" summary="app/routes/ 中的每個檔案都會變成一個 URL。點會變成斜線，而 $ 區段會變成動態參數。">
+
+```html
+<div class="diagram-filemap">
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">_index.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard</span>
+  </div>
+  <div class="diagram-filemap-row">
+    <span class="diagram-node">dashboard_.$ticketId.tsx</span>
+    <span class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</span>
+    <span class="diagram-pill accent">/dashboard/:ticketId</span>
+  </div>
+</div>
+```
+
+```css
+.diagram-filemap {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+.diagram-filemap-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.diagram-filemap-row .diagram-arrow {
+  font-size: 18px;
+  line-height: 1;
+}
+```
+
+</Diagram>
+
+## 基於檔案的路由 {#file-based-routing}
+
+### 檔案 → URL 對應
+
+| 檔案                       | URL                    | 註解                                                                 |
+| -------------------------- | ---------------------- | -------------------------------------------------------------------- |
+| `_index.tsx`               | `/`                    | 索引路由                                                             |
+| `dashboard.tsx`            | `/dashboard`           | 簡單頁面                                                             |
+| `extensions.$id.tsx`       | `/extensions/:id`      | 巢狀於 `extensions.tsx` 的 `<Outlet/>` 內。`$` 是動態參數            |
+| `dashboard_.$ticketId.tsx` | `/dashboard/:ticketId` | 結尾的 `_` 跳過巢狀於 `dashboard.tsx` 之下，因此這是它自己獨立的頁面 |
+| `_app.tsx`                 | （無 URL 區段）        | 無路徑版面配置路由。加上 `_` 前綴                                    |
+| `inbox/route.tsx`          | `/inbox`               | 資料夾形式。`route.tsx` 是索引                                       |
+
+在某個區段加上 `$` 前綴以表示動態參數。加上 `_` 前綴使其成為無路徑版面配置路由（沒有 URL 區段），或在點之前加上結尾的 `_`，讓一個看起來會巢狀的路徑選擇退出巢狀於其父層版面配置之下。範本使用 `flatRoutes()`。上方的點記號檔案是主要形式。巢狀資料夾形式 `inbox/route.tsx` 也同樣可行。
+
+## 新增一個新頁面 {#adding-a-page}
+
+建立檔案並匯出一個預設元件：
+
+```tsx filename="app/routes/settings.tsx"
+export function meta() {
+  return [{ title: "Settings" }];
+}
+
+export default function SettingsPage() {
+  return <div>Settings</div>;
+}
+```
+
+就是這樣。React Router 會自動選取它，不需要任何註冊。
+
+## 動態參數 {#dynamic-params}
+
+```tsx filename="app/routes/dashboard_.$ticketId.tsx"
+import { useParams } from "react-router";
+
+export default function TicketDetailPage() {
+  const { ticketId } = useParams();
+  return <div>Ticket: {ticketId}</div>;
+}
+```
+
+點之前結尾的 `_` 讓此頁面不會巢狀在 `dashboard.tsx` 的 `<Outlet/>` 內，因此它會以自己完整頁面的形式在 `/dashboard/:ticketId` 渲染，而不是出現在工單佇列的版面配置之中。
+
+## 導覽 {#navigation}
+
+使用 `<Link>` 進行用戶端導覽，使用 `useNavigate()` 進行程式化導覽：
+
+```tsx
+import { Link, useNavigate } from "react-router";
+
+// In JSX
+<Link to="/dashboard">Dashboard</Link>;
+
+// Programmatic
+const navigate = useNavigate();
+navigate(`/dashboard/${ticketId}`);
+```
+
+這兩者本身都不會告訴代理使用者正在看什麼。那是另一個獨立的關注點，由 `useAgentRouteState()` 將目前路由寫入應用程式狀態來處理。請參閱[脈絡感知](/docs/context-awareness)。
+
+## 下一步是什麼
+
+- [**總覽**](/docs/client-overview) — `app/routes/` 在 `app/` 和 `public/` 其他部分中的位置
+- [**資料與同步**](/docs/client-data) — 在路由內讀取與寫入資料
+- [**Agent 聊天**](/docs/client-agent-chat) — 從路由傳送提示與暫存脈絡
+- [**路由**](/docs/server-routes) — 另一套獨立的伺服器路由系統：`server/routes/` 下的檔案路由，以及框架的 `/_agent-native/` 命名空間
+- [**脈絡感知**](/docs/context-awareness) — 代理如何得知目前的路由與選取內容
diff --git a/packages/core/docs/content/locales/zh-TW/client-sync-internals.mdx b/packages/core/docs/content/locales/zh-TW/client-sync-internals.mdx
new file mode 100644
index 0000000000..7b99a9b7e5
--- /dev/null
+++ b/packages/core/docs/content/locales/zh-TW/client-sync-internals.mdx
@@ -0,0 +1,123 @@
+---
+title: "同步內部機制"
+description: "useDbSync 背後的變更版本機制：用於同步原始 useQuery 的 useChangeVersion/useChangeVersions，以及重新取得可能經過的兩條延遲路徑。"
+---
+
+# 同步內部機制
+
+[即時同步](/docs/key-concepts#polling-sync)涵蓋了心智模型：一次代理寫入變成一個變更事件，`useDbSync()` 接收到它，受影響的查詢就會重新取得。此頁面涵蓋大多數應用程式從不直接碰觸的底層機制：`useDbSync()` 所遞增的變更版本計數器，以及如何將它們折疊進一個沒有經過 `useActionQuery()` 的原始 `useQuery()` 呼叫中。
+
+`useActionQuery()` 在變異 action 完成時已經會自動重新取得（請參閱[資料與同步](/docs/client-data#fetching-mutating)）。只有在您要同步一個位於該路徑之外的原始 `useQuery()` 呼叫時，才使用 `useChangeVersion()`/`useChangeVersions()`，例如讀取整合狀態的低階用戶端輔助函式。
+
+## 變更版本如何運作 {#how-it-works}
+
+當伺服器端資料庫發生變異時，伺服器會記錄一個帶有 `source` 鍵標籤的變更事件。`useDbSync()` 接收該事件，並為該來源遞增一個本機計數器。將此計數器折疊進 React Query 鍵中，會讓查詢在後端回報該來源有新活動時自動重新取得。
+
+## useChangeVersion / useChangeVersions {#use-change-version}
+
+<Signature
+  id="doc-block-client-sync-internals-1"
+  name="useChangeVersion"
+  params={[
+    {
+      name: "source",
+      type: "string",
+      description: '要監看的變更事件來源，例如 `"dashboards"`。',
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "一個計數器，每當指定的來源發生變異時就會遞增。",
+  }}
+/>
+
+<Signature
+  id="doc-block-client-sync-internals-2"
+  name="useChangeVersions"
+  params={[
+    {
+      name: "sources",
+      type: "readonly string[]",
+      description: "要同時監看的多個變更事件來源。",
+    },
+  ]}
+  returns={{
+    type: "number",
+    description: "多個指定來源版本計數器的總和。",
+  }}
+/>
+
+在下方的範例中，一個原始的 `useQuery()` 呼叫直接讀取一個儀表板，並將 `"dashboards"` 來源的版本計數器折疊進其查詢鍵，使其在該來源發生變化時重新取得：
+
+```tsx
+import { useQuery } from "@tanstack/react-query";
+import { useChangeVersion } from "@agent-native/core/client/hooks";
+
+function DashboardView({ id }) {
+  const version = useChangeVersion("dashboards");
+
+  const { data } = useQuery({
+    queryKey: ["dashboard", id, version],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev,
+  });
+
+  return <div>{data?.title}</div>;
+}
+```
+
+`placeholderData: (prev) => prev` 讓重新取得期間畫面上保留先前的資料，因此檢視畫面不會閃爍到載入狀態。
+
+## 重新取得的兩條路徑 {#latency-models}
+
+一次變異透過兩種方式到達 UI，而它們的延遲不同。
+
+一次本機變異，也就是您自己的 `useActionMutation()` 呼叫剛剛所做的變異，會在成功後立即發出一個 `source: "action"` 事件。每個依賴該 action 的查詢都會立即重新取得。沒有來回延遲，因為進行寫入的分頁已經知道這件事。
+
+一次遠端變異，來自代理、webhook、另一個分頁或另一位使用者，必須先傳達到這個分頁。`useDbSync()` 幾乎立即透過 SSE 接收到它，或若 SSE 不可用，則在約兩秒內透過輪詢備援接收到它。只有在該事件到達之後，相關的版本計數器才會遞增，查詢才會在背景重新取得。
+
+<Diagram id="doc-block-client-sync-internals-3" title="重新取得的兩條路徑" summary="本機變異會立即使自己的快取失效。遠端寫入透過 SSE 到達此分頁，或以輪詢作為備援。">
+
+```html
+<div class="diagram-latency">
+  <div class="diagram-col">
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill ok">此分頁</span
+      ><strong>useActionMutation</strong
+      ><small class="diagram-muted"
+        >成功時發出 source: "action" &rarr; 立即在本機重新取得</small
+      >
+    </div>
+    <div class="diagram-card" data-rough>
+      <span class="diagram-pill accent">代理 · webhook · 其他分頁</span
+      ><strong>遠端寫入</strong
+      ><small class="diagram-muted"
+        >SSE 推送，或以約 2 秒的輪詢週期作為備援 &rarr; 版本遞增 &rarr;
+        背景重新取得</small
+      >
+    </div>
+  </div>
+</div>
+```
+
+```css
+.diagram-latency .diagram-col {
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+.diagram-latency .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 14px 16px;
+}
+```
+
+</Diagram>
+
+## 下一步是什麼
+
+- [**即時同步**](/docs/key-concepts#polling-sync) — 此頁面所深入探討的概念性心智模型
+- [**資料與同步**](/docs/client-data) — `useActionQuery`/`useDbSync`，大多數頁面應改用這些而非這些原語
+- [**進階**](/docs/client-advanced) — 其他較低階的用戶端原語與逃生口
diff --git a/packages/core/docs/content/locales/zh-TW/client.mdx b/packages/core/docs/content/locales/zh-TW/client.mdx
deleted file mode 100644
index f787f19496..0000000000
--- a/packages/core/docs/content/locales/zh-TW/client.mdx
+++ /dev/null
@@ -1,470 +0,0 @@
----
-title: "用戶端"
-description: "用於 Agent-Native 應用程式的 React 掛鉤和實用程式：sendToAgentChat、可選代理聊天脈絡狀態、useDbSync、useAgentChatGenerate 和 cn。"
----
-
-# 用戶端
-
-`@agent-native/core` 為 Agent-Native 應用程式的瀏覽器端提供 React 掛鉤和實用程式。
-
-這些用戶端/React API 是從 `@agent-native/core` 和 `@agent-native/core/client` 匯出的。為了清晰和正確的捆綁，從 `@agent-native/core/client`（瀏覽器條目）匯入它們，因為預設情況下裸 `@agent-native/core` 根解析為 Node 建置。
-
-對於基於檔案的路由 - 新增頁面、動態參數和導覽 - 請參閱 [Routing](/docs/routing)。
-
-## 取得和修改資料 {#fetching-mutating}
-
-從瀏覽器讀取和寫入應用程式資料的主要方式是透過操作掛鉤。切勿手寫 `fetch` 呼叫 `/_agent-native/*` 路由 - 請改用命名助手（請參閱 [Actions](/docs/actions)）。
-
-<Diagram id="doc-block-ttv3d8" title={"瀏覽器資料迴圈"} summary={"鉤子透過動作進行讀寫； useDbSync 監視資料庫，以便代理和背景寫入自動重新取得相同的快取。"}>
-
-```html
-<div class="diagram-client">
-  <div class="diagram-col">
-    <div class="diagram-node">
-      useActionQuery<br /><small class="diagram-muted">cached read</small>
-    </div>
-    <div class="diagram-node">
-      useActionMutation<br /><small class="diagram-muted"
-        >write + invalidate</small
-      >
-    </div>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-box" data-rough>
-    Actions<br /><small class="diagram-muted">/_agent-native/actions/*</small>
-  </div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&harr;</div>
-  <div class="diagram-panel" data-rough><strong>SQL 資料庫</strong></div>
-  <div class="diagram-arrow diagram-muted" aria-hidden="true">&#8635;</div>
-  <div class="diagram-pill ok">useDbSync &rarr; refetch on change</div>
-</div>
-```
-
-```css
-.diagram-client {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  flex-wrap: wrap;
-}
-.diagram-client .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 10px;
-}
-.diagram-client .diagram-arrow {
-  font-size: 22px;
-  line-height: 1;
-}
-```
-
-</Diagram>
-
-```tsx
-import {
-  useActionQuery,
-  useActionMutation,
-  callAction,
-} from "@agent-native/core/client/hooks";
-// Read: auto-cached, auto-invalidated on mutations
-const { data, isLoading } = useActionQuery("get-lead", { leadId });
-
-// Mutate: emits a change event so query caches refetch
-const { mutate, isPending } = useActionMutation("create-lead");
-mutate({ name: "Alice", company: "Acme" });
-
-// Imperative: for one-off calls outside a component
-await callAction("archive-lead", { leadId });
-```
-
-## sendToAgentChat（選取） {#sendtoagentchat}
-
-透過 postMessage 向代理聊天傳送訊息——這是從 UI 互動中委派 AI 工作的常用方法。傳遞 `context` 來隱藏模型脈絡，傳遞 `submit: true` 來立即傳送，或者傳遞 `submit: false` 來預先填寫使用者首先審閱的草稿。
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with hidden context
-sendToAgentChat({
-  message: "Generate alt text for this image",
-  context: "Image path: /api/projects/hero.jpg",
-  submit: true,
-});
-
-// Prefill without submitting (user reviews first)
-sendToAgentChat({
-  message: "Rewrite this in a conversational tone",
-  context: selectedText,
-  submit: false,
-});
-```
-
-在使用 `embedApp()` 建立的 MCP 應用嵌入中，自動提交訊息
-（`submit`省略或`true`）被轉發到 MCP 應用程式主橋，這
-要求包含主機新增隱藏脈絡並傳送可見使用者回合。
-`context` 保持模型可見，而不發布為面向使用者的聊天。
-`submit: false` 保留本機預填充/審核行為，因為 MCP 應用不會
-定義標準草稿預填充 API。在內部，這是提交的聊天路徑
-有時會以 `agentNative.submitChat` 的形式出現；應用程式碼應該呼叫
-`sendToAgentChat()` 而不是直接發布該事件。
-
-### 背景靜默傳送 {#background-send}
-
-當 UI 操作應該啟動真正的代理工作時，請使用 `background: true`
-開啟或聚焦側邊欄。這仍然會建立一個正常的聊天對話串/執行，
-使用代理的工具/actions/context，並透過以下方式保持工作可觀察
-執行托盤；它不是原始的一次性模型呼叫。
-
-```ts
-const tabId = sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-`background` 旨在與 `newTab` 配對，因此隱藏的工作不會
-overwrite the user's active conversation. Use the returned `tabId` if the UI
-需要將後續狀態或深層連結關聯到稍後的執行。
-
-### 代理聊天訊息 {#agentchatmessage}
-
-| 選項                  | 型別        | 描述                                                              |
-| --------------------- | ----------- | ----------------------------------------------------------------- |
-| `message`             | `string`    | 傳送到聊天的可見提示                                              |
-| `context`             | `string?`   | 附加隱藏脈絡（聊天 UI 中未顯示）                                  |
-| `submit`              | `boolean?`  | true = 自動提交，false = 僅預填充                                 |
-| `newTab`              | `boolean?`  | 為此提示建立單獨的聊天對話串                                      |
-| `background`          | `boolean?`  | 使用 `newTab`，在不聚焦分頁的情況下執行並在 `RunsTray` 中顯示執行 |
-| `openSidebar`         | `boolean?`  | 設定 false 來提交/預填充而不開啟側邊欄                            |
-| `projectSlug`         | `string?`   | 結構化脈絡的可選專案段                                            |
-| `preset`              | `string?`   | 下游消費者的可選預設名稱                                          |
-| `referenceImagePaths` | `string[]?` | 可選的參考圖片路徑                                                |
-
-## 代理聊天脈絡狀態（進階） {#agent-chat-context-state}
-
-脈絡狀態 API 是 UI 的可選管道，需要雙向同步
-暫存脈絡標籤：在編輯器之外渲染目前暫存專案，
-反映某個專案是否已附加，或提供明確的
-刪除/清除控制項。
-
-不要為了簡單的“將其傳送給代理”而聯絡這些助手，或者
-“預填寫此草稿以供審核”流程。將 `sendToAgentChat()` 與 `context` 結合使用
-還有 `submit`。
-
-| API                               | 何時使用                                      |
-| --------------------------------- | --------------------------------------------- |
-| `useAgentChatContext()`           | React 元件需要即時暫存脈絡清單                |
-| `setAgentChatContextItem(item)`   | 指令式程式碼應暫存或替換一個鍵控脈絡項        |
-| `listAgentChatContext()`          | 非 React 程式碼需要暫存脈絡的一次性快照       |
-| `removeAgentChatContextItem(key)` | UI 應透過其穩定的 `key` 刪除一個暫存脈絡項    |
-| `clearAgentChatContext()`         | UI 應清除所有暫存脈絡，例如在檢視或模式重設後 |
-| `refreshAgentChatContext()`       | 指令程式碼應該重新讀取最新的持久脈絡快照      |
-
-`useAgentChatContext()` 返回 `{ items, set, remove, clear, refresh }`。
-
-## openAgentSettings（部分？） {#openagentsettings}
-
-當應用設定頁面或設定卡開啟時使用 `openAgentSettings()`
-代理側邊欄的“設定”分頁。傳遞一個部分id，例如`"llm"`，`"secrets"`，
-`"automations"`、`"voice"` 或 `"limits"` 開啟特定部分。
-
-```ts
-import { openAgentSettings } from "@agent-native/core/client/navigation";
-openAgentSettings();
-openAgentSettings("secrets");
-```
-
-更喜歡這個助手而不是直接調度 `agent-panel:open-settings`。
-
-```tsx
-import { useAgentChatContext } from "@agent-native/core/client/agent-chat";
-function SelectionContextButton({ record }: { record: { id: string } }) {
-  const chatContext = useAgentChatContext();
-  const contextKey = `selected-record:${record.id}`;
-  const isAttached = chatContext.items.some((item) => item.key === contextKey);
-
-  return (
-    <button
-      type="button"
-      onClick={() => {
-        if (isAttached) {
-          chatContext.remove(contextKey);
-          return;
-        }
-
-        chatContext.set({
-          key: contextKey,
-          title: "Selected Record",
-          context: JSON.stringify(record, null, 2),
-          openSidebar: false,
-        });
-      }}
-    >
-      {isAttached ? "Remove from prompt context" : "Add to prompt context"}
-    </button>
-  );
-}
-```
-
-`listAgentChatContext()` 用於僅需要檢查的指令式程式碼
-目前暫存專案一次。 `clearAgentChatContext()` 故意寬泛；使用
-僅更改一項選取時為 `removeAgentChatContextItem(key)`。
-
-### AgentChatContextSetOptions {#agentchatcontextsetoptions}
-
-| 選項          | 型別       | 描述                                      |
-| ------------- | ---------- | ----------------------------------------- |
-| `key`         | `string`   | 用於替換現有塊的穩定識別碼                |
-| `title`       | `string`   | 撰寫器標籤中顯示的短標籤                  |
-| `context`     | `string`   | 下一個提交的提示中包含隱藏脈絡            |
-| `openSidebar` | `boolean?` | 預設為true；靜默地將 false 傳遞給舞台脈絡 |
-
-## 詢問使用者問題（選取） {#ask-user-question}
-
-透過應用程式碼向使用者提出多項選取問題，並將其行內呈現
-代理小組，並**等待他們的答覆**。它是用戶端的孿生
-代理的內建`ask-question`工具：它將`GuidedQuestionPayload`寫入
-`"guided-questions"` 應用程式狀態金鑰（已安裝的位置
-`GuidedQuestionFlow` 渲染它）並顯示代理面板，所以問題是
-可見。與代理工具不同——其答案會返回給代理——
-`askUserQuestion()` **解析呼叫者的答案**，因此 UI 可以
-在上面分支。
-
-當 UI 之前需要做出一個小決定（2-4 個選項）時使用它
-開始代理工作——而不是建置自訂模式。到達
-用於自由形式細節的組合器，以及用於多欄位輸入的表單/快顯框。
-
-```tsx
-import {
-  askUserQuestion,
-  sendToAgentChat,
-} from "@agent-native/core/client/agent-chat";
-const length = await askUserQuestion({
-  question: "How long should this deck be?",
-  header: "Deck length", // optional short chip/heading (≈12 chars)
-  options: [
-    { label: "Short (3–5 slides)", value: "short" },
-    { label: "Medium (6–10 slides)", value: "medium", recommended: true },
-    { label: "Long (11+ slides)", value: "long" },
-  ],
-  allowFreeText: false, // omit the "Other" free-text option (default adds it)
-  allowMultiple: false, // single-select (default)
-});
-
-if (length) {
-  sendToAgentChat({ message: `Generate a ${length} deck.`, submit: true });
-}
-```
-
-每個選項都是`{ label, value?, description?, preview?, recommended? }`； `value`
-預設為`label`，`preview`在
-選項。承諾以選定的 `value`（或 `value[]` 時）解析
-`allowMultiple`)，使用者選取“其他”時的自由文字字串，或 `null`
-如果他們跳過——它將保持待定狀態，直到使用者回答。需要代理面板
-要安裝（每個範本中都有）。
-
-代理透過其 `ask-question` 工具到達相同的 UI：更願意讓
-當 _it_ 遇到一個無法從脈絡解析的真正分叉時，代理會詢問；使用
-`askUserQuestion()`，當 _UI_ 需要對選取進行操作時。
-
-## MCP 應用程式主橋 {#mcp-app-host-bridge}
-
-作為 MCP 應用嵌入的路由應該是 URL-first：載入目前工件
-路徑/查詢參數，渲染真實的 React 路由或聚焦的共用元件，
-並且僅將主機橋用於主機擁有的行為。 `@agent-native/core/client`
-匯出助手嵌入的路由呼叫：
-
-```ts
-import {
-  getMcpAppHostContext,
-  openMcpAppHostLink,
-  requestMcpAppDisplayMode,
-  updateMcpAppModelContext,
-  useMcpAppHostContext,
-} from "@agent-native/core/client/agent-chat";
-```
-
-`getMcpAppHostContext()`讀取最新推送的主機脈絡快照；
-`useMcpAppHostContext()` 訂閱 React 元件的更改。請求
-助手（`openMcpAppHostLink`、`requestMcpAppDisplayMode`，
-`updateMcpAppModelContext`) 在嵌入式 MCP 應用框架之外返回 `false`，或
-`Promise<boolean>` 在框架內。 `sendToAgentChat()` 使用相同的橋
-從嵌入式路由自動提交提示。
-
-橋本身 - `ui/*` JSON-RPC 訊息、`agentNative.mcpHost.*`
-包裝器中繼、移植與受控幀渲染、主機脈絡以及
-顯示模式請求 — 屬於
-[External Agents](/docs/external-agents#mcp-app-bridge).
-
-## 動態建議 {#dynamic-suggestions}
-
-`<AgentSidebar>`、`<AgentPanel>` 和 `<AssistantChat>` 預設將靜態 `suggestions` 與脈絡感知建議合併。當可見空聊天時，框架從應用程式狀態中讀取 `navigation`、`selection`、`pending-selection-context` 和目前 URL，然後提供與目前螢幕匹配的提示標籤。
-
-```tsx
-<AgentSidebar
-  suggestions={["Summarize my inbox"]}
-  dynamicSuggestions={{ max: 4 }}
->
-  <App />
-</AgentSidebar>
-```
-
-設定 `dynamicSuggestions={false}` 僅保留靜態標籤。當應用程式需要來自同一應用程式狀態脈絡的確定性特定於域的標籤時，傳遞 `getSuggestions`。
-
-## useAgentChatGenerate() {#useagentchatgenerating}
-
-React 鉤子，透過載入狀態跟蹤包裝 sendToAgentChat：
-
-```ts
-import {
-  useAgentChatGenerating,
-} from "@agent-native/core/client/agent-chat"
-function GenerateButton() {
-  const [isGenerating, send] = useAgentChatGenerating();
-
-  return (
-    <button
-      disabled={isGenerating}
-      onClick={() => send({
-        message: "Generate a summary",
-        context: documentContent,
-        submit: true,
-      })}
-    >
-      {isGenerating ? "Generating..." : "Generate"}
-    </button>
-  );
-}
-```
-
-當您呼叫 `send()` 時，`isGenerating` 變為 true，並在代理完成生成時自動重設為 false。
-
-## useDbSync（選項？） {#usedbsync}
-
-React 掛鉤（以前稱為 `useFileWatcher`），用於偵聽 SSE 上的資料庫更改，回退到輪詢，並使保持 UI 與代理寫入保持一致的框架查詢快取無效：
-
-```ts
-import {
-  useDbSync,
-} from "@agent-native/core/client/hooks"
-import { useQueryClient } from "@tanstack/react-query";
-
-function App() {
-  const queryClient = useQueryClient();
-
-  useDbSync({
-    queryClient,
-    pollUrl: "/_agent-native/poll",
-    onEvent: (data) => console.log("Data changed:", data),
-  });
-
-  return <div>...</div>;
-}
-```
-
-### 選項 {#usedbsync-options}
-
-| 選項               | 型別               | 描述                                                                                   |
-| ------------------ | ------------------ | -------------------------------------------------------------------------------------- |
-| `queryClient`      | `QueryClient?`     | React-查詢用戶端快取失效                                                               |
-| `queryKeys`        | `string[]?`        | 已棄用並被忽略；為舊的呼叫站點保留                                                     |
-| `pollUrl`          | `string?`          | 輪詢端點 URL。預設值：`"/_agent-native/poll"`                                          |
-| `sseUrl`           | `string \| false?` | SSE endpoint URL. Default: `"/_agent-native/events"`; pass `false` to use polling only |
-| `interval`         | `number?`          | 輪詢間隔（以毫秒為單位）。預設值：`2000`                                               |
-| `fallbackInterval` | `number?`          | SSE 不可用時的回退輪詢間隔。預設值：`15000`                                            |
-| `pauseWhenHidden`  | `boolean?`         | 當瀏覽器分頁隱藏時暫停輪詢。預設值：`true`                                             |
-| `ignoreSource`     | `string?`          | 要忽略的每個分頁請求來源，以便分頁不會從其自己的寫入中重新取得                         |
-| `onEvent`          | `(data) => void`   | SSE/polling 收到更改事件時的可選回調                                                   |
-
-對於普通CRUD，優先選取`useActionQuery`和`useActionMutation`；變異 actions 會發出 `source: "action"` 並且這些鉤子會自動重新取得。
-
-## useChangeVersion / useChangeVersions {#use-change-version}
-
-框架使用更改版本將 React 查詢快取與背景代理、cron 作業或其他使用者所做的更改同步。
-
-當任何伺服器端資料庫發生突變時，伺服器都會使用特定的 `source` 金鑰紀錄更改事件。用戶端的 `useDbSync` 偵聽器接收這些事件並增加該來源的本機更改版本計數器。透過將版本計數器折疊到 React 查詢鍵中，每當後端通知用戶端新活動時，查詢就會自動重新取得。
-
-- **`useChangeVersion(source: string): number`** — 返回一個計數器，每當指定的 `source` 發生突變時該計數器就會遞增。
-- **`useChangeVersions(sources: readonly string[]): number`** — 返回多個來源的版本計數器之和。
-
-### 範例：將原始查詢與資料庫同步
-
-```tsx
-import { useQuery } from "@tanstack/react-query";
-import { useChangeVersion } from "@agent-native/core/client/hooks";
-function DashboardView({ id }) {
-  // Get version for dashboards domain source
-  const v = useChangeVersion("dashboards");
-
-  const { data } = useQuery({
-    queryKey: ["dashboard", id, v], // Invalidate automatically when version bumps
-    queryFn: () => fetchDashboard(id),
-    placeholderData: (prev) => prev, // Prevent layout flicker during refetch
-  });
-
-  return <div>{data?.title}</div>;
-}
-```
-
-### 延遲模型和失效行為
-
-- **UI-發起的突變：**當您使用 `useActionMutation` 從 UI 執行操作時，突變會在成功時立即觸發 `source: "action"` 本機事件。這會根據該操作觸發所有查詢鍵的**即時、樂觀的重新取得**，從而避免視覺延遲。
-- **背景或代理突變：** 當 AI 代理、Webhook 或背景工作人員突變資料時，更新會廣播到用戶端。用戶端的 `useDbSync` 可以立即透過 SSE（伺服器傳送的事件）捕獲此資訊，也可以回退到 **2 秒輪詢滴答**。然後查詢金鑰版本會發生變化，從而觸發背景重新取得。
-
-<Diagram id="doc-block-10uqc8p" title={"重新取得的兩條路徑"} summary={"本機突變會立即使自己的快取失效；遠端寫入透過 SSE 到達此分頁，或作為後備的輪詢標記。"}>
-
-```html
-<div class="diagram-latency">
-  <div class="diagram-col">
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill ok">此標籤頁面</span
-      ><strong>useActionMutation</strong
-      ><small class="diagram-muted"
-        >fires source: "action" on success &rarr; instant local refetch</small
-      >
-    </div>
-    <div class="diagram-card" data-rough>
-      <span class="diagram-pill accent">代理 · webhook · 其他標籤頁面</span
-      ><strong>遠端寫入</strong
-      ><small class="diagram-muted"
-        >SSE push, or the ~2s polling tick as fallback &rarr; version bumps
-        &rarr; background refetch</small
-      >
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-latency .diagram-col {
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-}
-.diagram-latency .diagram-card {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  padding: 14px 16px;
-}
-```
-
-</Diagram>
-
-## cn（...輸入） {#cn}
-
-合併類名的實用程式（clsx + tailwind-merge）：
-
-```ts
-import {
-  cn,
-} from "@agent-native/toolkit/utils"
-<div className={cn(
-  "px-4 py-2 rounded",
-  isActive && "bg-primary text-primary-foreground",
-  className
-)} />
-```
diff --git a/packages/core/docs/content/locales/zh-TW/drop-in-agent.mdx b/packages/core/docs/content/locales/zh-TW/drop-in-agent.mdx
index e322947448..ceb3cc470b 100644
--- a/packages/core/docs/content/locales/zh-TW/drop-in-agent.mdx
+++ b/packages/core/docs/content/locales/zh-TW/drop-in-agent.mdx
@@ -225,7 +225,7 @@ sendToAgentChat({
 
 當嵌入相同的路由作為 MCP App 時，提交
 `sendToAgentChat()` 呼叫將轉發至支援的聊天主機；參見
-[Client](/docs/client#sendtoagentchat) 用於 MCP 應用橋接行為。
+[Agent 聊天](/docs/client-agent-chat#sendtoagentchat) 用於 MCP 應用橋接行為。
 
 如果您想要載入狀態，請使用 `useSendToAgentChat()` 鉤子 - 它返回 `send` 和 `isGenerating`：
 
diff --git a/packages/core/docs/content/locales/zh-TW/notifications.mdx b/packages/core/docs/content/locales/zh-TW/notifications.mdx
index 62d958c08f..13b51d726e 100644
--- a/packages/core/docs/content/locales/zh-TW/notifications.mdx
+++ b/packages/core/docs/content/locales/zh-TW/notifications.mdx
@@ -363,7 +363,7 @@ export function HeaderBar() {
 ## 它是如何工作的 {#internals}
 
 - **所有者範圍** — 每行都有一個 `owner` 列；每個查詢都會對其進行過濾；每個路由都使用經過驗證的工作階段的電子郵件。使用者永遠不會看到彼此的通知。
-- **輪詢整合** - 每個突變都會呼叫 `recordChange()`，因此使用 [`useDbSync`](/docs/client) 的範本會自動失效，無需任何額外的接線。
+- **輪詢整合** - 每個突變都會呼叫 `recordChange()`，因此使用 [`useDbSync`](/docs/client-data#usedbsync) 的範本會自動失效，無需任何額外的接線。
 - **盡力扇出** — 捕獲並紀錄通道錯誤；一個失敗的通道不會阻止其他通道或收件箱寫入。
 - **即發即忘** — `notify()` 在收件箱寫入完成後返回；自訂通道在背景執行。
 
diff --git a/packages/core/docs/content/locales/zh-TW/progress.mdx b/packages/core/docs/content/locales/zh-TW/progress.mdx
index 6dfb0d9733..8d934c93f9 100644
--- a/packages/core/docs/content/locales/zh-TW/progress.mdx
+++ b/packages/core/docs/content/locales/zh-TW/progress.mdx
@@ -233,7 +233,7 @@ mode: agentic
 ## 它是如何工作的 {#internals}
 
 - **所有者範圍** — 每行都有一個 `owner` 列；每個查詢都會對其進行過濾。使用者只能看到自己的跑步。
-- **輪詢整合** - 每個突變都會呼叫 `recordChange()`，因此使用 [`useDbSync`](/docs/client) 的範本會自動失效，無需任何額外的接線。
+- **輪詢整合** - 每個突變都會呼叫 `recordChange()`，因此使用 [`useDbSync`](/docs/client-data#usedbsync) 的範本會自動失效，無需任何額外的接線。
 - **表名稱** — 此框架還有一個 `agent_runs` 表，用於內部代理聊天回合生命週期跟蹤。進度原語使用 `progress_runs` 將兩個關注點分開。
 - **百分比限制** — 值被限制為 `[0, 100]` 並在寫入時四舍五入為整數。
 
@@ -241,4 +241,4 @@ mode: agentic
 
 - [**Notifications**](/docs/notifications) — 與 `manage-progress` (`action=complete`) 配對，告訴使用者工作何時完成
 - [**Automations**](/docs/automations) — 看門狗透過 `run.progress.updated` 緩慢執行
-- [**Client**](/docs/client) — `useDbSync` 用於即時快取失效
+- [**資料與同步**](/docs/client-data) — `useDbSync` 用於即時快取失效
diff --git a/packages/core/docs/content/locales/zh-TW/real-time-collaboration.mdx b/packages/core/docs/content/locales/zh-TW/real-time-collaboration.mdx
index 7d0fd754ec..4d66fe1455 100644
--- a/packages/core/docs/content/locales/zh-TW/real-time-collaboration.mdx
+++ b/packages/core/docs/content/locales/zh-TW/real-time-collaboration.mdx
@@ -17,7 +17,7 @@ description: "多使用者協作編輯，其中 AI 代理是一流的同行：CR
 與代理一起編輯感覺就像在協作編輯器中工作
 一位既快速又不知疲倦的同事：
 
-如果您只需要在代理或其他使用者寫入 SQL 時重新整理 UI，則不需要任何這些 — 使用 [`useDbSync`](/docs/client)。此頁面用於對單一富文字檔案進行字符級共同編輯（共用游標、無衝突合併）。兩者都使用相同的 `/_agent-native/poll` 通道。
+如果您只需要在代理或其他使用者寫入 SQL 時重新整理 UI，則不需要任何這些 — 使用 [`useDbSync`](/docs/client-data#usedbsync)。此頁面用於對單一富文字檔案進行字符級共同編輯（共用游標、無衝突合併）。兩者都使用相同的 `/_agent-native/poll` 通道。
 
 它建立在三項經過實战檢驗的技術之上：**Yjs**（CRDT，用於無衝突合併）、**TipTap**（富文字編輯器）和**基於輪詢的同步**（適用於所有部署環境，包括無伺服器和邊緣）。
 
@@ -764,7 +764,7 @@ Use `emailToColor(email)` and `emailToName(email)` from
 
 ## 相關檔案 {#related}
 
-- [Real-Time Sync](/docs/client#usedbsync) — `useDbSync` + `useChangeVersion`
+- [Sync Internals](/docs/client-sync-internals) — `useDbSync` + `useChangeVersion`
   提供 `updatedAt` 碰撞驅動編輯器協調的系統。
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   和 `assertAccess`，用於資源範圍內的協作。
diff --git a/packages/core/docs/content/locales/zh-TW/routing.mdx b/packages/core/docs/content/locales/zh-TW/routing.mdx
deleted file mode 100644
index 746b3bcb66..0000000000
--- a/packages/core/docs/content/locales/zh-TW/routing.mdx
+++ /dev/null
@@ -1,116 +0,0 @@
----
-title: "路由"
-description: "使用 React Router v8 為 Agent-Native 應用程式提供基於檔案的路由 - 頁面、動態參數和導覽。"
----
-
-# 路由
-
-Agent-Native 應用程式使用 **React Router v8** 以及透過來自 `@react-router/fs-routes` 的 `flatRoutes()` 的基於檔案的路由。 `app/routes/` 中的每個檔案都會變成 URL。範本使用點符號約定 - 點在單一檔名內分隔 URL 段。
-
-## 基於檔案的路由 {#file-based-routing}
-
-### 檔案→URL 對應
-
-| 檔案                  | URL                | 註解                          |
-| --------------------- | ------------------ | ----------------------------- |
-| `_index.tsx`          | `/`                | 索引路由                      |
-| `settings.tsx`        | `/settings`        | 簡單頁面                      |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | 點 = `/`，`$` = 動態參數      |
-| `_app.tsx`            | （無 URL 段）      | 無路徑布局 - 前綴為 `_`       |
-| `inbox/route.tsx`     | `/inbox`           | 資料夾形式——`route.tsx`為索引 |
-
-為動態參數新增 `$` 前綴。以 `_` 為前綴，使其成為無路徑布局路由（無 URL 段）。範本使用 `flatRoutes()` — 上面的點符號檔案是主要的；嵌套資料夾形式 `inbox/route.tsx` 也適用。
-
-<Diagram id="doc-block-oj35e8" title={"無路徑布局包裹頁面"} summary={"_app.tsx 布局（無 URL 段）渲染共用 shell 一次；匹配的頁面在其 <Outlet/> 內呈現，因此代理側邊欄永遠不會在導覽時重新安裝。"}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted">無路徑布局 · 持久外殼 + Agent 側邊欄</small>
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## 新增新頁面 {#adding-a-page}
-
-建立檔案並匯出預設元件：
-
-```tsx
-// app/routes/settings.tsx
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-就是這樣 - React 路由器會自動選取它，無需註冊。
-
-## 動態參數 {#dynamic-params}
-
-```tsx
-// app/routes/inbox/$threadId.tsx
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## 導覽 {#navigation}
-
-使用 `<Link>` 進行用戶端導覽，使用 `useNavigate()` 進行程式化導覽：
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## 下一步是什麼
-
-- [**Client**](/docs/client) - Agent-Native 瀏覽器掛鉤和實用程式
-- [**Server**](/docs/server) — 基於檔案的伺服器路由和 `/_agent-native/` 命名空間
diff --git a/packages/core/docs/content/notifications.mdx b/packages/core/docs/content/notifications.mdx
index 76a1db5088..0226aa6ce4 100644
--- a/packages/core/docs/content/notifications.mdx
+++ b/packages/core/docs/content/notifications.mdx
@@ -366,7 +366,7 @@ Automations can chain off this — e.g. _"if a critical notification fires, also
 ## How it works {#internals}
 
 - **Owner scoping** — every row has an `owner` column; every query filters on it; every route uses the authenticated session's email. Users never see each other's notifications.
-- **Poll integration** — every mutation calls `recordChange()` so templates using [`useDbSync`](/docs/client) auto-invalidate without any extra wiring.
+- **Poll integration** — every mutation calls `recordChange()` so templates using [`useDbSync`](/docs/client-data#usedbsync) auto-invalidate without any extra wiring.
 - **Best-effort fan-out** — channel errors are caught and logged; one failing channel does not block others or the inbox write.
 - **Fire-and-forget** — `notify()` returns after the inbox write completes; custom channels run in the background.
 
diff --git a/packages/core/docs/content/progress.mdx b/packages/core/docs/content/progress.mdx
index 892d72d285..13c253d69f 100644
--- a/packages/core/docs/content/progress.mdx
+++ b/packages/core/docs/content/progress.mdx
@@ -244,7 +244,7 @@ Notify me that run {{runId}} has failed.
 ## How it works {#internals}
 
 - **Owner scoping** — every row has an `owner` column; every query filters on it. Users see only their own runs.
-- **Poll integration** — every mutation calls `recordChange()` so templates using [`useDbSync`](/docs/client) auto-invalidate without any extra wiring.
+- **Poll integration** — every mutation calls `recordChange()` so templates using [`useDbSync`](/docs/client-data#usedbsync) auto-invalidate without any extra wiring.
 - **Table name** — the framework also has an `agent_runs` table for internal agent-chat turn lifecycle tracking. The progress primitive uses `progress_runs` to keep the two concerns separate.
 - **Percent clamping** — values are clamped to `[0, 100]` and rounded to an integer on write.
 
@@ -252,4 +252,4 @@ Notify me that run {{runId}} has failed.
 
 - [**Notifications**](/docs/notifications) — pair with `manage-progress` (`action=complete`) to tell the user when work finishes
 - [**Automations**](/docs/automations) — watchdog slow runs via `run.progress.updated`
-- [**Client**](/docs/client) — `useDbSync` for real-time cache invalidation
+- [**Data & Sync**](/docs/client-data) — `useDbSync` for real-time cache invalidation
diff --git a/packages/core/docs/content/real-time-collaboration.mdx b/packages/core/docs/content/real-time-collaboration.mdx
index 2c07a1fc54..66a07df55a 100644
--- a/packages/core/docs/content/real-time-collaboration.mdx
+++ b/packages/core/docs/content/real-time-collaboration.mdx
@@ -39,7 +39,7 @@ deployment environments including serverless and edge).
 
 <Callout tone="info">
 
-**Just need the UI to refresh, not character-level co-editing?** Use [`useDbSync`](/docs/client#usedbsync) instead — it's for reacting to SQL writes from the agent or other users. This page covers real-time character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
+**Just need the UI to refresh, not character-level co-editing?** Use [`useDbSync`](/docs/client-data#usedbsync) instead — it's for reacting to SQL writes from the agent or other users. This page covers real-time character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
 
 </Callout>
 
@@ -780,7 +780,7 @@ Key properties:
 
 ## What's next {#whats-next}
 
-- [Real-Time Sync](/docs/client#usedbsync) — the `useDbSync` + `useChangeVersion`
+- [Sync Internals](/docs/client-sync-internals) — the `useDbSync` + `useChangeVersion`
   system that delivers the `updatedAt` bump driving editor reconciliation.
 - [Security](/docs/security) — `registerShareableResource`, `resolveAccess`,
   and `assertAccess` for resource-scoped collaboration.
diff --git a/packages/core/docs/content/routing.mdx b/packages/core/docs/content/routing.mdx
deleted file mode 100644
index 6360c6104c..0000000000
--- a/packages/core/docs/content/routing.mdx
+++ /dev/null
@@ -1,117 +0,0 @@
----
-title: "Routing"
-description: "File-based routing for agent-native apps with React Router v8 — pages, dynamic params, and navigation."
----
-
-# Routing
-
-Agent-native apps use **React Router v8** with file-based routing via `flatRoutes()` from `@react-router/fs-routes`. Every file in `app/routes/` becomes a URL. Templates use the dot-notation convention — dots separate URL segments inside a single filename.
-
-## File-Based Routing {#file-based-routing}
-
-### File → URL mapping
-
-| File                  | URL                | Notes                                  |
-| --------------------- | ------------------ | -------------------------------------- |
-| `_index.tsx`          | `/`                | Index route                            |
-| `settings.tsx`        | `/settings`        | Simple page                            |
-| `inbox.$threadId.tsx` | `/inbox/:threadId` | Dot = `/`, `$` = dynamic param         |
-| `_app.tsx`            | (no URL segment)   | Pathless layout — prefix with `_`      |
-| `inbox/route.tsx`     | `/inbox`           | Folder form — `route.tsx` is the index |
-
-Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a pathless layout route (no URL segment). Templates use `flatRoutes()` — the dot-notation file above is primary; the nested-folder form `inbox/route.tsx` also works.
-
-<Diagram id="doc-block-19aa3pu" title="Pathless layout wraps the pages" summary={"A _app.tsx layout (no URL segment) renders the shared shell once; matched pages render inside its <Outlet/>, so the agent sidebar never remounts on navigation."}>
-
-```html
-<div class="diagram-layout" data-rough>
-  <div class="diagram-shell">
-    <span class="diagram-pill accent">_app.tsx</span
-    ><small class="diagram-muted"
-      >pathless layout · persistent shell + agent sidebar</small
-    >
-    <div class="diagram-outlet" data-rough>
-      <small class="diagram-muted">&lt;Outlet/&gt; — the matched page</small>
-      <div class="diagram-row">
-        <span class="diagram-pill">_index.tsx &rarr; /</span
-        ><span class="diagram-pill">settings.tsx &rarr; /settings</span
-        ><span class="diagram-pill"
-          >inbox.$threadId.tsx &rarr; /inbox/:threadId</span
-        >
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-```css
-.diagram-layout .diagram-shell {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 16px;
-}
-.diagram-layout .diagram-outlet {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
-  padding: 14px;
-  margin-top: 6px;
-}
-.diagram-layout .diagram-row {
-  display: flex;
-  flex-wrap: wrap;
-  gap: 8px;
-  margin-top: 4px;
-}
-```
-
-</Diagram>
-
-## Adding a new page {#adding-a-page}
-
-Create the file and export a default component:
-
-```tsx filename="app/routes/settings.tsx"
-export function meta() {
-  return [{ title: "Settings" }];
-}
-
-export default function SettingsPage() {
-  return <div>Settings</div>;
-}
-```
-
-That's it — React Router picks it up automatically, no registration needed.
-
-## Dynamic params {#dynamic-params}
-
-```tsx filename="app/routes/inbox.$threadId.tsx"
-import { useParams } from "react-router";
-
-export default function ThreadPage() {
-  const { threadId } = useParams();
-  return <div>Thread: {threadId}</div>;
-}
-```
-
-## Navigation {#navigation}
-
-Use `<Link>` for client-side navigation and `useNavigate()` for programmatic navigation:
-
-```tsx
-import { Link, useNavigate } from "react-router";
-
-// In JSX
-<Link to="/settings">Settings</Link>;
-
-// Programmatic
-const navigate = useNavigate();
-navigate(`/inbox/${threadId}`);
-```
-
-## What's next
-
-- [**Client**](/docs/client) — the agent-native browser hooks and utilities
-- [**Server**](/docs/server-overview) — file-based server routes and the `/_agent-native/` namespace
-- [**Context Awareness**](/docs/context-awareness) — how the agent learns the current route and selection
diff --git a/packages/core/docs/content/template-chat-developers.mdx b/packages/core/docs/content/template-chat-developers.mdx
index be70491bfb..01e02c6d53 100644
--- a/packages/core/docs/content/template-chat-developers.mdx
+++ b/packages/core/docs/content/template-chat-developers.mdx
@@ -11,7 +11,7 @@ This page is for developers who need to know what runs under the hood in [Chat](
 
 Chat adds no domain tables of its own (see [What's not in it](/docs/template-chat#not-in-it)). It runs entirely on the framework's core tables: chat threads and messages, `application_state`, `settings`, sessions, resources, and run history.
 
-`useDbSync()` is already wired into the app shell: when the agent (or anyone else) writes to SQL, the client receives the change over SSE, or the 2-second polling fallback, and invalidates the matching React Query caches — no manual refresh, no websocket you have to manage yourself. See [`useDbSync`](/docs/client#usedbsync) for the full hook API.
+`useDbSync()` is already wired into the app shell: when the agent (or anyone else) writes to SQL, the client receives the change over SSE, or the 2-second polling fallback, and invalidates the matching React Query caches — no manual refresh, no websocket you have to manage yourself. See [`useDbSync`](/docs/client-data#usedbsync) for the full hook API.
 
 `server/plugins/agent-chat.ts` is where the chat runtime itself is configured: it registers every action in `actions/` as a callable tool (`loadActionsFromStaticRegistry`), resolves the current org for scoping (`resolveOrgId`), sets the system prompt, and declares which tools the model sees on the very first turn (`initialToolNames`) — see [Your first feature in Chat](/docs/template-chat-first-edits#first-edits) for what that last part means when you add a new action.
 
diff --git a/packages/core/docs/content/toolkit-command-navigation.mdx b/packages/core/docs/content/toolkit-command-navigation.mdx
index faed487da1..414d8118df 100644
--- a/packages/core/docs/content/toolkit-command-navigation.mdx
+++ b/packages/core/docs/content/toolkit-command-navigation.mdx
@@ -104,7 +104,7 @@ Use a small predictable route set:
 
 ## What's next
 
-- [**Routing**](/docs/routing) — the file-route conventions the route standard
+- [**Routing**](/docs/client-routing) — the file-route conventions the route standard
   builds on.
 - [**Context Awareness**](/docs/context-awareness) — how `view-screen` and
   navigation state stay in sync.
diff --git a/packages/docs/app/components/docsNavItems.ts b/packages/docs/app/components/docsNavItems.ts
index 70210b1272..ca51baf0ae 100644
--- a/packages/docs/app/components/docsNavItems.ts
+++ b/packages/docs/app/components/docsNavItems.ts
@@ -116,57 +116,47 @@ const NAV_SECTION_CONFIG: NavSectionConfig[] = [
           },
         ],
       },
-      { id: "client", labelKey: "client", slug: "client" },
       {
         id: "client-section",
-        labelKey: "clientNext",
-        draft: true,
+        labelKey: "client",
         children: [
           {
             id: "client-overview",
             labelKey: "clientOverview",
             slug: "client-overview",
-            draft: true,
           },
           {
             id: "client-data",
             labelKey: "clientDataSync",
             slug: "client-data",
-            draft: true,
           },
           {
             id: "client-agent-chat",
             labelKey: "clientAgentChat",
             slug: "client-agent-chat",
-            draft: true,
           },
           {
             id: "client-routing",
             labelKey: "routing",
             slug: "client-routing",
-            draft: true,
           },
           {
             id: "client-advanced",
             labelKey: "clientAdvanced",
             slug: "client-advanced",
-            draft: true,
           },
           {
             id: "client-sync-internals",
             labelKey: "clientSyncInternals",
             slug: "client-sync-internals",
-            draft: true,
           },
           {
             id: "client-entry-points",
             labelKey: "clientEntryPoints",
             slug: "client-entry-points",
-            draft: true,
           },
         ],
       },
-      { id: "routing", labelKey: "routing", slug: "routing" },
       { id: "actions", labelKey: "actions", slug: "actions" },
       {
         id: "human-approval",
diff --git a/packages/docs/app/i18n/ar-SA.ts b/packages/docs/app/i18n/ar-SA.ts
index d0cdb8255b..2008f6cfb2 100644
--- a/packages/docs/app/i18n/ar-SA.ts
+++ b/packages/docs/app/i18n/ar-SA.ts
@@ -1515,7 +1515,6 @@ const arSA = {
     serverPlugins: "الإضافات",
     serverRoutes: "المسارات",
     client: "Client",
-    clientNext: "Client (جديد)",
     clientOverview: "نظرة عامة",
     clientDataSync: "البيانات والمزامنة",
     clientAgentChat: "محادثة الوكيل",
diff --git a/packages/docs/app/i18n/de-DE.ts b/packages/docs/app/i18n/de-DE.ts
index 767702ba6c..257d1764e3 100644
--- a/packages/docs/app/i18n/de-DE.ts
+++ b/packages/docs/app/i18n/de-DE.ts
@@ -1527,7 +1527,6 @@ const deDE = {
     serverPlugins: "Plugins",
     serverRoutes: "Routen",
     client: "Client",
-    clientNext: "Client (neu)",
     clientOverview: "Überblick",
     clientDataSync: "Daten & Synchronisierung",
     clientAgentChat: "Agent-Chat",
diff --git a/packages/docs/app/i18n/en-US.ts b/packages/docs/app/i18n/en-US.ts
index 2a77b6b21d..07e43f9503 100644
--- a/packages/docs/app/i18n/en-US.ts
+++ b/packages/docs/app/i18n/en-US.ts
@@ -1517,7 +1517,6 @@ const enUS = {
     serverPlugins: "Plugins",
     serverRoutes: "Routes",
     client: "Client",
-    clientNext: "Client (new)",
     clientOverview: "Overview",
     clientDataSync: "Data & Sync",
     clientAgentChat: "Agent Chat",
diff --git a/packages/docs/app/i18n/es-ES.ts b/packages/docs/app/i18n/es-ES.ts
index 535118ef69..2ae9564170 100644
--- a/packages/docs/app/i18n/es-ES.ts
+++ b/packages/docs/app/i18n/es-ES.ts
@@ -1527,7 +1527,6 @@ const esES = {
     serverPlugins: "Plugins",
     serverRoutes: "Rutas",
     client: "Cliente",
-    clientNext: "Cliente (nuevo)",
     clientOverview: "Resumen",
     clientDataSync: "Datos y sincronización",
     clientAgentChat: "Chat del Agent",
diff --git a/packages/docs/app/i18n/fr-FR.ts b/packages/docs/app/i18n/fr-FR.ts
index 10895e463c..14b82ec5ba 100644
--- a/packages/docs/app/i18n/fr-FR.ts
+++ b/packages/docs/app/i18n/fr-FR.ts
@@ -1528,7 +1528,6 @@ const frFR = {
     serverPlugins: "Plugins",
     serverRoutes: "Routes",
     client: "Client",
-    clientNext: "Client (nouveau)",
     clientOverview: "Vue d’ensemble",
     clientDataSync: "Données et synchronisation",
     clientAgentChat: "Chat de l’Agent",
diff --git a/packages/docs/app/i18n/hi-IN.ts b/packages/docs/app/i18n/hi-IN.ts
index 4d2339eb9b..42c7c2c597 100644
--- a/packages/docs/app/i18n/hi-IN.ts
+++ b/packages/docs/app/i18n/hi-IN.ts
@@ -1517,7 +1517,6 @@ const hiIN = {
     serverPlugins: "प्लगइन्स",
     serverRoutes: "रूट्स",
     client: "Client",
-    clientNext: "Client (नया)",
     clientOverview: "अवलोकन",
     clientDataSync: "डेटा और सिंक",
     clientAgentChat: "एजेंट चैट",
diff --git a/packages/docs/app/i18n/ja-JP.ts b/packages/docs/app/i18n/ja-JP.ts
index c03b9e92a5..351cc5ffcb 100644
--- a/packages/docs/app/i18n/ja-JP.ts
+++ b/packages/docs/app/i18n/ja-JP.ts
@@ -1524,7 +1524,6 @@ const jaJP = {
     serverPlugins: "プラグイン",
     serverRoutes: "ルート",
     client: "クライアント",
-    clientNext: "クライアント（新）",
     clientOverview: "概要",
     clientDataSync: "データと同期",
     clientAgentChat: "Agent チャット",
diff --git a/packages/docs/app/i18n/ko-KR.ts b/packages/docs/app/i18n/ko-KR.ts
index 39a2f62281..a27189d762 100644
--- a/packages/docs/app/i18n/ko-KR.ts
+++ b/packages/docs/app/i18n/ko-KR.ts
@@ -1520,7 +1520,6 @@ const koKR = {
     serverPlugins: "플러그인",
     serverRoutes: "라우트",
     client: "클라이언트",
-    clientNext: "클라이언트 (신규)",
     clientOverview: "개요",
     clientDataSync: "데이터 및 동기화",
     clientAgentChat: "Agent 채팅",
diff --git a/packages/docs/app/i18n/pt-BR.ts b/packages/docs/app/i18n/pt-BR.ts
index 44459c133b..eaaea0844d 100644
--- a/packages/docs/app/i18n/pt-BR.ts
+++ b/packages/docs/app/i18n/pt-BR.ts
@@ -1523,7 +1523,6 @@ const ptBR = {
     serverPlugins: "Plugins",
     serverRoutes: "Rotas",
     client: "Cliente",
-    clientNext: "Cliente (novo)",
     clientOverview: "Visão geral",
     clientDataSync: "Dados e sincronização",
     clientAgentChat: "Chat do Agent",
diff --git a/packages/docs/app/i18n/zh-CN.ts b/packages/docs/app/i18n/zh-CN.ts
index 01bca76cbd..5e458b20eb 100644
--- a/packages/docs/app/i18n/zh-CN.ts
+++ b/packages/docs/app/i18n/zh-CN.ts
@@ -1499,7 +1499,6 @@ const zhCN = {
     serverPlugins: "插件",
     serverRoutes: "路由",
     client: "客户端",
-    clientNext: "客户端（新）",
     clientOverview: "概览",
     clientDataSync: "数据与同步",
     clientAgentChat: "Agent 聊天",
diff --git a/packages/docs/app/i18n/zh-TW.ts b/packages/docs/app/i18n/zh-TW.ts
index e70f9914ce..af184e8e79 100644
--- a/packages/docs/app/i18n/zh-TW.ts
+++ b/packages/docs/app/i18n/zh-TW.ts
@@ -1497,7 +1497,6 @@ const messages = {
     serverPlugins: "外掛",
     serverRoutes: "路由",
     client: "用戶端",
-    clientNext: "用戶端（新）",
     clientOverview: "總覽",
     clientDataSync: "資料與同步",
     clientAgentChat: "Agent 聊天",
diff --git a/packages/docs/app/routes/docs.$locale.$slug.tsx b/packages/docs/app/routes/docs.$locale.$slug.tsx
index 5406daaf50..56af721a4a 100644
--- a/packages/docs/app/routes/docs.$locale.$slug.tsx
+++ b/packages/docs/app/routes/docs.$locale.$slug.tsx
@@ -39,6 +39,11 @@ const SLUG_REDIRECTS: Record<string, string> = {
   // server.mdx split into the Server section (server-overview, -database,
   // -middleware, -plugins, -routes).
   server: "server-overview",
+  // client.mdx split into the Client section (client-overview, -data,
+  // -agent-chat, -routing, -advanced, -sync-internals, -entry-points).
+  client: "client-overview",
+  // routing.mdx superseded by the Client section's own routing page.
+  routing: "client-routing",
 };
 
 function requireLocale(value: unknown): DocsLocale {
diff --git a/packages/docs/app/routes/docs.$slug.tsx b/packages/docs/app/routes/docs.$slug.tsx
index 45fbaf13e0..7a53a4be66 100644
--- a/packages/docs/app/routes/docs.$slug.tsx
+++ b/packages/docs/app/routes/docs.$slug.tsx
@@ -34,6 +34,11 @@ const SLUG_REDIRECTS: Record<string, string> = {
   // server.mdx split into the Server section (server-overview, -database,
   // -middleware, -plugins, -routes).
   server: "server-overview",
+  // client.mdx split into the Client section (client-overview, -data,
+  // -agent-chat, -routing, -advanced, -sync-internals, -entry-points).
+  client: "client-overview",
+  // routing.mdx superseded by the Client section's own routing page.
+  routing: "client-routing",
 };
 
 export async function loader({ params }: LoaderFunctionArgs) {

From f356e58591258a44e7b22f4773570b7e6194b0a0 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 16:08:54 -0700
Subject: [PATCH 13/22] docs: clear guard:i18n-catalogs findings on new Client
 docs blocks

Adds the code filename "dashboard_.$ticketId.tsx" to the no-translate-terms
list so all 10 client-routing.mdx locales stop being flagged for leaving a
literal identifier untranslated. Records the Image/Signature/media-layout
blocks' English-only description, aria-label, and placeholder text in the
raw-literal baseline, matching how sibling blocks (steps, cards, notice,
banner) already record the same category of block-internal chrome text.
---
 scripts/i18n-no-translate-terms.txt   | 1 +
 scripts/i18n-raw-literal-baseline.txt | 5 +++++
 2 files changed, 6 insertions(+)

diff --git a/scripts/i18n-no-translate-terms.txt b/scripts/i18n-no-translate-terms.txt
index 6c7336f785..6b61cfb5d7 100644
--- a/scripts/i18n-no-translate-terms.txt
+++ b/scripts/i18n-no-translate-terms.txt
@@ -39,6 +39,7 @@ create-form · update-form
 createSession.resumeState
 CRUD
 Cursor · Codex
+dashboard_.$ticketId.tsx
 dbQuery / dbExec
 Dispatch hub
 GET /api/auth/user
diff --git a/scripts/i18n-raw-literal-baseline.txt b/scripts/i18n-raw-literal-baseline.txt
index 7cf0a0f9f6..4ad25d7c38 100644
--- a/scripts/i18n-raw-literal-baseline.txt
+++ b/scripts/i18n-raw-literal-baseline.txt
@@ -5,7 +5,12 @@ packages/docs/app/components/blocks/badge.tsx|A small status/label chip for the
 packages/docs/app/components/blocks/banner.tsx|A compact, full-width, single-line announcement strip for the top of a page or section — beta, deprecated, moved. Tones: info, decision, risk, warning, success.
 packages/docs/app/components/blocks/cards.tsx|Feature name
 packages/docs/app/components/blocks/comparison.tsx|A side-by-side comparison of two to four options, e.g. Before/After or Option A/Option B.
+packages/docs/app/components/blocks/image.tsx|An image, full width or aligned left/right with paired markdown text, an optional caption, and a hover-to-expand popup.
+packages/docs/app/components/blocks/media-layout.tsx|Close preview
+packages/docs/app/components/blocks/media-layout.tsx|Media preview
 packages/docs/app/components/blocks/notice.tsx|A bold, filled alert card with an icon and optional title, for something a reader must not skim past. Tones: info, decision, risk, warning, success.
+packages/docs/app/components/blocks/signature.tsx|Describe the parameter.
+packages/docs/app/components/blocks/signature.tsx|Function signature
 packages/docs/app/components/blocks/steps.tsx|A numbered step-by-step procedure with circled step numbers.
 packages/docs/app/components/blocks/steps.tsx|Step title
 packages/docs/app/components/docBlocks.tsx|| Extract

From a5a3ee4d824118cedcca6adf5f2291a125c0e5fa Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 16:13:45 -0700
Subject: [PATCH 14/22] docs: add writing-reference-docs skill

Captures the reference-doc shape that emerged from rewriting client-data.mdx's
hook sections: plain-language purpose, real argument list, escalating
examples grounded in a real app, and a short closing behavior note. Dev-only
scope so it guides future reference-page edits without shipping to the
runtime agent.
---
 .../skills/writing-reference-docs/SKILL.md    | 110 ++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 .agents/skills/writing-reference-docs/SKILL.md

diff --git a/.agents/skills/writing-reference-docs/SKILL.md b/.agents/skills/writing-reference-docs/SKILL.md
new file mode 100644
index 0000000000..07dbcb49c3
--- /dev/null
+++ b/.agents/skills/writing-reference-docs/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: writing-reference-docs
+description: >-
+  How to write a function/hook/action reference section: plain-language
+  signature, real arguments, escalating examples grounded in a real app,
+  trimmed prose with no em dashes or semicolons. Use when writing or editing a
+  packages/core/docs/content reference page.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Writing Reference Docs
+
+This came out of rewriting `client-data.mdx`'s hook sections
+(`useActionQuery`, `useActionMutation`, `callAction`, `useDbSync`) section by
+section with the user. It captures the shape that emerged so the next
+reference section starts from it instead of reinventing it.
+
+## Rule
+
+Document each function, hook, or action reference as: a plain-language
+purpose statement, a bulleted argument list matching the real signature, two
+or more escalating runnable examples grounded in a real app, and a one or two
+sentence closing behavior note. Never a bare one-line description with a
+single toy snippet.
+
+## Why
+
+The original `client-data.mdx` gave each hook one sentence and one minimal
+snippet with no options argument shown at all. That hid real, common needs
+(conditional fetching via `enabled`, a post-mutation side effect via
+`onSuccess`) that readers would only discover by reading the source. It also
+leaned on a hypothetical `leads` domain (`get-lead`, `create-lead`,
+`archive-lead`) that reads as unconvincing next to an example grounded in a
+real app with a real schema and real access rules.
+
+## How
+
+1. **Match heading level to role.** Hooks that solve the same kind of problem
+   get grouped under one parent heading (e.g. `### Action hooks`) with each
+   hook as a child heading below it. A utility that is not a hook (like
+   `callAction`) is a sibling heading at the same level as the group, not a
+   child of it, even if it lives right next to the group.
+2. **Open with plain-language purpose, then link out.** State what the
+   function is for in one or two sentences ("This hook is intended to be used
+   for..."). If it wraps another library's hook (React Query's `useQuery`,
+   `useMutation`), link its reference page instead of re-documenting fields
+   you don't own.
+3. **List real arguments as a short bullet list**, matching the actual
+   exported signature in `packages/core/src/client/`, not a paraphrase. Read
+   the source before writing the list. Skip the bullet-list format entirely
+   for a function that takes only one argument. Fold that into a sentence
+   instead:
+
+   ```md
+   `useActionQuery()` accepts three arguments:
+
+   - **actionName**: the action's registered name.
+   - **params**: the action's input, typed from its `defineAction()` schema.
+   - **options**: everything from the [useQuery options](...) except
+     `queryKey` and `queryFn`, which the hook sets itself.
+   ```
+
+4. **Give two or more escalating examples.** The first is the simplest
+   possible call. The second demonstrates one real, common option (a
+   conditional fetch, a success callback, a longer timeout), with one
+   sentence before it explaining what's different and why it matters.
+5. **Ground every example in a real reference app's real action**, not an
+   invented one, e.g. `get-ticket`, `send-ticket-reply`, `update-ticket` from
+   a real ticket-support example app, rather than `get-lead`/`create-lead`.
+   Exception: if the page already threads a hypothetical domain across
+   multiple sibling pages (a running example), keep using that domain in this
+   page too. Enrich its snippets with the missing option; don't swap the
+   domain out from under the other pages.
+6. **Close with the one behavior fact a reader needs**, in one or two
+   sentences: cache key, invalidation trigger, timeout.
+7. **Prose rules, every sentence:** no em dashes, no semicolons (this
+   includes table cells), short sentences. Split into two sentences instead
+   of joining with either. Reference every function by name with parens,
+   `useActionQuery()` not `useActionQuery`.
+8. **Example values must mean something to a reader with zero app context.**
+   Don't reuse an in-app sentinel value (like a `"me"` string a real action
+   resolves specially) without explaining it. Use a literal, self-explanatory
+   value instead, like a real-looking email address.
+
+## Don't
+
+- Don't introduce a new framework concept into the primary example just
+  because it's technically correct for that hook. If most readers of this
+  page will never need to write it themselves (e.g. wiring `ignoreSource` with
+  a per-tab id), it belongs in the options table, not the main example, or on
+  a deeper page like Advanced.
+- Don't swap a page's running example domain without checking whether sibling
+  pages share it. Grep the other draft pages for the same domain terms first.
+- Don't leave a semicolon or em dash anywhere in the page, including table
+  cells. Split into two sentences.
+- Don't add a one-item options bullet list for a function that only takes a
+  single argument. State it in a sentence instead.
+- Don't paraphrase a signature from memory. Grep the actual export in
+  `packages/core/src/client/` and read its real parameter and option types.
+
+## Related Skills
+
+- **writing-agent-instructions** — the sibling guide for AGENTS.md/SKILL.md
+  prose, which this borrows its "say it once, plainly" spirit from.
+- **agent-native-docs** — how to look up the version-matched docs this skill
+  helps you write.
+- **internationalization** — localized copies under `content/locales/*` need
+  the same edit when a source doc's meaning changes (see CLAUDE.md).

From 8eba6d8fa9a5081fc8e7b03e151f922e0ec4ae71 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Mon, 10 Aug 2026 17:27:10 -0700
Subject: [PATCH 15/22] fix: docs build-blocking CSS brace and locale-aware
 navigation

Removes a stray extra closing brace in global.css left over from the merge
resolution, which broke the production CSS build. Threads a locale param
through the markdown/block render pipeline (MarkdownRenderer, DocContent,
DocBlocksContent, docBlocks) so links written as plain /docs/x in a
localized page's body rewrite to /{locale}/docs/x instead of dropping the
reader out of their active locale. Replaces the ASCII-only heading-slug
regex (duplicated in three places) with a shared Unicode-aware slugifier so
non-Latin headings (Chinese, Japanese, Korean, Arabic, Devanagari) get a
real anchor id instead of an empty one, fixing both the rendered heading id
and the sidebar/search TOC. Also fixes a dangling shadcn/ui link in the
Overview page (English + all 10 locales) that pointed at a slug that never
existed; the real page is /docs/toolkit-ui.
---
 .../core/docs/content/client-overview.mdx     |  2 +-
 .../content/locales/ar-SA/client-overview.mdx |  2 +-
 .../content/locales/de-DE/client-overview.mdx |  2 +-
 .../content/locales/es-ES/client-overview.mdx |  2 +-
 .../content/locales/fr-FR/client-overview.mdx |  2 +-
 .../content/locales/hi-IN/client-overview.mdx |  2 +-
 .../content/locales/ja-JP/client-overview.mdx |  2 +-
 .../content/locales/ko-KR/client-overview.mdx |  2 +-
 .../content/locales/pt-BR/client-overview.mdx |  2 +-
 .../content/locales/zh-CN/client-overview.mdx |  2 +-
 .../content/locales/zh-TW/client-overview.mdx |  2 +-
 .../docs/app/components/DocBlocksContent.tsx  | 15 +++++--
 packages/docs/app/components/DocContent.tsx   | 17 ++++---
 .../docs/app/components/MarkdownRenderer.tsx  | 44 ++++++++++++-------
 .../docs/app/components/doc-block-renderer.ts |  7 ++-
 packages/docs/app/components/docBlocks.tsx    | 36 +++++++++++----
 packages/docs/app/components/docs-content.ts  | 15 ++-----
 packages/docs/app/components/docs-locale.ts   | 19 ++++++++
 packages/docs/app/components/heading-slug.ts  | 18 ++++++++
 packages/docs/app/global.css                  |  3 --
 .../docs/app/routes/docs.$locale.$slug.tsx    |  2 +-
 21 files changed, 139 insertions(+), 59 deletions(-)
 create mode 100644 packages/docs/app/components/heading-slug.ts

diff --git a/packages/core/docs/content/client-overview.mdx b/packages/core/docs/content/client-overview.mdx
index e6e071210f..4375326dd0 100644
--- a/packages/core/docs/content/client-overview.mdx
+++ b/packages/core/docs/content/client-overview.mdx
@@ -111,7 +111,7 @@ This page covers the directories you build in and the pieces of the browser runt
 | **`app/root.tsx`**                                  | The HTML shell and provider stack — see [The Browser Shell](#app-shell) below                                     |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration and SSR bootstrap — see [Entry Points](/docs/client-entry-points)                                       |
 | **`app/routes.ts` + `app/routes/`**                 | File-based pages and navigation — see [Routing](/docs/client-routing)                                             |
-| **`app/components/`**                               | Your UI: shadcn-style primitives plus app-specific components — see [shadcn/ui](/docs/shadcn-ui)                  |
+| **`app/components/`**                               | Your UI: shadcn-style primitives plus app-specific components — see [Toolkit UI Primitives](/docs/toolkit-ui)     |
 | **`app/hooks/`**                                    | Data, sync, and agent-chat hooks — see [Data & Sync](/docs/client-data) and [Agent Chat](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | Shared client utilities (app config, tab id, `cn`) — see [Utilities](#utilities) below                            |
 | **`app/design-system.ts`**                          | Optional custom design system adapter — see [Custom Design Systems](/docs/custom-design-system)                   |
diff --git a/packages/core/docs/content/locales/ar-SA/client-overview.mdx b/packages/core/docs/content/locales/ar-SA/client-overview.mdx
index 03ecbd6664..52738a61dc 100644
--- a/packages/core/docs/content/locales/ar-SA/client-overview.mdx
+++ b/packages/core/docs/content/locales/ar-SA/client-overview.mdx
@@ -111,7 +111,7 @@ description: "دليلا `app/` و`public/`: حيث تبني عرض تطبيق 
 | **`app/root.tsx`**                                  | غلاف HTML ومجموعة الموفرات (providers) - راجع [غلاف المتصفح](#app-shell) أدناه                                                      |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | إقلاع الترطيب (hydration) وSSR - راجع [نقاط الدخول](/docs/client-entry-points)                                                      |
 | **`app/routes.ts` + `app/routes/`**                 | الصفحات المستندة إلى الملفات والتنقل - راجع [التوجيه](/docs/client-routing)                                                         |
-| **`app/components/`**                               | واجهة المستخدم الخاصة بك: عناصر أساسية بأسلوب shadcn بالإضافة إلى مكونات خاصة بالتطبيق - راجع [shadcn/ui](/docs/shadcn-ui)          |
+| **`app/components/`**                               | واجهة المستخدم الخاصة بك: عناصر أساسية بأسلوب shadcn بالإضافة إلى مكونات خاصة بالتطبيق - راجع [shadcn/ui](/docs/toolkit-ui)         |
 | **`app/hooks/`**                                    | خطافات البيانات، والمزامنة، ومحادثة الوكيل - راجع [البيانات والمزامنة](/docs/client-data) و[محادثة الوكيل](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | أدوات مساعدة مشتركة للعميل (تكوين التطبيق، معرف اللسان (tab id)، `cn`) - راجع [الأدوات المساعدة](#utilities) أدناه                  |
 | **`app/design-system.ts`**                          | محول نظام تصميم مخصص اختياري - راجع [أنظمة التصميم المخصصة](/docs/custom-design-system)                                             |
diff --git a/packages/core/docs/content/locales/de-DE/client-overview.mdx b/packages/core/docs/content/locales/de-DE/client-overview.mdx
index 5d67c8b7e4..50ed715d7e 100644
--- a/packages/core/docs/content/locales/de-DE/client-overview.mdx
+++ b/packages/core/docs/content/locales/de-DE/client-overview.mdx
@@ -113,7 +113,7 @@ Diese Seite behandelt die Verzeichnisse, in denen Sie bauen, und die Teile der B
 | **`app/root.tsx`**                                  | Die HTML-Hülle und der Provider-Stack – siehe [Die Browser-Hülle](#app-shell) unten                                    |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration und SSR-Bootstrap – siehe [Einstiegspunkte](/docs/client-entry-points)                                       |
 | **`app/routes.ts` + `app/routes/`**                 | Dateibasierte Seiten und Navigation – siehe [Routing](/docs/client-routing)                                            |
-| **`app/components/`**                               | Ihre UI: shadcn-artige Primitive plus app-spezifische Komponenten – siehe [shadcn/ui](/docs/shadcn-ui)                 |
+| **`app/components/`**                               | Ihre UI: shadcn-artige Primitive plus app-spezifische Komponenten – siehe [shadcn/ui](/docs/toolkit-ui)                |
 | **`app/hooks/`**                                    | Daten-, Sync- und Agent-Chat-Hooks – siehe [Daten & Sync](/docs/client-data) und [Agent Chat](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | Gemeinsame Client-Utilities (App-Konfiguration, Tab-Id, `cn`) – siehe [Utilities](#utilities) unten                    |
 | **`app/design-system.ts`**                          | Optionaler benutzerdefinierter Design-System-Adapter – siehe [Custom Design Systems](/docs/custom-design-system)       |
diff --git a/packages/core/docs/content/locales/es-ES/client-overview.mdx b/packages/core/docs/content/locales/es-ES/client-overview.mdx
index 6df10c8264..30bbb711d7 100644
--- a/packages/core/docs/content/locales/es-ES/client-overview.mdx
+++ b/packages/core/docs/content/locales/es-ES/client-overview.mdx
@@ -111,7 +111,7 @@ Esta página cubre los directorios en los que trabajas y las piezas del runtime
 | **`app/root.tsx`**                                  | El shell HTML y la pila de providers — consulta [El shell del navegador](#app-shell) más abajo                                                      |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hidratación y arranque de SSR — consulta [Puntos de entrada](/docs/client-entry-points)                                                             |
 | **`app/routes.ts` + `app/routes/`**                 | Páginas basadas en archivos y navegación — consulta [Enrutamiento](/docs/client-routing)                                                            |
-| **`app/components/`**                               | Tu UI: primitivos de estilo shadcn más componentes específicos de la app — consulta [shadcn/ui](/docs/shadcn-ui)                                    |
+| **`app/components/`**                               | Tu UI: primitivos de estilo shadcn más componentes específicos de la app — consulta [shadcn/ui](/docs/toolkit-ui)                                   |
 | **`app/hooks/`**                                    | Hooks de datos, sincronización y chat del agente — consulta [Datos y sincronización](/docs/client-data) y [Chat del Agent](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | Utilidades compartidas del cliente (configuración de la app, id de pestaña, `cn`) — consulta [Utilidades](#utilities) más abajo                     |
 | **`app/design-system.ts`**                          | Adaptador opcional de sistema de diseño personalizado — consulta [Sistemas de diseño personalizados](/docs/custom-design-system)                    |
diff --git a/packages/core/docs/content/locales/fr-FR/client-overview.mdx b/packages/core/docs/content/locales/fr-FR/client-overview.mdx
index 3543c0a1e4..2d6054cd66 100644
--- a/packages/core/docs/content/locales/fr-FR/client-overview.mdx
+++ b/packages/core/docs/content/locales/fr-FR/client-overview.mdx
@@ -111,7 +111,7 @@ Cette page couvre les répertoires dans lesquels vous construisez et les éléme
 | **`app/root.tsx`**                                  | Le shell HTML et la pile de providers — voir [Le shell du navigateur](#app-shell) ci-dessous                                                               |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | Bootstrap d'hydratation et SSR — voir [Points d'entrée](/docs/client-entry-points)                                                                         |
 | **`app/routes.ts` + `app/routes/`**                 | Pages basées sur des fichiers et navigation — voir [Routage](/docs/client-routing)                                                                         |
-| **`app/components/`**                               | Votre UI : primitives de style shadcn plus des composants spécifiques à l'application — voir [shadcn/ui](/docs/shadcn-ui)                                  |
+| **`app/components/`**                               | Votre UI : primitives de style shadcn plus des composants spécifiques à l'application — voir [shadcn/ui](/docs/toolkit-ui)                                 |
 | **`app/hooks/`**                                    | Hooks de données, de synchronisation et de chat agent — voir [Données et synchronisation](/docs/client-data) et [Chat de l’Agent](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | Utilitaires client partagés (config de l'application, id d'onglet, `cn`) — voir [Utilitaires](#utilities) ci-dessous                                       |
 | **`app/design-system.ts`**                          | Adaptateur de système de design personnalisé facultatif — voir [Systèmes de conception personnalisés](/docs/custom-design-system)                          |
diff --git a/packages/core/docs/content/locales/hi-IN/client-overview.mdx b/packages/core/docs/content/locales/hi-IN/client-overview.mdx
index ee7bdda082..58562fcc4d 100644
--- a/packages/core/docs/content/locales/hi-IN/client-overview.mdx
+++ b/packages/core/docs/content/locales/hi-IN/client-overview.mdx
@@ -111,7 +111,7 @@ description: "app/ और public/ डायरेक्टरी: जहां 
 | **`app/root.tsx`**                                  | HTML शेल और प्रोवाइडर स्टैक - नीचे [ब्राउज़र शेल](#app-shell) देखें                                            |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | हाइड्रेशन और SSR बूटस्ट्रैप - [एंट्री पॉइंट्स](/docs/client-entry-points) देखें                                |
 | **`app/routes.ts` + `app/routes/`**                 | फ़ाइल-आधारित पेज और नेविगेशन - [रूटिंग](/docs/client-routing) देखें                                            |
-| **`app/components/`**                               | आपका UI: shadcn-स्टाइल प्रिमिटिव प्लस ऐप-विशिष्ट घटक - [shadcn/ui](/docs/shadcn-ui) देखें                      |
+| **`app/components/`**                               | आपका UI: shadcn-स्टाइल प्रिमिटिव प्लस ऐप-विशिष्ट घटक - [shadcn/ui](/docs/toolkit-ui) देखें                     |
 | **`app/hooks/`**                                    | डेटा, सिंक, और एजेंट-चैट हुक - [डेटा और सिंक](/docs/client-data) और [एजेंट चैट](/docs/client-agent-chat) देखें |
 | **`app/lib/`**                                      | साझा क्लाइंट यूटिलिटीज़ (ऐप कॉन्फिग, टैब आईडी, `cn`) - नीचे [यूटिलिटीज़](#utilities) देखें                     |
 | **`app/design-system.ts`**                          | वैकल्पिक कस्टम डिज़ाइन सिस्टम एडाप्टर - [कस्टम डिज़ाइन सिस्टम](/docs/custom-design-system) देखें               |
diff --git a/packages/core/docs/content/locales/ja-JP/client-overview.mdx b/packages/core/docs/content/locales/ja-JP/client-overview.mdx
index 0fe2566051..f5941a64c4 100644
--- a/packages/core/docs/content/locales/ja-JP/client-overview.mdx
+++ b/packages/core/docs/content/locales/ja-JP/client-overview.mdx
@@ -111,7 +111,7 @@ description: "app/ と public/ ディレクトリ: agent-native アプリの表
 | **`app/root.tsx`**                                  | HTML シェルとプロバイダー スタック — 下記の [ブラウザ シェル](#app-shell) を参照                                                    |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | ハイドレーションと SSR のブートストラップ — [エントリーポイント](/docs/client-entry-points) を参照                                  |
 | **`app/routes.ts` + `app/routes/`**                 | ファイルベースのページとナビゲーション — [Routing](/docs/client-routing) を参照                                                     |
-| **`app/components/`**                               | 自分の UI: shadcn スタイルのプリミティブとアプリ固有のコンポーネント — [shadcn/ui](/docs/shadcn-ui) を参照                          |
+| **`app/components/`**                               | 自分の UI: shadcn スタイルのプリミティブとアプリ固有のコンポーネント — [shadcn/ui](/docs/toolkit-ui) を参照                         |
 | **`app/hooks/`**                                    | データ、同期、エージェント チャットのフック — [データと同期](/docs/client-data) と [Agent チャット](/docs/client-agent-chat) を参照 |
 | **`app/lib/`**                                      | 共有クライアント ユーティリティ (アプリ設定、タブ id、`cn`) — 下記の [ユーティリティ](#utilities) を参照                            |
 | **`app/design-system.ts`**                          | オプションのカスタム デザイン システム アダプター — [カスタム デザイン システム](/docs/custom-design-system) を参照                 |
diff --git a/packages/core/docs/content/locales/ko-KR/client-overview.mdx b/packages/core/docs/content/locales/ko-KR/client-overview.mdx
index c9e46f5651..dc7627d9ec 100644
--- a/packages/core/docs/content/locales/ko-KR/client-overview.mdx
+++ b/packages/core/docs/content/locales/ko-KR/client-overview.mdx
@@ -111,7 +111,7 @@ description: "app/ 및 public/ 디렉터리: 에이전트 네이티브 앱의 
 | **`app/root.tsx`**                                  | HTML 셸과 provider 스택 — 아래 [브라우저 셸](#app-shell) 참조                                                            |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | 하이드레이션 및 SSR 부트스트랩 — [엔트리 포인트](/docs/client-entry-points) 참조                                         |
 | **`app/routes.ts` + `app/routes/`**                 | 파일 기반 페이지와 내비게이션 — [Routing](/docs/client-routing) 참조                                                     |
-| **`app/components/`**                               | 여러분의 UI: shadcn 스타일 프리미티브와 앱 전용 컴포넌트 — [shadcn/ui](/docs/shadcn-ui) 참조                             |
+| **`app/components/`**                               | 여러분의 UI: shadcn 스타일 프리미티브와 앱 전용 컴포넌트 — [shadcn/ui](/docs/toolkit-ui) 참조                            |
 | **`app/hooks/`**                                    | 데이터, 동기화, 에이전트 채팅 후크 — [데이터 및 동기화](/docs/client-data) 및 [Agent 채팅](/docs/client-agent-chat) 참조 |
 | **`app/lib/`**                                      | 공유 클라이언트 유틸리티(앱 구성, 탭 id, `cn`) — 아래 [유틸리티](#utilities) 참조                                        |
 | **`app/design-system.ts`**                          | 선택적 커스텀 디자인 시스템 어댑터 — [커스텀 디자인 시스템](/docs/custom-design-system) 참조                             |
diff --git a/packages/core/docs/content/locales/pt-BR/client-overview.mdx b/packages/core/docs/content/locales/pt-BR/client-overview.mdx
index 850fc4a176..25050e6b8a 100644
--- a/packages/core/docs/content/locales/pt-BR/client-overview.mdx
+++ b/packages/core/docs/content/locales/pt-BR/client-overview.mdx
@@ -111,7 +111,7 @@ Esta página cobre os diretórios em que você constrói e as partes do runtime
 | **`app/root.tsx`**                                  | O shell HTML e a pilha de provedores — veja [O Shell do Navegador](#app-shell) abaixo                                                         |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | Bootstrap de hidratação e SSR — veja [Pontos de entrada](/docs/client-entry-points)                                                           |
 | **`app/routes.ts` + `app/routes/`**                 | Páginas baseadas em arquivo e navegação — veja [Roteamento](/docs/client-routing)                                                             |
-| **`app/components/`**                               | Sua UI: primitivas no estilo shadcn mais componentes específicos do aplicativo — veja [shadcn/ui](/docs/shadcn-ui)                            |
+| **`app/components/`**                               | Sua UI: primitivas no estilo shadcn mais componentes específicos do aplicativo — veja [shadcn/ui](/docs/toolkit-ui)                           |
 | **`app/hooks/`**                                    | Ganchos de dados, sincronização e chat do agente — veja [Dados e sincronização](/docs/client-data) e [Chat do Agent](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | Utilitários de cliente compartilhados (config do app, id da aba, `cn`) — veja [Utilitários](#utilities) abaixo                                |
 | **`app/design-system.ts`**                          | Adaptador opcional de sistema de design personalizado — veja [Sistemas de design personalizados](/docs/custom-design-system)                  |
diff --git a/packages/core/docs/content/locales/zh-CN/client-overview.mdx b/packages/core/docs/content/locales/zh-CN/client-overview.mdx
index 7fcd01728a..6bd498ecc9 100644
--- a/packages/core/docs/content/locales/zh-CN/client-overview.mdx
+++ b/packages/core/docs/content/locales/zh-CN/client-overview.mdx
@@ -111,7 +111,7 @@ description: "app/ 和 public/ 目录：您在其中构建代理本机应用程
 | **`app/root.tsx`**                                  | HTML 外壳与 provider 栈——见下方 [浏览器外壳](#app-shell)                                              |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | Hydration 与 SSR 引导——见 [入口点](/docs/client-entry-points)                                         |
 | **`app/routes.ts` + `app/routes/`**                 | 基于文件的页面与导航——见 [路由](/docs/client-routing)                                                 |
-| **`app/components/`**                               | 您的 UI：shadcn 风格的基础组件加上应用专属组件——见 [shadcn/ui](/docs/shadcn-ui)                       |
+| **`app/components/`**                               | 您的 UI：shadcn 风格的基础组件加上应用专属组件——见 [shadcn/ui](/docs/toolkit-ui)                      |
 | **`app/hooks/`**                                    | 数据、同步和代理聊天钩子——见 [数据与同步](/docs/client-data) 和 [Agent 聊天](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | 共享客户端工具（应用配置、tab id、`cn`）——见下方 [工具函数](#utilities)                               |
 | **`app/design-system.ts`**                          | 可选的自定义设计系统适配器——见 [自定义设计系统](/docs/custom-design-system)                           |
diff --git a/packages/core/docs/content/locales/zh-TW/client-overview.mdx b/packages/core/docs/content/locales/zh-TW/client-overview.mdx
index a50573c3a0..3ee1b4023b 100644
--- a/packages/core/docs/content/locales/zh-TW/client-overview.mdx
+++ b/packages/core/docs/content/locales/zh-TW/client-overview.mdx
@@ -111,7 +111,7 @@ description: "app/ 與 public/ 目錄：您在此建置 agent-native 應用程
 | **`app/root.tsx`**                                  | HTML 外殼與提供者堆疊 — 請參閱下方[瀏覽器外殼](#app-shell)                                              |
 | **`app/entry.client.tsx` / `app/entry.server.tsx`** | 水合與 SSR 啟動 — 請參閱[入口點](/docs/client-entry-points)                                             |
 | **`app/routes.ts` + `app/routes/`**                 | 基於檔案的頁面與導覽 — 請參閱[路由](/docs/client-routing)                                               |
-| **`app/components/`**                               | 您的 UI：shadcn 風格的基礎元件與應用專屬元件 — 請參閱[shadcn/ui](/docs/shadcn-ui)                       |
+| **`app/components/`**                               | 您的 UI：shadcn 風格的基礎元件與應用專屬元件 — 請參閱[shadcn/ui](/docs/toolkit-ui)                      |
 | **`app/hooks/`**                                    | 資料、同步與代理聊天掛鉤 — 請參閱[資料與同步](/docs/client-data)與[Agent 聊天](/docs/client-agent-chat) |
 | **`app/lib/`**                                      | 共用的用戶端工具（應用設定、分頁 id、`cn`）— 請參閱下方[實用工具](#utilities)                           |
 | **`app/design-system.ts`**                          | 選用的自訂設計系統適配器 — 請參閱[自訂設計系統](/docs/custom-design-system)                             |
diff --git a/packages/docs/app/components/DocBlocksContent.tsx b/packages/docs/app/components/DocBlocksContent.tsx
index 575ca1d6d0..d36e1b3dee 100644
--- a/packages/docs/app/components/DocBlocksContent.tsx
+++ b/packages/docs/app/components/DocBlocksContent.tsx
@@ -2,20 +2,29 @@ import { useMemo } from "react";
 
 import { splitDocSegments } from "../../lib/doc-block-segments";
 import { DocBlock, DocBlocksProvider } from "./docBlocks";
+import { DEFAULT_DOCS_LOCALE, type DocsLocale } from "./docs-locale";
 import MarkdownRenderer from "./MarkdownRenderer";
 
 interface Props {
   markdown: string;
+  locale?: DocsLocale;
 }
 
-export default function DocBlocksContent({ markdown }: Props) {
+export default function DocBlocksContent({
+  markdown,
+  locale = DEFAULT_DOCS_LOCALE,
+}: Props) {
   const segments = useMemo(() => splitDocSegments(markdown), [markdown]);
 
   return (
-    <DocBlocksProvider>
+    <DocBlocksProvider locale={locale}>
       {segments.map((segment, index) =>
         segment.kind === "markdown" ? (
-          <MarkdownRenderer key={index} markdown={segment.text} />
+          <MarkdownRenderer
+            key={index}
+            markdown={segment.text}
+            locale={locale}
+          />
         ) : (
           <div key={index} className="docs-block">
             <DocBlock segment={segment} index={index} />
diff --git a/packages/docs/app/components/DocContent.tsx b/packages/docs/app/components/DocContent.tsx
index 397af2bcc3..d06116e126 100644
--- a/packages/docs/app/components/DocContent.tsx
+++ b/packages/docs/app/components/DocContent.tsx
@@ -12,20 +12,25 @@ import {
   getPreloadedDocBlocksContent,
   preloadDocBlocksContent,
 } from "./doc-block-renderer";
+import { DEFAULT_DOCS_LOCALE, type DocsLocale } from "./docs-locale";
 import MarkdownRenderer from "./MarkdownRenderer";
 
 interface Props {
   markdown: string;
+  locale?: DocsLocale;
 }
 
-export default function DocContent({ markdown }: Props) {
+export default function DocContent({
+  markdown,
+  locale = DEFAULT_DOCS_LOCALE,
+}: Props) {
   if (!hasDocBlockSyntax(markdown)) {
-    return <MarkdownRenderer markdown={markdown} />;
+    return <MarkdownRenderer markdown={markdown} locale={locale} />;
   }
 
   const PreloadedDocBlocksContent = getPreloadedDocBlocksContent();
   if (PreloadedDocBlocksContent) {
-    return <PreloadedDocBlocksContent markdown={markdown} />;
+    return <PreloadedDocBlocksContent markdown={markdown} locale={locale} />;
   }
 
   // Hydration can receive prerendered loader data without rerunning the route
@@ -34,8 +39,10 @@ export default function DocContent({ markdown }: Props) {
   void preloadDocBlocksContent();
 
   return (
-    <Suspense fallback={<MarkdownRenderer markdown={markdown} />}>
-      <DocBlocksContent markdown={markdown} />
+    <Suspense
+      fallback={<MarkdownRenderer markdown={markdown} locale={locale} />}
+    >
+      <DocBlocksContent markdown={markdown} locale={locale} />
     </Suspense>
   );
 }
diff --git a/packages/docs/app/components/MarkdownRenderer.tsx b/packages/docs/app/components/MarkdownRenderer.tsx
index 6cb7be18d1..56f6b34c51 100644
--- a/packages/docs/app/components/MarkdownRenderer.tsx
+++ b/packages/docs/app/components/MarkdownRenderer.tsx
@@ -8,8 +8,16 @@ import {
 import { useEffect, useMemo, useRef, useState } from "react";
 import { codeToHtml } from "shiki";
 
+import {
+  DEFAULT_DOCS_LOCALE,
+  localizeDocsHref,
+  type DocsLocale,
+} from "./docs-locale";
+import { slugifyHeading } from "./heading-slug";
+
 interface Props {
   markdown: string;
+  locale?: DocsLocale;
 }
 
 interface HighlightedMarkdownHtml {
@@ -297,7 +305,7 @@ const kbdExtension: MarkedExtension = {
 marked.use(kbdExtension);
 
 // Custom renderer to add IDs to headings and handle {#custom-id} syntax
-function createRenderer() {
+function createRenderer(locale: DocsLocale) {
   const renderer = new marked.Renderer();
 
   renderer.html = function ({ text }: Tokens.HTML) {
@@ -312,7 +320,8 @@ function createRenderer() {
     const text = this.parser.parseInline(token.tokens);
     if (!isSafeUrl(token.href, "link")) return text;
     const title = token.title ? ` title="${escapeHtml(token.title)}"` : "";
-    return `<a href="${escapeHtml(token.href)}"${title}>${text}</a>`;
+    const href = localizeDocsHref(token.href, locale);
+    return `<a href="${escapeHtml(href)}"${title}>${text}</a>`;
   };
 
   renderer.image = function (token: Tokens.Image) {
@@ -374,10 +383,7 @@ function createRenderer() {
     } else {
       displayHtml = rendered;
       const plain = rendered.replace(/<[^>]+>/g, "");
-      id = plain
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-|-$/g, "");
+      id = slugifyHeading(plain);
     }
     const tag = `h${depth}`;
     return `<${tag} id="${id}">${displayHtml}</${tag}>\n`;
@@ -388,21 +394,26 @@ function createRenderer() {
 
 const renderedMarkdownCache = new Map<string, string>();
 
-export function renderMarkdownToHtml(markdown: string): string {
-  const cached = renderedMarkdownCache.get(markdown);
+export function renderMarkdownToHtml(
+  markdown: string,
+  locale: DocsLocale = DEFAULT_DOCS_LOCALE,
+): string {
+  const cacheKey =
+    locale === DEFAULT_DOCS_LOCALE ? markdown : `${locale}\0${markdown}`;
+  const cached = renderedMarkdownCache.get(cacheKey);
   if (cached !== undefined) {
-    renderedMarkdownCache.delete(markdown);
-    renderedMarkdownCache.set(markdown, cached);
+    renderedMarkdownCache.delete(cacheKey);
+    renderedMarkdownCache.set(cacheKey, cached);
     return cached;
   }
 
-  const renderer = createRenderer();
+  const renderer = createRenderer(locale);
   const html = marked(markdown, { renderer, async: false }) as string;
   if (renderedMarkdownCache.size >= MAX_RENDERED_MARKDOWN_CACHE_ENTRIES) {
     const oldest = renderedMarkdownCache.keys().next().value;
     if (oldest !== undefined) renderedMarkdownCache.delete(oldest);
   }
-  renderedMarkdownCache.set(markdown, html);
+  renderedMarkdownCache.set(cacheKey, html);
   return html;
 }
 
@@ -415,7 +426,10 @@ export function resolveRenderedMarkdownHtml(
     : baseHtml;
 }
 
-export default function MarkdownRenderer({ markdown }: Props) {
+export default function MarkdownRenderer({
+  markdown,
+  locale = DEFAULT_DOCS_LOCALE,
+}: Props) {
   const articleRef = useRef<HTMLDivElement>(null);
   const t = useT();
   const [highlightedHtml, setHighlightedHtml] =
@@ -423,8 +437,8 @@ export default function MarkdownRenderer({ markdown }: Props) {
 
   // Convert markdown to HTML
   const baseHtml = useMemo(() => {
-    return renderMarkdownToHtml(markdown);
-  }, [markdown]);
+    return renderMarkdownToHtml(markdown, locale);
+  }, [markdown, locale]);
 
   // Highlight code blocks with Shiki after mount
   useEffect(() => {
diff --git a/packages/docs/app/components/doc-block-renderer.ts b/packages/docs/app/components/doc-block-renderer.ts
index a235ae2091..5c37a22c91 100644
--- a/packages/docs/app/components/doc-block-renderer.ts
+++ b/packages/docs/app/components/doc-block-renderer.ts
@@ -1,6 +1,11 @@
 import { lazy, type ComponentType } from "react";
 
-type DocBlocksContentComponent = ComponentType<{ markdown: string }>;
+import type { DocsLocale } from "./docs-locale";
+
+type DocBlocksContentComponent = ComponentType<{
+  markdown: string;
+  locale?: DocsLocale;
+}>;
 type DocBlocksContentModule = {
   default: DocBlocksContentComponent;
 };
diff --git a/packages/docs/app/components/docBlocks.tsx b/packages/docs/app/components/docBlocks.tsx
index 960935799f..408ce7188c 100644
--- a/packages/docs/app/components/docBlocks.tsx
+++ b/packages/docs/app/components/docBlocks.tsx
@@ -53,6 +53,7 @@ import { noticeBlock } from "./blocks/notice";
 import { signatureBlock } from "./blocks/signature";
 import { stepsBlock } from "./blocks/steps";
 import { videoBlock } from "./blocks/video";
+import { DEFAULT_DOCS_LOCALE, type DocsLocale } from "./docs-locale";
 import { renderMarkdownToHtml } from "./MarkdownRenderer";
 
 export {
@@ -98,11 +99,19 @@ function getDocBlockRegistry(): BlockRegistry {
 /* Render context                                                              */
 /* -------------------------------------------------------------------------- */
 
-function MarkdownInline({ markdown }: { markdown: string }): ReactNode {
+function MarkdownInline({
+  markdown,
+  locale,
+}: {
+  markdown: string;
+  locale: DocsLocale;
+}): ReactNode {
   return (
     <div
       className="docs-content"
-      dangerouslySetInnerHTML={{ __html: renderMarkdownToHtml(markdown) }}
+      dangerouslySetInnerHTML={{
+        __html: renderMarkdownToHtml(markdown, locale),
+      }}
     />
   );
 }
@@ -113,7 +122,7 @@ function MarkdownInline({ markdown }: { markdown: string }): ReactNode {
  * container blocks (tabs, columns) to a recursive dispatch so nested blocks render
  * through the same registry.
  */
-function useDocBlockContext(): BlockRenderContext {
+function useDocBlockContext(locale: DocsLocale): BlockRenderContext {
   const registry = getDocBlockRegistry();
   return useMemo<BlockRenderContext>(
     () => ({
@@ -121,16 +130,19 @@ function useDocBlockContext(): BlockRenderContext {
       textDirection: "ltr",
       visualFrame: "hide",
       showCodeAnnotationOverlays: false,
-      renderMarkdown: (markdown) => <MarkdownInline markdown={markdown} />,
+      renderMarkdown: (markdown) => (
+        <MarkdownInline markdown={markdown} locale={locale} />
+      ),
       renderBlock: ({ block, compactVisuals }) => (
         <DocNestedBlock
           block={block}
           registry={registry}
           compactVisuals={compactVisuals}
+          locale={locale}
         />
       ),
     }),
-    [registry],
+    [registry, locale],
   );
 }
 
@@ -138,12 +150,14 @@ function DocNestedBlock({
   block,
   registry,
   compactVisuals,
+  locale,
 }: {
   block: NestedBlock;
   registry: BlockRegistry;
   compactVisuals?: boolean;
+  locale: DocsLocale;
 }): ReactNode {
-  const ctx = useDocBlockContext();
+  const ctx = useDocBlockContext(locale);
   const spec = registry.get(block.type);
   if (!spec) return null;
   void compactVisuals;
@@ -162,9 +176,15 @@ function DocNestedBlock({
 /* -------------------------------------------------------------------------- */
 
 /** Provides the docs block registry + read-only render context to descendants. */
-export function DocBlocksProvider({ children }: { children: ReactNode }) {
+export function DocBlocksProvider({
+  children,
+  locale = DEFAULT_DOCS_LOCALE,
+}: {
+  children: ReactNode;
+  locale?: DocsLocale;
+}) {
   const registry = getDocBlockRegistry();
-  const ctx = useDocBlockContext();
+  const ctx = useDocBlockContext(locale);
   return (
     <BlockRegistryProvider registry={registry} ctx={ctx}>
       {children}
diff --git a/packages/docs/app/components/docs-content.ts b/packages/docs/app/components/docs-content.ts
index 6f1268ac8f..c612e0c680 100644
--- a/packages/docs/app/components/docs-content.ts
+++ b/packages/docs/app/components/docs-content.ts
@@ -17,6 +17,7 @@ import {
   isDocsLocale,
   type DocsLocale,
 } from "./docs-locale";
+import { slugifyHeading } from "./heading-slug";
 
 // Keep default docs route-lazy. Eagerly importing and parsing the whole corpus
 // makes every SSR cold start pay for documents unrelated to the requested page.
@@ -127,12 +128,7 @@ function extractHeadings(
     if (!match) continue;
     const level = match[1].length; // 2, 3, or 4
     const label = match[2].replace(/`([^`]+)`/g, "$1").trim();
-    const id =
-      match[3] ||
-      label
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-|-$/g, "");
+    const id = match[3] || slugifyHeading(label);
     headings.push({ id, label, level });
   }
   return headings;
@@ -357,12 +353,7 @@ async function buildSearchIndexFromDocs(
       const m = line.text.match(/^(#{2,3})\s+(.+?)(?:\s+\{#([\w-]+)\})?\s*$/);
       if (m) {
         const label = m[2].replace(/`([^`]+)`/g, "$1").trim();
-        const id =
-          m[3] ||
-          label
-            .toLowerCase()
-            .replace(/[^a-z0-9]+/g, "-")
-            .replace(/^-|-$/g, "");
+        const id = m[3] || slugifyHeading(label);
         sections.push({ id, label, startLine: line.lineNumber });
       }
     }
diff --git a/packages/docs/app/components/docs-locale.ts b/packages/docs/app/components/docs-locale.ts
index f505ddf178..31356b4270 100644
--- a/packages/docs/app/components/docs-locale.ts
+++ b/packages/docs/app/components/docs-locale.ts
@@ -135,6 +135,25 @@ export function sitePathForLocale(
   return unprefixedPath === "/" ? `/${locale}` : `/${locale}${unprefixedPath}`;
 }
 
+/**
+ * Rewrite a same-site `/docs/...` href written in a doc's markdown body so it
+ * stays in the given locale, e.g. `/docs/client-data#usedbsync` becomes
+ * `/de-DE/docs/client-data#usedbsync` for a non-default locale. Leaves
+ * already-locale-prefixed, external, in-page (`#anchor`), and non-docs hrefs
+ * untouched.
+ */
+export function localizeDocsHref(href: string, locale: DocsLocale): string {
+  if (locale === DEFAULT_DOCS_LOCALE) return href;
+  const hashIndex = href.indexOf("#");
+  const path = hashIndex === -1 ? href : href.slice(0, hashIndex);
+  const hash = hashIndex === -1 ? "" : href.slice(hashIndex);
+  if (!path || !isDocsPath(path) || routeLocaleFromPathname(path)) {
+    return href;
+  }
+  const slug = docsSlugFromPathname(path);
+  return slug ? `${docsPathForSlug(slug, locale)}${hash}` : href;
+}
+
 export function browserDocsLocale() {
   if (typeof navigator === "undefined") return DEFAULT_DOCS_LOCALE;
   return resolveLocaleFromCandidates(
diff --git a/packages/docs/app/components/heading-slug.ts b/packages/docs/app/components/heading-slug.ts
new file mode 100644
index 0000000000..5c8f7c7c37
--- /dev/null
+++ b/packages/docs/app/components/heading-slug.ts
@@ -0,0 +1,18 @@
+/**
+ * Slugify heading text into a stable anchor id. Keeps any Unicode letter,
+ * combining mark, or digit — so a heading written entirely in a non-Latin
+ * script (Chinese, Japanese, Korean, Arabic, Devanagari, ...) still gets a
+ * real, non-empty id instead of collapsing to "", and scripts that rely on
+ * combining marks (Devanagari vowel signs, Arabic diacritics) keep them
+ * instead of being reduced to bare consonants. Hyphenates whitespace/
+ * punctuation runs. Matches the previous ASCII-only behavior byte-for-byte
+ * for Latin-script headings, so existing English anchors are unaffected.
+ */
+export function slugifyHeading(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-")
+    .replace(/[^\p{L}\p{M}\p{N}-]+/gu, "")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
diff --git a/packages/docs/app/global.css b/packages/docs/app/global.css
index 6286c5491b..240162dd20 100644
--- a/packages/docs/app/global.css
+++ b/packages/docs/app/global.css
@@ -681,7 +681,6 @@ h4 {
   font-size: 14px;
 }
 
-
 /* Signature: function/hook signature reference — call line + parameter/return
    breakdown, collapsed to the call line until clicked.
    Usage in MDX: <Signature name params={[...]} returns={{...}} /> */
@@ -1305,8 +1304,6 @@ h4 {
   opacity: 0.45;
 }
 
-}
-
 /* Sidebar nav */
 .docs-sidebar-nav {
   overflow-anchor: none;
diff --git a/packages/docs/app/routes/docs.$locale.$slug.tsx b/packages/docs/app/routes/docs.$locale.$slug.tsx
index 2544e35543..ba66a0cfd3 100644
--- a/packages/docs/app/routes/docs.$locale.$slug.tsx
+++ b/packages/docs/app/routes/docs.$locale.$slug.tsx
@@ -95,7 +95,7 @@ export default function LocalizedDocPage() {
       markdownUrl={docsMarkdownPathForDoc(doc.slug, locale) ?? undefined}
     >
       {doc.draft && <DocDraftBanner />}
-      <DocContent markdown={doc.body} />
+      <DocContent markdown={doc.body} locale={locale} />
     </DocsLayout>
   );
 }

From f02cb9dfe37c9c3b185d63c9823370450a010418 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Tue, 11 Aug 2026 09:08:51 -0700
Subject: [PATCH 16/22] fix: unblock CI checks for the Client docs PR

Adds the missing changeset for the @agent-native/core docs changes. Fixes an
oxfmt formatting issue in docs-components.mdx left over from the merge
conflict resolution. Categorizes the new writing-reference-docs skill into
workspaceSkillExcludes, since it's dev-only guidance for this monorepo and
should not sync into generated workspace templates.
---
 .changeset/split-client-docs-into-sections.md |  5 +++
 .../core/docs/content/docs-components.mdx     | 36 +++++++++----------
 scripts/sync-workspace-core-skills.ts         |  1 +
 3 files changed, 24 insertions(+), 18 deletions(-)
 create mode 100644 .changeset/split-client-docs-into-sections.md

diff --git a/.changeset/split-client-docs-into-sections.md b/.changeset/split-client-docs-into-sections.md
new file mode 100644
index 0000000000..97e08f9320
--- /dev/null
+++ b/.changeset/split-client-docs-into-sections.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Split the Client docs page into focused Overview, Data & Sync, Agent Chat, Routing, Advanced, Sync Internals, and Entry Points pages, translate them into all ten supported locales, and fix several inaccurate examples and dead links found in review.
diff --git a/packages/core/docs/content/docs-components.mdx b/packages/core/docs/content/docs-components.mdx
index 993b1f99be..cb19c2ecd2 100644
--- a/packages/core/docs/content/docs-components.mdx
+++ b/packages/core/docs/content/docs-components.mdx
@@ -791,21 +791,21 @@ Like `TabsBlock`, `Columns` is self-closing with a single JSON `columns` attribu
 
 ## When to use which component
 
-| Situation                                              | Component                            |
-| ------------------------------------------------------ | ------------------------------------- |
-| Reader must not miss something, inline in prose        | `Callout` (warning / info / success) |
-| Reader must not miss something, standalone              | `Notice`                             |
-| Deprecated/beta/version notice at page or section top  | `Banner`                             |
-| Status or version tag at page or section top            | `Badge`                              |
-| Sequential procedure with titled steps                  | `Steps`                              |
-| FAQ-style content, one answer at a time                | `Accordion`                          |
-| Navigation or feature overview grid                     | `Cards`                              |
-| Before vs. after, old vs. new (prose)                  | `Comparison`                         |
-| Same task in multiple tools or frameworks               | `Tabs`                               |
-| Side-by-side code (labeled columns)                     | `Columns`                            |
-| Project directory structure                             | `FileTree`                           |
-| A function/hook/action's call shape                     | `Signature`                          |
-| An image, full width or with paired text                | `Image`                              |
-| A video, full width or with paired text                 | `Video`                              |
-| Inline keyboard shortcut                                | `[[Key]]`                            |
-| Architecture or flow diagram                            | Mermaid fence                        |
+| Situation                                             | Component                            |
+| ----------------------------------------------------- | ------------------------------------ |
+| Reader must not miss something, inline in prose       | `Callout` (warning / info / success) |
+| Reader must not miss something, standalone            | `Notice`                             |
+| Deprecated/beta/version notice at page or section top | `Banner`                             |
+| Status or version tag at page or section top          | `Badge`                              |
+| Sequential procedure with titled steps                | `Steps`                              |
+| FAQ-style content, one answer at a time               | `Accordion`                          |
+| Navigation or feature overview grid                   | `Cards`                              |
+| Before vs. after, old vs. new (prose)                 | `Comparison`                         |
+| Same task in multiple tools or frameworks             | `Tabs`                               |
+| Side-by-side code (labeled columns)                   | `Columns`                            |
+| Project directory structure                           | `FileTree`                           |
+| A function/hook/action's call shape                   | `Signature`                          |
+| An image, full width or with paired text              | `Image`                              |
+| A video, full width or with paired text               | `Video`                              |
+| Inline keyboard shortcut                              | `[[Key]]`                            |
+| Architecture or flow diagram                          | Mermaid fence                        |
diff --git a/scripts/sync-workspace-core-skills.ts b/scripts/sync-workspace-core-skills.ts
index ffa15c404a..83122f8835 100644
--- a/scripts/sync-workspace-core-skills.ts
+++ b/scripts/sync-workspace-core-skills.ts
@@ -277,6 +277,7 @@ const workspaceSkillExcludes = [
   "ship",
   "ship-desktop",
   "verifying-changes",
+  "writing-reference-docs",
 ];
 
 const check = process.argv.includes("--check");

From 56dc88e3ec6a2b7eae0e46cda107916a25afd604 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Tue, 11 Aug 2026 10:10:48 -0700
Subject: [PATCH 17/22] fix: address second review pass on Client docs and
 media blocks

Rejects protocol-relative media src values (//attacker.example/...), which
the existing regex let through despite the schema's own error message
promising otherwise; adds a regression test.

Fixes the custom-suggestions example in client-advanced.mdx: getSuggestions
must nest inside dynamicSuggestions, not sit as a top-level AgentSidebar prop,
and narrows the unknown navigation snapshot before reading its fields.
Applied across English and all 10 locales.

Delays Video block autoplay until the reduced-motion preference actually
resolves instead of defaulting to false, since a reduced-motion browser can
start playback before the matchMedia effect runs and removing the prop
afterward does not stop it; adds a regression test covering SSR, resolved
reduced-motion, and resolved no-preference states.

Reverts client-agent-chat.mdx's sendToAgentChat `context` description back to
hidden-from-the-user: it is appended to the message sent to the agent, but
message-components.tsx strips <context> blocks before the chat UI renders the
message, so the model sees it and the user does not. Applied across English
and all 10 locales.

Exports readClientAppStateMany and ClientAppStateBatch from
@agent-native/core/client/hooks alongside their sibling application-state
helpers, so the documented batched-read example actually resolves instead of
throwing a module-export error.
---
 .../export-read-client-app-state-many.md      |  5 +
 .../core/docs/content/client-advanced.mdx     | 22 +++--
 .../core/docs/content/client-agent-chat.mdx   | 18 ++--
 .../content/locales/ar-SA/client-advanced.mdx | 22 +++--
 .../locales/ar-SA/client-agent-chat.mdx       | 18 ++--
 .../content/locales/de-DE/client-advanced.mdx | 22 +++--
 .../locales/de-DE/client-agent-chat.mdx       | 18 ++--
 .../content/locales/es-ES/client-advanced.mdx | 22 +++--
 .../locales/es-ES/client-agent-chat.mdx       | 18 ++--
 .../content/locales/fr-FR/client-advanced.mdx | 22 +++--
 .../locales/fr-FR/client-agent-chat.mdx       | 18 ++--
 .../content/locales/hi-IN/client-advanced.mdx | 22 +++--
 .../locales/hi-IN/client-agent-chat.mdx       | 18 ++--
 .../content/locales/ja-JP/client-advanced.mdx | 22 +++--
 .../locales/ja-JP/client-agent-chat.mdx       | 18 ++--
 .../content/locales/ko-KR/client-advanced.mdx | 27 ++++--
 .../locales/ko-KR/client-agent-chat.mdx       | 18 ++--
 .../content/locales/pt-BR/client-advanced.mdx | 22 +++--
 .../locales/pt-BR/client-agent-chat.mdx       | 18 ++--
 .../content/locales/zh-CN/client-advanced.mdx | 22 +++--
 .../locales/zh-CN/client-agent-chat.mdx       | 18 ++--
 .../content/locales/zh-TW/client-advanced.mdx | 22 +++--
 .../locales/zh-TW/client-agent-chat.mdx       | 18 ++--
 packages/core/src/client/hooks/index.ts       |  2 +
 .../components/blocks/media-shared.test.ts    | 30 ++++++
 .../app/components/blocks/media-shared.ts     |  2 +-
 .../docs/app/components/blocks/video.test.tsx | 93 +++++++++++++++++++
 packages/docs/app/components/blocks/video.tsx | 30 +++---
 28 files changed, 417 insertions(+), 190 deletions(-)
 create mode 100644 .changeset/export-read-client-app-state-many.md
 create mode 100644 packages/docs/app/components/blocks/media-shared.test.ts
 create mode 100644 packages/docs/app/components/blocks/video.test.tsx

diff --git a/.changeset/export-read-client-app-state-many.md b/.changeset/export-read-client-app-state-many.md
new file mode 100644
index 0000000000..442d026afa
--- /dev/null
+++ b/.changeset/export-read-client-app-state-many.md
@@ -0,0 +1,5 @@
+---
+"@agent-native/core": patch
+---
+
+Export `readClientAppStateMany` (and its `ClientAppStateBatch` return type) from `@agent-native/core/client/hooks`, alongside its sibling application-state helpers, so the documented batched-read import actually resolves.
diff --git a/packages/core/docs/content/client-advanced.mdx b/packages/core/docs/content/client-advanced.mdx
index 0d846336c6..7f5578e667 100644
--- a/packages/core/docs/content/client-advanced.mdx
+++ b/packages/core/docs/content/client-advanced.mdx
@@ -163,22 +163,30 @@ display-mode requests, is owned by
 
 ## Custom Suggestion Chips {#custom-suggestions}
 
-`<AgentSidebar>`'s `dynamicSuggestions` (see [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) already merges static `suggestions` with the framework's own context-aware heuristic. Pass `getSuggestions` instead when an app wants deterministic, domain-specific chips computed from the same `application_state` context rather than the framework's default heuristic.
+`<AgentSidebar>`'s `dynamicSuggestions` (see [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) already merges static `suggestions` with the framework's own context-aware heuristic. Pass a `getSuggestions` function inside `dynamicSuggestions` instead when an app wants deterministic, domain-specific chips computed from the same `application_state` context rather than the framework's default heuristic.
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` receives the same `navigation`/`selection`/`pending-selection-context` snapshot the built-in heuristic reads, so a custom implementation can react to exactly the state the default one does, just with app-specific rules instead of generic ones.
+`getSuggestions` receives the same `navigation`/`selection`/`pendingSelection` snapshot the built-in heuristic reads, typed as `unknown` since its shape is app-defined, so narrow it before reading fields. A custom implementation can react to exactly the state the default one does, just with app-specific rules instead of generic ones.
 
 ## What's next
 
diff --git a/packages/core/docs/content/client-agent-chat.mdx b/packages/core/docs/content/client-agent-chat.mdx
index 265a16187f..9e8ca93856 100644
--- a/packages/core/docs/content/client-agent-chat.mdx
+++ b/packages/core/docs/content/client-agent-chat.mdx
@@ -183,11 +183,11 @@ Combining this with the `askUserQuestion()` example above completes the button's
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-Send a message to the agent chat via `postMessage`. This is the lower-level primitive `useAgentChatGenerating()` above wraps, useful when a UI interaction doesn't need loading-state tracking of its own. Pass `context` for extra detail the message alone doesn't carry. It gets appended to the same visible message, wrapped in `<context>` tags. It is not hidden from the user. Pass `submit: true` to send immediately, or `submit: false` to prefill a draft the user reviews first.
+Send a message to the agent chat via `postMessage`. This is the lower-level primitive `useAgentChatGenerating()` above wraps, useful when a UI interaction doesn't need loading-state tracking of its own. Pass `context` for extra detail the model should see but the user shouldn't. It's appended to the message sent to the agent, wrapped in `<context>` tags, and stripped back out before the message renders in the chat UI. Pass `submit: true` to send immediately, or `submit: false` to prefill a draft the user reviews first.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// Auto-submit a prompt with hidden context
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -204,13 +204,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| Option        | Type       | Description                                                                                         |
-| ------------- | ---------- | --------------------------------------------------------------------------------------------------- |
-| `message`     | `string`   | The prompt sent to the chat. `context`, if set, is appended to this same visible message            |
-| `context`     | `string?`  | Extra detail appended to the visible message, wrapped in `<context>` tags. Not hidden from the user |
-| `submit`      | `boolean?` | true = auto-submit, false = prefill only                                                            |
-| `newTab`      | `boolean?` | Create a separate chat thread for this prompt                                                       |
-| `openSidebar` | `boolean?` | Set false to submit/prefill without opening the sidebar                                             |
+| Option        | Type       | Description                                                                                     |
+| ------------- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | The prompt sent to the chat, and the only part shown in the chat UI                             |
+| `context`     | `string?`  | Model-visible context appended to the message before sending. Stripped from the chat UI display |
+| `submit`      | `boolean?` | true = auto-submit, false = prefill only                                                        |
+| `newTab`      | `boolean?` | Create a separate chat thread for this prompt                                                   |
+| `openSidebar` | `boolean?` | Set false to submit/prefill without opening the sidebar                                         |
 
 Running this from inside an MCP App embed, or backgrounding the run without opening the sidebar, are both covered in [Advanced](/docs/client-advanced#background-send).
 
diff --git a/packages/core/docs/content/locales/ar-SA/client-advanced.mdx b/packages/core/docs/content/locales/ar-SA/client-advanced.mdx
index 46c3928dc4..dc7484e374 100644
--- a/packages/core/docs/content/locales/ar-SA/client-advanced.mdx
+++ b/packages/core/docs/content/locales/ar-SA/client-advanced.mdx
@@ -163,22 +163,30 @@ import {
 
 ## شرائح الاقتراحات المخصصة {#custom-suggestions}
 
-تدمج `dynamicSuggestions` الخاصة بـ `<AgentSidebar>` (راجع [محادثة الوكيل](/docs/client-agent-chat#dynamic-suggestions)) بالفعل `suggestions` الثابتة مع الاستدلال المدرك للسياق الخاص بإطار العمل. مرر `getSuggestions` بدلًا من ذلك عندما يريد تطبيق شرائح حتمية خاصة بالمجال محسوبة من نفس سياق `application_state` بدلًا من استدلال إطار العمل الافتراضي.
+تدمج `dynamicSuggestions` الخاصة بـ `<AgentSidebar>` (راجع [محادثة الوكيل](/docs/client-agent-chat#dynamic-suggestions)) بالفعل `suggestions` الثابتة مع الاستدلال المدرك للسياق الخاص بإطار العمل. مرر دالة `getSuggestions` داخل `dynamicSuggestions` بدلًا من ذلك عندما يريد تطبيق شرائح حتمية خاصة بالمجال محسوبة من نفس سياق `application_state` بدلًا من استدلال إطار العمل الافتراضي.
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-تستقبل `getSuggestions` نفس لقطة `navigation`/`selection`/`pending-selection-context` التي يقرأها الاستدلال المدمج، لذا يمكن لتنفيذ مخصص أن يتفاعل مع الحالة نفسها التي يتفاعل معها الاستدلال الافتراضي بالضبط، فقط بقواعد خاصة بالتطبيق بدلًا من قواعد عامة.
+تستقبل `getSuggestions` نفس لقطة `navigation`/`selection`/`pendingSelection` التي يقرأها الاستدلال المدمج، مكتوبة كـ `unknown` لأن شكلها يحدده التطبيق، لذا يجب تضييقها قبل قراءة حقولها. يمكن لتنفيذ مخصص أن يتفاعل مع الحالة نفسها التي يتفاعل معها الاستدلال الافتراضي بالضبط، فقط بقواعد خاصة بالتطبيق بدلًا من قواعد عامة.
 
 ## ما هي الخطوة التالية
 
diff --git a/packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx b/packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx
index 6e0f864b5f..803faab48a 100644
--- a/packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/ar-SA/client-agent-chat.mdx
@@ -182,11 +182,11 @@ const answer = await askUserQuestion({
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-أرسل رسالة إلى محادثة الوكيل عبر `postMessage`. هذا هو البدائي (primitive) ذو المستوى الأدنى الذي تُغلّفه `useAgentChatGenerating()` أعلاه، وهو مفيد عندما لا يحتاج تفاعل واجهة المستخدم إلى تتبع حالة تحميل خاص به. مرر `context` لتفصيل إضافي لا تحمله الرسالة بمفردها. يُلحَق بنفس الرسالة المرئية، مُغلَّفًا بوسوم `<context>`. إنه ليس مخفيًا عن المستخدم. مرر `submit: true` للإرسال فورًا، أو `submit: false` لتعبئة مسودة يراجعها المستخدم أولًا.
+أرسل رسالة إلى محادثة الوكيل عبر `postMessage`. هذا هو البدائي (primitive) ذو المستوى الأدنى الذي تُغلّفه `useAgentChatGenerating()` أعلاه، وهو مفيد عندما لا يحتاج تفاعل واجهة المستخدم إلى تتبع حالة تحميل خاص به. مرر `context` لتفصيل إضافي ينبغي أن يراه الوكيل دون أن يراه المستخدم. يُلحَق بالرسالة المرسلة إلى الوكيل، مُغلَّفًا بوسوم `<context>`، ثم يُزال قبل عرض الرسالة في واجهة المحادثة. مرر `submit: true` للإرسال فورًا، أو `submit: false` لتعبئة مسودة يراجعها المستخدم أولًا.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// إرسال تلقائي لمطالبة مع سياق مخفي
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -203,13 +203,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| الخيار        | النوع      | الوصف                                                                                 |
-| ------------- | ---------- | ------------------------------------------------------------------------------------- |
-| `message`     | `string`   | المطالبة المُرسلة إلى المحادثة. يُلحَق `context`، إن وُجد، بهذه الرسالة المرئية نفسها |
-| `context`     | `string?`  | تفصيل إضافي يُلحَق بالرسالة المرئية، مُغلَّف بوسوم `<context>`. غير مخفي عن المستخدم  |
-| `submit`      | `boolean?` | true = إرسال تلقائي، false = تعبئة مسبقة فقط                                          |
-| `newTab`      | `boolean?` | إنشاء سلسلة محادثة منفصلة لهذه المطالبة                                               |
-| `openSidebar` | `boolean?` | اضبطه على false للإرسال/التعبئة المسبقة دون فتح الشريط الجانبي                        |
+| الخيار        | النوع      | الوصف                                                                        |
+| ------------- | ---------- | ---------------------------------------------------------------------------- |
+| `message`     | `string`   | المطالبة المُرسلة إلى المحادثة، وهي الجزء الوحيد الذي يظهر في واجهة المحادثة |
+| `context`     | `string?`  | سياق يراه الوكيل يُلحَق بالرسالة قبل إرسالها. يُزال من عرض واجهة المحادثة    |
+| `submit`      | `boolean?` | true = إرسال تلقائي، false = تعبئة مسبقة فقط                                 |
+| `newTab`      | `boolean?` | إنشاء سلسلة محادثة منفصلة لهذه المطالبة                                      |
+| `openSidebar` | `boolean?` | اضبطه على false للإرسال/التعبئة المسبقة دون فتح الشريط الجانبي               |
 
 تشغيل هذا من داخل تضمين MCP App، أو تشغيل العمل في الخلفية دون فتح الشريط الجانبي، مُغطّى كلاهما في [متقدم](/docs/client-advanced#background-send).
 
diff --git a/packages/core/docs/content/locales/de-DE/client-advanced.mdx b/packages/core/docs/content/locales/de-DE/client-advanced.mdx
index 997d7165a6..719d6bb1ab 100644
--- a/packages/core/docs/content/locales/de-DE/client-advanced.mdx
+++ b/packages/core/docs/content/locales/de-DE/client-advanced.mdx
@@ -162,22 +162,30 @@ Anzeigemodus-Anfragen, gehört zu
 
 ## Benutzerdefinierte Vorschlags-Chips {#custom-suggestions}
 
-`dynamicSuggestions` von `<AgentSidebar>` (siehe [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) führt statische `suggestions` bereits mit der eigenen kontextbewussten Heuristik des Frameworks zusammen. Übergeben Sie stattdessen `getSuggestions`, wenn eine App deterministische, domänenspezifische Chips möchte, berechnet aus demselben `application_state`-Kontext statt aus der Standard-Heuristik des Frameworks.
+`dynamicSuggestions` von `<AgentSidebar>` (siehe [Agent Chat](/docs/client-agent-chat#dynamic-suggestions)) führt statische `suggestions` bereits mit der eigenen kontextbewussten Heuristik des Frameworks zusammen. Übergeben Sie stattdessen eine `getSuggestions`-Funktion innerhalb von `dynamicSuggestions`, wenn eine App deterministische, domänenspezifische Chips möchte, berechnet aus demselben `application_state`-Kontext statt aus der Standard-Heuristik des Frameworks.
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` erhält denselben `navigation`/`selection`/`pending-selection-context`-Snapshot, den die eingebaute Heuristik liest, sodass eine benutzerdefinierte Implementierung auf genau den Zustand reagieren kann, auf den auch die Standardimplementierung reagiert, nur mit app-spezifischen Regeln statt generischer.
+`getSuggestions` erhält denselben `navigation`/`selection`/`pendingSelection`-Snapshot, den die eingebaute Heuristik liest, typisiert als `unknown`, da die Form von der App abhängt, also grenzen Sie ihn ein, bevor Sie Felder lesen. Eine benutzerdefinierte Implementierung kann auf genau den Zustand reagieren, auf den auch die Standardimplementierung reagiert, nur mit app-spezifischen Regeln statt generischer.
 
 ## Was kommt als nächstes?
 
diff --git a/packages/core/docs/content/locales/de-DE/client-agent-chat.mdx b/packages/core/docs/content/locales/de-DE/client-agent-chat.mdx
index 6815134716..92d05cfe45 100644
--- a/packages/core/docs/content/locales/de-DE/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/de-DE/client-agent-chat.mdx
@@ -185,11 +185,11 @@ Die Kombination davon mit dem `askUserQuestion()`-Beispiel oben vervollständigt
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-Sendet eine Nachricht an den Agent-Chat über `postMessage`. Dies ist die niedrigere Primitive, die `useAgentChatGenerating()` oben umschließt, nützlich, wenn eine UI-Interaktion keine eigene Ladezustandsverfolgung benötigt. Übergeben Sie `context` für zusätzliche Details, die die Nachricht allein nicht trägt. Er wird derselben sichtbaren Nachricht angehängt, eingeschlossen in `<context>`-Tags. Er ist nicht vor dem Benutzer verborgen. Übergeben Sie `submit: true`, um sofort zu senden, oder `submit: false`, um einen Entwurf vorab auszufüllen, den der Benutzer zuerst überprüft.
+Sendet eine Nachricht an den Agent-Chat über `postMessage`. Dies ist die niedrigere Primitive, die `useAgentChatGenerating()` oben umschließt, nützlich, wenn eine UI-Interaktion keine eigene Ladezustandsverfolgung benötigt. Übergeben Sie `context` für zusätzliche Details, die das Modell sehen soll, der Benutzer aber nicht. Er wird an die an den Agenten gesendete Nachricht angehängt, eingeschlossen in `<context>`-Tags, und wird wieder entfernt, bevor die Nachricht im Chat angezeigt wird. Übergeben Sie `submit: true`, um sofort zu senden, oder `submit: false`, um einen Entwurf vorab auszufüllen, den der Benutzer zuerst überprüft.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Automatisches Senden eines Prompts mit angehängtem Kontext
+// Automatisches Senden eines Prompts mit verborgenem Kontext
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -206,13 +206,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| Option        | Typ        | Beschreibung                                                                                                                    |
-| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `message`     | `string`   | Der an den Chat gesendete Prompt. `context`, falls gesetzt, wird derselben sichtbaren Nachricht angehängt                       |
-| `context`     | `string?`  | Zusätzliche Details, angehängt an die sichtbare Nachricht, eingeschlossen in `<context>`-Tags. Nicht vor dem Benutzer verborgen |
-| `submit`      | `boolean?` | true = automatisches Senden, false = nur Vorabausfüllung                                                                        |
-| `newTab`      | `boolean?` | Einen separaten Chat-Thread für diesen Prompt erstellen                                                                         |
-| `openSidebar` | `boolean?` | Auf false setzen, um zu senden/vorab auszufüllen, ohne die Seitenleiste zu öffnen                                               |
+| Option        | Typ        | Beschreibung                                                                                                                 |
+| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | Der an den Chat gesendete Prompt, und der einzige Teil, der in der Chat-UI angezeigt wird                                    |
+| `context`     | `string?`  | Für das Modell sichtbarer Kontext, der vor dem Senden an die Nachricht angehängt wird. Wird aus der Chat-UI-Anzeige entfernt |
+| `submit`      | `boolean?` | true = automatisches Senden, false = nur Vorabausfüllung                                                                     |
+| `newTab`      | `boolean?` | Einen separaten Chat-Thread für diesen Prompt erstellen                                                                      |
+| `openSidebar` | `boolean?` | Auf false setzen, um zu senden/vorab auszufüllen, ohne die Seitenleiste zu öffnen                                            |
 
 Das Ausführen davon aus einem eingebetteten MCP-App-Frame heraus, oder das Ausführen im Hintergrund ohne Öffnen der Seitenleiste, wird beides in [Fortgeschritten](/docs/client-advanced#background-send) behandelt.
 
diff --git a/packages/core/docs/content/locales/es-ES/client-advanced.mdx b/packages/core/docs/content/locales/es-ES/client-advanced.mdx
index 47f1878436..9295438d64 100644
--- a/packages/core/docs/content/locales/es-ES/client-advanced.mdx
+++ b/packages/core/docs/content/locales/es-ES/client-advanced.mdx
@@ -163,22 +163,30 @@ las solicitudes de modo de visualización, son propiedad de
 
 ## Chips de sugerencias personalizadas {#custom-suggestions}
 
-`dynamicSuggestions` de `<AgentSidebar>` (consulta [Chat del Agent](/docs/client-agent-chat#dynamic-suggestions)) ya combina las `suggestions` estáticas con la propia heurística consciente del contexto del framework. Pasa `getSuggestions` en su lugar cuando una app quiera chips deterministas y específicos de dominio calculados a partir del mismo contexto de `application_state` en lugar de la heurística predeterminada del framework.
+`dynamicSuggestions` de `<AgentSidebar>` (consulta [Chat del Agent](/docs/client-agent-chat#dynamic-suggestions)) ya combina las `suggestions` estáticas con la propia heurística consciente del contexto del framework. Pasa una función `getSuggestions` dentro de `dynamicSuggestions` en su lugar cuando una app quiera chips deterministas y específicos de dominio calculados a partir del mismo contexto de `application_state` en lugar de la heurística predeterminada del framework.
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` recibe la misma instantánea de `navigation`/`selection`/`pending-selection-context` que lee la heurística incorporada, así que una implementación personalizada puede reaccionar exactamente al mismo estado que la predeterminada, solo que con reglas específicas de la app en lugar de genéricas.
+`getSuggestions` recibe la misma instantánea de `navigation`/`selection`/`pendingSelection` que lee la heurística incorporada, tipada como `unknown` porque su forma la define la app, así que hay que acotarla antes de leer sus campos. Una implementación personalizada puede reaccionar exactamente al mismo estado que la predeterminada, solo que con reglas específicas de la app en lugar de genéricas.
 
 ## ¿Qué sigue?
 
diff --git a/packages/core/docs/content/locales/es-ES/client-agent-chat.mdx b/packages/core/docs/content/locales/es-ES/client-agent-chat.mdx
index 96e8a59100..c24dcc52e0 100644
--- a/packages/core/docs/content/locales/es-ES/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/es-ES/client-agent-chat.mdx
@@ -185,11 +185,11 @@ Combinar esto con el ejemplo de `askUserQuestion()` de arriba completa el maneja
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-Envía un mensaje al chat del agente a través de `postMessage`. Este es el primitivo de nivel más bajo que envuelve `useAgentChatGenerating()` arriba, útil cuando una interacción de UI no necesita su propio seguimiento de estado de carga. Pasa `context` para detalle adicional que el mensaje por sí solo no transmite. Se agrega al mismo mensaje visible, envuelto en etiquetas `<context>`. No se oculta al usuario. Pasa `submit: true` para enviar de inmediato, o `submit: false` para precompletar un borrador que el usuario revisa primero.
+Envía un mensaje al chat del agente a través de `postMessage`. Este es el primitivo de nivel más bajo que envuelve `useAgentChatGenerating()` arriba, útil cuando una interacción de UI no necesita su propio seguimiento de estado de carga. Pasa `context` para detalle adicional que el modelo debería ver pero el usuario no. Se agrega al mensaje enviado al agente, envuelto en etiquetas `<context>`, y se elimina antes de que el mensaje se muestre en la interfaz del chat. Pasa `submit: true` para enviar de inmediato, o `submit: false` para precompletar un borrador que el usuario revisa primero.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// Enviar automáticamente un prompt con contexto oculto
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -206,13 +206,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| Opción        | Tipo       | Descripción                                                                                               |
-| ------------- | ---------- | --------------------------------------------------------------------------------------------------------- |
-| `message`     | `string`   | El prompt enviado al chat. `context`, si se establece, se agrega a este mismo mensaje visible             |
-| `context`     | `string?`  | Detalle adicional agregado al mensaje visible, envuelto en etiquetas `<context>`. No se oculta al usuario |
-| `submit`      | `boolean?` | true = envío automático, false = solo precompletar                                                        |
-| `newTab`      | `boolean?` | Crea un hilo de chat independiente para este prompt                                                       |
-| `openSidebar` | `boolean?` | Establece falso para enviar/precompletar sin abrir la barra lateral                                       |
+| Opción        | Tipo       | Descripción                                                                                                |
+| ------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | El prompt enviado al chat, y la única parte que se muestra en la interfaz del chat                         |
+| `context`     | `string?`  | Contexto visible para el modelo, agregado al mensaje antes de enviarlo. Se elimina de la interfaz del chat |
+| `submit`      | `boolean?` | true = envío automático, false = solo precompletar                                                         |
+| `newTab`      | `boolean?` | Crea un hilo de chat independiente para este prompt                                                        |
+| `openSidebar` | `boolean?` | Establece falso para enviar/precompletar sin abrir la barra lateral                                        |
 
 Ejecutar esto desde dentro de una inserción de aplicación MCP, o poner la ejecución en segundo plano sin abrir la barra lateral, se cubren ambos en [Avanzado](/docs/client-advanced#background-send).
 
diff --git a/packages/core/docs/content/locales/fr-FR/client-advanced.mdx b/packages/core/docs/content/locales/fr-FR/client-advanced.mdx
index 4167843a32..a1aa8f5b71 100644
--- a/packages/core/docs/content/locales/fr-FR/client-advanced.mdx
+++ b/packages/core/docs/content/locales/fr-FR/client-advanced.mdx
@@ -166,22 +166,30 @@ contexte hôte, et les requêtes de mode d'affichage, sont pris en charge par
 
 ## Puces de suggestion personnalisées {#custom-suggestions}
 
-Le `dynamicSuggestions` de `<AgentSidebar>` (voir [Chat de l’Agent](/docs/client-agent-chat#dynamic-suggestions)) fusionne déjà les `suggestions` statiques avec l'heuristique propre au framework, consciente du contexte. Transmettez `getSuggestions` à la place lorsqu'une application veut des puces déterministes, spécifiques à son domaine, calculées à partir du même contexte `application_state` plutôt qu'à partir de l'heuristique par défaut du framework.
+Le `dynamicSuggestions` de `<AgentSidebar>` (voir [Chat de l’Agent](/docs/client-agent-chat#dynamic-suggestions)) fusionne déjà les `suggestions` statiques avec l'heuristique propre au framework, consciente du contexte. Transmettez plutôt une fonction `getSuggestions` à l'intérieur de `dynamicSuggestions` lorsqu'une application veut des puces déterministes, spécifiques à son domaine, calculées à partir du même contexte `application_state` plutôt qu'à partir de l'heuristique par défaut du framework.
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` reçoit le même instantané `navigation`/`selection`/`pending-selection-context` que l'heuristique intégrée lit, afin qu'une implémentation personnalisée puisse réagir exactement au même état que celui lu par l'implémentation par défaut, simplement avec des règles spécifiques à l'application plutôt que génériques.
+`getSuggestions` reçoit le même instantané `navigation`/`selection`/`pendingSelection` que l'heuristique intégrée lit, typé `unknown` car sa forme est définie par l'application, il faut donc le restreindre avant de lire ses champs. Une implémentation personnalisée peut réagir exactement au même état que celui lu par l'implémentation par défaut, simplement avec des règles spécifiques à l'application plutôt que génériques.
 
 ## Quelle est la prochaine étape
 
diff --git a/packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx b/packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx
index bc11abff64..fe0bb46988 100644
--- a/packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/fr-FR/client-agent-chat.mdx
@@ -186,11 +186,11 @@ Combiner ceci avec l'exemple `askUserQuestion()` ci-dessus complète le gestionn
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-Envoie un message au chat de l'agent via `postMessage`. C'est la primitive de plus bas niveau que `useAgentChatGenerating()` ci-dessus enveloppe, utile lorsqu'une interaction UI n'a pas besoin de son propre suivi d'état de chargement. Transmettez `context` pour un détail supplémentaire que le message seul ne porte pas. Il est ajouté au même message visible, entouré de balises `<context>`. Il n'est pas masqué à l'utilisateur. Transmettez `submit: true` pour envoyer immédiatement, ou `submit: false` pour pré-remplir un brouillon que l'utilisateur examine d'abord.
+Envoie un message au chat de l'agent via `postMessage`. C'est la primitive de plus bas niveau que `useAgentChatGenerating()` ci-dessus enveloppe, utile lorsqu'une interaction UI n'a pas besoin de son propre suivi d'état de chargement. Transmettez `context` pour un détail supplémentaire que le modèle doit voir mais pas l'utilisateur. Il est ajouté au message envoyé à l'agent, entouré de balises `<context>`, puis retiré avant que le message ne s'affiche dans l'interface de chat. Transmettez `submit: true` pour envoyer immédiatement, ou `submit: false` pour pré-remplir un brouillon que l'utilisateur examine d'abord.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// Envoi automatique d'un prompt avec contexte masqué
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -207,13 +207,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| Option        | Type       | Description                                                                                                 |
-| ------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
-| `message`     | `string`   | Le prompt envoyé au chat. `context`, si défini, est ajouté à ce même message visible                        |
-| `context`     | `string?`  | Détail supplémentaire ajouté au message visible, entouré de balises `<context>`. Pas masqué à l'utilisateur |
-| `submit`      | `boolean?` | true = envoi automatique, false = préremplissage uniquement                                                 |
-| `newTab`      | `boolean?` | Crée un fil de discussion distinct pour ce prompt                                                           |
-| `openSidebar` | `boolean?` | Définir sur false pour envoyer/préremplir sans ouvrir la barre latérale                                     |
+| Option        | Type       | Description                                                                                                   |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | Le prompt envoyé au chat, et la seule partie affichée dans l'interface de chat                                |
+| `context`     | `string?`  | Contexte visible par le modèle, ajouté au message avant l'envoi. Retiré de l'affichage de l'interface de chat |
+| `submit`      | `boolean?` | true = envoi automatique, false = préremplissage uniquement                                                   |
+| `newTab`      | `boolean?` | Crée un fil de discussion distinct pour ce prompt                                                             |
+| `openSidebar` | `boolean?` | Définir sur false pour envoyer/préremplir sans ouvrir la barre latérale                                       |
 
 Exécuter ceci depuis l'intérieur d'une intégration MCP App, ou mettre l'exécution en arrière-plan sans ouvrir la barre latérale, sont tous les deux couverts dans [Avancé](/docs/client-advanced#background-send).
 
diff --git a/packages/core/docs/content/locales/hi-IN/client-advanced.mdx b/packages/core/docs/content/locales/hi-IN/client-advanced.mdx
index 885237afd9..18bf48156d 100644
--- a/packages/core/docs/content/locales/hi-IN/client-advanced.mdx
+++ b/packages/core/docs/content/locales/hi-IN/client-advanced.mdx
@@ -163,22 +163,30 @@ import {
 
 ## कस्टम सुझाव चिप्स {#custom-suggestions}
 
-`<AgentSidebar>` का `dynamicSuggestions` (देखें [एजेंट चैट](/docs/client-agent-chat#dynamic-suggestions)) पहले से ही स्टैटिक `suggestions` को फ्रेमवर्क के अपने कॉन्टेक्स्ट-अवेयर हेयुरिस्टिक के साथ मर्ज करता है। जब कोई ऐप फ्रेमवर्क के डिफ़ॉल्ट हेयुरिस्टिक के बजाय उसी `application_state` कॉन्टेक्स्ट से कंप्यूट किए गए नियतात्मक, डोमेन-विशिष्ट चिप्स चाहता है तो इसके बजाय `getSuggestions` पास करें।
+`<AgentSidebar>` का `dynamicSuggestions` (देखें [एजेंट चैट](/docs/client-agent-chat#dynamic-suggestions)) पहले से ही स्टैटिक `suggestions` को फ्रेमवर्क के अपने कॉन्टेक्स्ट-अवेयर हेयुरिस्टिक के साथ मर्ज करता है। जब कोई ऐप फ्रेमवर्क के डिफ़ॉल्ट हेयुरिस्टिक के बजाय उसी `application_state` कॉन्टेक्स्ट से कंप्यूट किए गए नियतात्मक, डोमेन-विशिष्ट चिप्स चाहता है तो इसके बजाय `dynamicSuggestions` के भीतर एक `getSuggestions` फ़ंक्शन पास करें।
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` उसी `navigation`/`selection`/`pending-selection-context` स्नैपशॉट को प्राप्त करता है जिसे बिल्ट-इन हेयुरिस्टिक पढ़ता है, इसलिए कोई कस्टम इम्प्लीमेंटेशन उसी स्टेट के प्रति रिएक्ट कर सकता है जिसके प्रति डिफ़ॉल्ट करता है, बस सामान्य नियमों के बजाय ऐप-विशिष्ट नियमों के साथ।
+`getSuggestions` उसी `navigation`/`selection`/`pendingSelection` स्नैपशॉट को प्राप्त करता है जिसे बिल्ट-इन हेयुरिस्टिक पढ़ता है, जो `unknown` के रूप में टाइप किया गया है क्योंकि इसका आकार ऐप-निर्धारित है, इसलिए फ़ील्ड पढ़ने से पहले इसे नैरो करें। कोई कस्टम इम्प्लीमेंटेशन उसी स्टेट के प्रति रिएक्ट कर सकता है जिसके प्रति डिफ़ॉल्ट करता है, बस सामान्य नियमों के बजाय ऐप-विशिष्ट नियमों के साथ।
 
 ## आगे क्या
 
diff --git a/packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx b/packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx
index a94d6119d7..b852033931 100644
--- a/packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/hi-IN/client-agent-chat.mdx
@@ -184,11 +184,11 @@ const answer = await askUserQuestion({
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-`postMessage` के माध्यम से एजेंट चैट पर एक मैसेज भेजें। यह वह लोअर-लेवल प्रिमिटिव है जिसे ऊपर दिया `useAgentChatGenerating()` रैप करता है, यह उपयोगी है जब किसी UI इंटरैक्शन को खुद की लोडिंग-स्टेट ट्रैकिंग की आवश्यकता नहीं होती। अतिरिक्त विवरण के लिए `context` पास करें जो मैसेज खुद नहीं बताता। यह उसी दिखने वाले मैसेज में जुड़ जाता है, `<context>` टैग में रैप्ड। यह उपयोगकर्ता से छिपा नहीं है। तुरंत भेजने के लिए `submit: true` पास करें, या एक ड्राफ्ट प्रीफिल करने के लिए `submit: false` पास करें जिसे उपयोगकर्ता पहले रिव्यू करता है।
+`postMessage` के माध्यम से एजेंट चैट पर एक मैसेज भेजें। यह वह लोअर-लेवल प्रिमिटिव है जिसे ऊपर दिया `useAgentChatGenerating()` रैप करता है, यह उपयोगी है जब किसी UI इंटरैक्शन को खुद की लोडिंग-स्टेट ट्रैकिंग की आवश्यकता नहीं होती। अतिरिक्त विवरण के लिए `context` पास करें जो मॉडल को दिखना चाहिए लेकिन उपयोगकर्ता को नहीं। यह एजेंट को भेजे गए मैसेज में जुड़ जाता है, `<context>` टैग में रैप्ड, और चैट UI में मैसेज रेंडर होने से पहले हटा दिया जाता है। तुरंत भेजने के लिए `submit: true` पास करें, या एक ड्राफ्ट प्रीफिल करने के लिए `submit: false` पास करें जिसे उपयोगकर्ता पहले रिव्यू करता है।
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// छिपे हुए कॉन्टेक्स्ट के साथ प्रॉम्प्ट को ऑटो-सबमिट करें
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -205,13 +205,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| विकल्प        | प्रकार     | विवरण                                                                                            |
-| ------------- | ---------- | ------------------------------------------------------------------------------------------------ |
-| `message`     | `string`   | चैट पर भेजा गया प्रॉम्प्ट। यदि सेट है, तो `context` इसी दिखने वाले मैसेज में जुड़ जाता है        |
-| `context`     | `string?`  | दिखने वाले मैसेज में जुड़ा अतिरिक्त विवरण, `<context>` टैग में रैप्ड। उपयोगकर्ता से छिपा नहीं है |
-| `submit`      | `boolean?` | true = ऑटो-सबमिट, false = केवल प्रीफिल                                                           |
-| `newTab`      | `boolean?` | इस प्रॉम्प्ट के लिए एक अलग चैट थ्रेड बनाएं                                                       |
-| `openSidebar` | `boolean?` | साइडबार खोले बिना सबमिट/प्रीफिल करने के लिए false सेट करें                                       |
+| विकल्प        | प्रकार     | विवरण                                                                                           |
+| ------------- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | चैट पर भेजा गया प्रॉम्प्ट, और चैट UI में दिखने वाला एकमात्र हिस्सा                              |
+| `context`     | `string?`  | भेजने से पहले मैसेज में जोड़ा गया मॉडल-विज़िबल कॉन्टेक्स्ट। चैट UI डिस्प्ले से हटा दिया जाता है |
+| `submit`      | `boolean?` | true = ऑटो-सबमिट, false = केवल प्रीफिल                                                          |
+| `newTab`      | `boolean?` | इस प्रॉम्प्ट के लिए एक अलग चैट थ्रेड बनाएं                                                      |
+| `openSidebar` | `boolean?` | साइडबार खोले बिना सबमिट/प्रीफिल करने के लिए false सेट करें                                      |
 
 इसी रूट को MCP App के रूप में एम्बेड करने से, या साइडबार खोले बिना रन को बैकग्राउंड में ले जाने से जुड़ी बातें [उन्नत](/docs/client-advanced#background-send) में कवर की गई हैं।
 
diff --git a/packages/core/docs/content/locales/ja-JP/client-advanced.mdx b/packages/core/docs/content/locales/ja-JP/client-advanced.mdx
index 861953af1c..81601a4102 100644
--- a/packages/core/docs/content/locales/ja-JP/client-advanced.mdx
+++ b/packages/core/docs/content/locales/ja-JP/client-advanced.mdx
@@ -148,22 +148,30 @@ import {
 
 ## カスタム提案チップ {#custom-suggestions}
 
-`<AgentSidebar>` の `dynamicSuggestions` ([Agent チャット](/docs/client-agent-chat#dynamic-suggestions) を参照) は、既に静的な `suggestions` とフレームワーク自身のコンテキスト認識ヒューリスティックをマージしています。フレームワークのデフォルトのヒューリスティックの代わりに、同じ `application_state` のコンテキストから計算された決定論的でドメイン固有のチップをアプリが求める場合は、代わりに `getSuggestions` を渡してください。
+`<AgentSidebar>` の `dynamicSuggestions` ([Agent チャット](/docs/client-agent-chat#dynamic-suggestions) を参照) は、既に静的な `suggestions` とフレームワーク自身のコンテキスト認識ヒューリスティックをマージしています。フレームワークのデフォルトのヒューリスティックの代わりに、同じ `application_state` のコンテキストから計算された決定論的でドメイン固有のチップをアプリが求める場合は、代わりに `dynamicSuggestions` の中に `getSuggestions` 関数を渡してください。
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` は、組み込みのヒューリスティックが読み取るのと同じ `navigation`/`selection`/`pending-selection-context` のスナップショットを受け取るため、カスタムの実装は、汎用的なルールの代わりにアプリ固有のルールを使って、デフォルトの実装が反応するのと全く同じ状態に反応できます。
+`getSuggestions` は、組み込みのヒューリスティックが読み取るのと同じ `navigation`/`selection`/`pendingSelection` のスナップショットを受け取りますが、その形はアプリ次第なので `unknown` として型付けされています。フィールドを読み取る前に型を絞り込んでください。カスタムの実装は、汎用的なルールの代わりにアプリ固有のルールを使って、デフォルトの実装が反応するのと全く同じ状態に反応できます。
 
 ## 次は何ですか
 
diff --git a/packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx b/packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx
index 0b4d10eb39..81ec2133fd 100644
--- a/packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/ja-JP/client-agent-chat.mdx
@@ -183,11 +183,11 @@ const answer = await askUserQuestion({
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-`postMessage` 経由でエージェント チャットにメッセージを送信します。これは `useAgentChatGenerating()` がラップしている、より低レベルのプリミティブで、UI のやり取りが自前の読み込み状態の追跡を必要としない場合に便利です。メッセージだけでは伝わらない追加の詳細には `context` を渡します。これは同じ表示メッセージに `<context>` タグで囲んで追加されます。ユーザーから隠されるわけではありません。すぐに送信するには `submit: true` を、ユーザーが最初にレビューするドラフトを事前入力するには `submit: false` を渡します。
+`postMessage` 経由でエージェント チャットにメッセージを送信します。これは `useAgentChatGenerating()` がラップしている、より低レベルのプリミティブで、UI のやり取りが自前の読み込み状態の追跡を必要としない場合に便利です。モデルには見えるがユーザーには見えるべきではない追加の詳細には `context` を渡します。これはエージェントに送信されるメッセージに `<context>` タグで囲んで追加され、チャット UI にメッセージがレンダリングされる前に取り除かれます。すぐに送信するには `submit: true` を、ユーザーが最初にレビューするドラフトを事前入力するには `submit: false` を渡します。
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// 隠しコンテキスト付きでプロンプトを自動送信
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -204,13 +204,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| オプション    | タイプ     | 説明                                                                                                 |
-| ------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
-| `message`     | `string`   | チャットに送信されるプロンプト。設定されている場合、`context` はこの同じ表示メッセージに追加されます |
-| `context`     | `string?`  | 表示メッセージに `<context>` タグで囲んで追加される追加の詳細。ユーザーから隠されない                |
-| `submit`      | `boolean?` | true = 自動送信、false = 事前入力のみ                                                                |
-| `newTab`      | `boolean?` | このプロンプト用に別のチャット スレッドを作成する                                                    |
-| `openSidebar` | `boolean?` | サイドバーを開かずに送信/事前入力するには false を設定                                               |
+| オプション    | タイプ     | 説明                                                                                             |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------ |
+| `message`     | `string`   | チャットに送信されるプロンプト。チャット UI に表示される唯一の部分                               |
+| `context`     | `string?`  | 送信前にメッセージに追加される、モデルに見えるコンテキスト。チャット UI の表示からは取り除かれる |
+| `submit`      | `boolean?` | true = 自動送信、false = 事前入力のみ                                                            |
+| `newTab`      | `boolean?` | このプロンプト用に別のチャット スレッドを作成する                                                |
+| `openSidebar` | `boolean?` | サイドバーを開かずに送信/事前入力するには false を設定                                           |
 
 MCP アプリ埋め込み内からこれを実行する場合や、サイドバーを開かずに実行をバックグラウンドに送る方法は、いずれも [高度](/docs/client-advanced#background-send) で扱っています。
 
diff --git a/packages/core/docs/content/locales/ko-KR/client-advanced.mdx b/packages/core/docs/content/locales/ko-KR/client-advanced.mdx
index 9f41b0836f..aa50df5a5c 100644
--- a/packages/core/docs/content/locales/ko-KR/client-advanced.mdx
+++ b/packages/core/docs/content/locales/ko-KR/client-advanced.mdx
@@ -179,24 +179,33 @@ import {
 이미 고정된 `suggestions`를 프레임워크 자체의 컨텍스트 인식 휴리스틱과
 병합합니다. 프레임워크의 기본 휴리스틱 대신 동일한 `application_state`
 컨텍스트로부터 계산된 결정론적이고 도메인 특화된 칩을 앱이 원할 때는
-`getSuggestions`를 전달하세요.
+`dynamicSuggestions` 안에 `getSuggestions` 함수를 전달하세요.
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions`는 내장 휴리스틱이 읽는 것과 동일한 `navigation`/`selection`/`pending-selection-context`
-스냅샷을 받으므로, 커스텀 구현이 기본 구현과 정확히 같은 상태에 반응하되
-일반적인 규칙이 아닌 앱 전용 규칙으로 반응할 수 있습니다.
+`getSuggestions`는 내장 휴리스틱이 읽는 것과 동일한 `navigation`/`selection`/`pendingSelection`
+스냅샷을 받지만, 모양이 앱마다 다르므로 `unknown`으로 타입이 지정되어 있습니다.
+필드를 읽기 전에 타입을 좁혀야 합니다. 커스텀 구현은 기본 구현과 정확히 같은
+상태에 반응하되 일반적인 규칙이 아닌 앱 전용 규칙으로 반응할 수 있습니다.
 
 ## 다음 단계
 
diff --git a/packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx b/packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx
index ae52185f93..3d993840fe 100644
--- a/packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/ko-KR/client-agent-chat.mdx
@@ -185,11 +185,11 @@ const answer = await askUserQuestion({
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-`postMessage`를 통해 에이전트 채팅에 메시지를 보냅니다. 이는 위의 `useAgentChatGenerating()`이 감싸고 있는 더 저수준의 기본 요소로, UI 상호작용이 자체적인 로딩 상태 추적을 필요로 하지 않을 때 유용합니다. 메시지만으로는 전달되지 않는 추가적인 세부 정보에는 `context`를 전달하세요. 이는 동일한 표시 메시지에 `<context>` 태그로 감싸여 덧붙여집니다. 사용자에게 숨겨지지 않습니다. 즉시 전송하려면 `submit: true`를, 사용자가 먼저 검토할 초안을 미리 채우려면 `submit: false`를 전달하세요.
+`postMessage`를 통해 에이전트 채팅에 메시지를 보냅니다. 이는 위의 `useAgentChatGenerating()`이 감싸고 있는 더 저수준의 기본 요소로, UI 상호작용이 자체적인 로딩 상태 추적을 필요로 하지 않을 때 유용합니다. 모델은 봐야 하지만 사용자는 보지 않아야 하는 추가 세부 정보에는 `context`를 전달하세요. 이는 에이전트로 전송되는 메시지에 `<context>` 태그로 감싸여 추가되며, 채팅 UI에 메시지가 렌더링되기 전에 다시 제거됩니다. 즉시 전송하려면 `submit: true`를, 사용자가 먼저 검토할 초안을 미리 채우려면 `submit: false`를 전달하세요.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// 숨겨진 컨텍스트로 프롬프트 자동 전송
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -206,13 +206,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| 옵션          | 유형       | 설명                                                                                                   |
-| ------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
-| `message`     | `string`   | 채팅에 전송되는 프롬프트입니다. `context`가 설정되어 있으면 동일한 표시 메시지에 덧붙여집니다          |
-| `context`     | `string?`  | 표시 메시지에 덧붙여지는 추가 세부 정보로, `<context>` 태그로 감싸집니다. 사용자에게 숨겨지지 않습니다 |
-| `submit`      | `boolean?` | true = 자동 제출, false = 미리 채우기만                                                                |
-| `newTab`      | `boolean?` | 이 프롬프트를 위한 별도의 채팅 스레드를 생성합니다                                                     |
-| `openSidebar` | `boolean?` | 사이드바를 열지 않고 제출/미리 채우려면 false로 설정하세요                                             |
+| 옵션          | 유형       | 설명                                                                                        |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | 채팅에 전송되는 프롬프트이며, 채팅 UI에 표시되는 유일한 부분입니다                          |
+| `context`     | `string?`  | 전송 전에 메시지에 추가되는 모델에게만 보이는 컨텍스트입니다. 채팅 UI 표시에서는 제거됩니다 |
+| `submit`      | `boolean?` | true = 자동 제출, false = 미리 채우기만                                                     |
+| `newTab`      | `boolean?` | 이 프롬프트를 위한 별도의 채팅 스레드를 생성합니다                                          |
+| `openSidebar` | `boolean?` | 사이드바를 열지 않고 제출/미리 채우려면 false로 설정하세요                                  |
 
 MCP 앱 임베드 내부에서 이를 실행하는 경우, 또는 사이드바를 열지 않고 실행을 백그라운드로 보내는 경우는 모두 [고급](/docs/client-advanced#background-send)에서 다룹니다.
 
diff --git a/packages/core/docs/content/locales/pt-BR/client-advanced.mdx b/packages/core/docs/content/locales/pt-BR/client-advanced.mdx
index b9ff8b5250..32d1d66a31 100644
--- a/packages/core/docs/content/locales/pt-BR/client-advanced.mdx
+++ b/packages/core/docs/content/locales/pt-BR/client-advanced.mdx
@@ -163,22 +163,30 @@ solicitações de modo de exibição, é de responsabilidade de
 
 ## Chips de sugestão personalizados {#custom-suggestions}
 
-`dynamicSuggestions` de `<AgentSidebar>` (veja [Chat do Agent](/docs/client-agent-chat#dynamic-suggestions)) já mescla as `suggestions` estáticas com a heurística de reconhecimento de contexto própria da estrutura. Passe `getSuggestions` em vez disso quando um aplicativo quiser chips determinísticos e específicos do domínio, calculados a partir do mesmo contexto de `application_state`, em vez da heurística padrão da estrutura.
+`dynamicSuggestions` de `<AgentSidebar>` (veja [Chat do Agent](/docs/client-agent-chat#dynamic-suggestions)) já mescla as `suggestions` estáticas com a heurística de reconhecimento de contexto própria da estrutura. Passe uma função `getSuggestions` dentro de `dynamicSuggestions` em vez disso quando um aplicativo quiser chips determinísticos e específicos do domínio, calculados a partir do mesmo contexto de `application_state`, em vez da heurística padrão da estrutura.
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` recebe o mesmo snapshot de `navigation`/`selection`/`pending-selection-context` que a heurística integrada lê, então uma implementação personalizada pode reagir exatamente ao mesmo estado que a padrão reage, apenas com regras específicas do aplicativo em vez de regras genéricas.
+`getSuggestions` recebe o mesmo snapshot de `navigation`/`selection`/`pendingSelection` que a heurística integrada lê, tipado como `unknown` porque o formato é definido pelo aplicativo, então é preciso restringi-lo antes de ler seus campos. Uma implementação personalizada pode reagir exatamente ao mesmo estado que a padrão reage, apenas com regras específicas do aplicativo em vez de regras genéricas.
 
 ## O que vem a seguir
 
diff --git a/packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx b/packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx
index ad7692ad32..66ec7d4d9e 100644
--- a/packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/pt-BR/client-agent-chat.mdx
@@ -185,11 +185,11 @@ Combinar isto com o exemplo de `askUserQuestion()` acima completa o manipulador
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-Envie uma mensagem para o chat do agente via `postMessage`. Esta é a primitiva de nível mais baixo que `useAgentChatGenerating()` acima encapsula, útil quando uma interação de UI não precisa de rastreamento de estado de carregamento próprio. Passe `context` para detalhes extras que a mensagem por si só não carrega. Ele é anexado à mesma mensagem visível, envolvido em tags `<context>`. Não fica oculto do usuário. Passe `submit: true` para enviar imediatamente, ou `submit: false` para preencher previamente um rascunho que o usuário revisa primeiro.
+Envie uma mensagem para o chat do agente via `postMessage`. Esta é a primitiva de nível mais baixo que `useAgentChatGenerating()` acima encapsula, útil quando uma interação de UI não precisa de rastreamento de estado de carregamento próprio. Passe `context` para detalhes extras que o modelo deve ver, mas o usuário não. Ele é anexado à mensagem enviada ao agente, envolvido em tags `<context>`, e é removido antes que a mensagem seja renderizada na UI do chat. Passe `submit: true` para enviar imediatamente, ou `submit: false` para preencher previamente um rascunho que o usuário revisa primeiro.
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// Enviar automaticamente um prompt com contexto oculto
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -206,13 +206,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| Opção         | Tipo       | Descrição                                                                                           |
-| ------------- | ---------- | --------------------------------------------------------------------------------------------------- |
-| `message`     | `string`   | O prompt enviado ao chat. `context`, se definido, é anexado a esta mesma mensagem visível           |
-| `context`     | `string?`  | Detalhe extra anexado à mensagem visível, envolvido em tags `<context>`. Não fica oculto do usuário |
-| `submit`      | `boolean?` | true = envio automático, false = apenas preenchimento prévio                                        |
-| `newTab`      | `boolean?` | Cria uma thread de chat separada para este prompt                                                   |
-| `openSidebar` | `boolean?` | Defina como false para enviar/preencher sem abrir a barra lateral                                   |
+| Opção         | Tipo       | Descrição                                                                                         |
+| ------------- | ---------- | ------------------------------------------------------------------------------------------------- |
+| `message`     | `string`   | O prompt enviado ao chat, e a única parte exibida na UI do chat                                   |
+| `context`     | `string?`  | Contexto visível ao modelo, anexado à mensagem antes do envio. Removido da exibição da UI do chat |
+| `submit`      | `boolean?` | true = envio automático, false = apenas preenchimento prévio                                      |
+| `newTab`      | `boolean?` | Cria uma thread de chat separada para este prompt                                                 |
+| `openSidebar` | `boolean?` | Defina como false para enviar/preencher sem abrir a barra lateral                                 |
 
 Executar isso de dentro de um embed de MCP App, ou colocar a execução em segundo plano sem abrir a barra lateral, ambos são cobertos em [Avançado](/docs/client-advanced#background-send).
 
diff --git a/packages/core/docs/content/locales/zh-CN/client-advanced.mdx b/packages/core/docs/content/locales/zh-CN/client-advanced.mdx
index d5898c1d8e..41413b66d0 100644
--- a/packages/core/docs/content/locales/zh-CN/client-advanced.mdx
+++ b/packages/core/docs/content/locales/zh-CN/client-advanced.mdx
@@ -148,22 +148,30 @@ import {
 
 ## 自定义建议芯片 {#custom-suggestions}
 
-`<AgentSidebar>` 的 `dynamicSuggestions`（见 [Agent 聊天](/docs/client-agent-chat#dynamic-suggestions)）已经将静态 `suggestions` 与框架自身的上下文感知启发式规则合并在一起。当应用希望从同一份 `application_state` 上下文中计算出确定性的、领域专属的芯片，而不是使用框架的默认启发式规则时，改为传入 `getSuggestions`。
+`<AgentSidebar>` 的 `dynamicSuggestions`（见 [Agent 聊天](/docs/client-agent-chat#dynamic-suggestions)）已经将静态 `suggestions` 与框架自身的上下文感知启发式规则合并在一起。当应用希望从同一份 `application_state` 上下文中计算出确定性的、领域专属的芯片，而不是使用框架的默认启发式规则时，改为在 `dynamicSuggestions` 内传入 `getSuggestions` 函数。
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` 接收到的，与内置启发式规则读取的是同一份 `navigation`/`selection`/`pending-selection-context` 快照，因此自定义实现可以对与默认实现完全相同的状态做出反应，只是使用应用专属的规则，而不是通用规则。
+`getSuggestions` 接收到的，与内置启发式规则读取的是同一份 `navigation`/`selection`/`pendingSelection` 快照，但其类型为 `unknown`，因为具体形状由应用决定，所以读取字段前需要先做类型收窄。自定义实现可以对与默认实现完全相同的状态做出反应，只是使用应用专属的规则，而不是通用规则。
 
 ## 下一步
 
diff --git a/packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx b/packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx
index ae2fdb2b3c..6d13f64215 100644
--- a/packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/zh-CN/client-agent-chat.mdx
@@ -182,11 +182,11 @@ const answer = await askUserQuestion({
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-通过 `postMessage` 向代理聊天发送一条消息。这是上面 `useAgentChatGenerating()` 所包装的更底层原语，适用于 UI 交互本身不需要加载状态跟踪的场景。传入 `context` 可以携带消息本身无法承载的额外细节，它会被追加到同一条可见消息中，并用 `<context>` 标签包裹——对用户并不隐藏。传入 `submit: true` 立即发送，或传入 `submit: false` 预填充一份草稿供用户先审阅。
+通过 `postMessage` 向代理聊天发送一条消息。这是上面 `useAgentChatGenerating()` 所包装的更底层原语，适用于 UI 交互本身不需要加载状态跟踪的场景。传入 `context` 可以携带模型应该看到但用户不应看到的额外细节。它会被追加到发送给代理的消息中，并用 `<context>` 标签包裹，在消息渲染到聊天界面之前会被移除。传入 `submit: true` 立即发送，或传入 `submit: false` 预填充一份草稿供用户先审阅。
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// 使用隐藏上下文自动提交提示
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -203,13 +203,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| 选项          | 类型       | 描述                                                                   |
-| ------------- | ---------- | ---------------------------------------------------------------------- |
-| `message`     | `string`   | 发送到聊天中的提示。如果设置了 `context`，会被追加到这同一条可见消息中 |
-| `context`     | `string?`  | 追加到可见消息中的额外细节，用 `<context>` 标签包裹。对用户并不隐藏    |
-| `submit`      | `boolean?` | true = 自动提交，false = 仅预填充                                      |
-| `newTab`      | `boolean?` | 为此提示创建一个单独的聊天线程                                         |
-| `openSidebar` | `boolean?` | 设为 false 可在不打开侧边栏的情况下提交/预填充                         |
+| 选项          | 类型       | 描述                                                           |
+| ------------- | ---------- | -------------------------------------------------------------- |
+| `message`     | `string`   | 发送到聊天中的提示，也是聊天界面中唯一显示的部分               |
+| `context`     | `string?`  | 发送前追加到消息中的、模型可见的上下文。会从聊天界面显示中移除 |
+| `submit`      | `boolean?` | true = 自动提交，false = 仅预填充                              |
+| `newTab`      | `boolean?` | 为此提示创建一个单独的聊天线程                                 |
+| `openSidebar` | `boolean?` | 设为 false 可在不打开侧边栏的情况下提交/预填充                 |
 
 在 MCP App embed 内部运行它，或者在不打开侧边栏的情况下将运行放到后台，这两种情况都在 [高级](/docs/client-advanced#background-send) 中有介绍。
 
diff --git a/packages/core/docs/content/locales/zh-TW/client-advanced.mdx b/packages/core/docs/content/locales/zh-TW/client-advanced.mdx
index 90ba05ff38..5ba9196d84 100644
--- a/packages/core/docs/content/locales/zh-TW/client-advanced.mdx
+++ b/packages/core/docs/content/locales/zh-TW/client-advanced.mdx
@@ -163,22 +163,30 @@ import {
 
 ## 自訂建議標籤 {#custom-suggestions}
 
-`<AgentSidebar>` 的 `dynamicSuggestions`（請參閱[Agent 聊天](/docs/client-agent-chat#dynamic-suggestions)）已經將靜態 `suggestions` 與框架自身的脈絡感知啟發式方法合併。當應用程式想要根據相同的 `application_state` 脈絡計算出確定性、特定領域的標籤，而非使用框架的預設啟發式方法時，改傳入 `getSuggestions`。
+`<AgentSidebar>` 的 `dynamicSuggestions`（請參閱[Agent 聊天](/docs/client-agent-chat#dynamic-suggestions)）已經將靜態 `suggestions` 與框架自身的脈絡感知啟發式方法合併。當應用程式想要根據相同的 `application_state` 脈絡計算出確定性、特定領域的標籤，而非使用框架的預設啟發式方法時，改在 `dynamicSuggestions` 內傳入 `getSuggestions` 函式。
 
 ```tsx
 <AgentSidebar
   suggestions={["Summarize my inbox"]}
-  getSuggestions={(state) =>
-    state.navigation?.view === "inbox"
-      ? [`Summarize ${state.navigation.label ?? "this"} label`]
-      : []
-  }
+  dynamicSuggestions={{
+    getSuggestions: ({ navigation }) => {
+      if (
+        typeof navigation !== "object" ||
+        navigation === null ||
+        (navigation as { view?: unknown }).view !== "inbox"
+      ) {
+        return [];
+      }
+      const label = (navigation as { label?: unknown }).label;
+      return [`Summarize ${typeof label === "string" ? label : "this"} label`];
+    },
+  }}
 >
   <App />
 </AgentSidebar>
 ```
 
-`getSuggestions` 收到的 `navigation`/`selection`/`pending-selection-context` 快照，與內建啟發式方法讀取的完全相同，因此自訂實作可以對內建方法所讀取的相同狀態做出反應，只是使用應用專屬的規則，而非通用規則。
+`getSuggestions` 收到的 `navigation`/`selection`/`pendingSelection` 快照，與內建啟發式方法讀取的完全相同，但其型別為 `unknown`，因為形狀由應用程式決定，因此讀取欄位前需要先縮小型別。自訂實作可以對內建方法所讀取的相同狀態做出反應，只是使用應用專屬的規則，而非通用規則。
 
 ## 下一步是什麼
 
diff --git a/packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx b/packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx
index 6f9deda6f3..69eef58ff5 100644
--- a/packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx
+++ b/packages/core/docs/content/locales/zh-TW/client-agent-chat.mdx
@@ -181,11 +181,11 @@ const answer = await askUserQuestion({
 
 ## sendToAgentChat(opts) {#sendtoagentchat}
 
-透過 `postMessage` 向代理聊天傳送一則訊息。這是 `useAgentChatGenerating()` 在上方包裝的較低階原語，適用於不需要自己的載入狀態追蹤的 UI 互動。傳入 `context` 以提供訊息本身未涵蓋的額外細節。它會被附加到同一則可見訊息上，並用 `<context>` 標籤包裹。它並不會對使用者隱藏。傳入 `submit: true` 立即傳送，或傳入 `submit: false` 預填一份草稿供使用者先審閱。
+透過 `postMessage` 向代理聊天傳送一則訊息。這是 `useAgentChatGenerating()` 在上方包裝的較低階原語，適用於不需要自己的載入狀態追蹤的 UI 互動。傳入 `context` 以提供模型應該看到但使用者不應該看到的額外細節。它會被附加到傳送給代理的訊息上，並用 `<context>` 標籤包裹，在訊息呈現於聊天介面之前會被移除。傳入 `submit: true` 立即傳送，或傳入 `submit: false` 預填一份草稿供使用者先審閱。
 
 ```ts
 import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-// Auto-submit a prompt with appended context
+// 使用隱藏內容自動提交提示
 sendToAgentChat({
   message: "Generate alt text for this image",
   context: "Image path: /api/projects/hero.jpg",
@@ -202,13 +202,13 @@ sendToAgentChat({
 
 ### AgentChatMessage {#agentchatmessage}
 
-| 選項          | 型別       | 描述                                                                |
-| ------------- | ---------- | ------------------------------------------------------------------- |
-| `message`     | `string`   | 傳送到聊天的提示。若設定了 `context`，會附加到同一則可見訊息上      |
-| `context`     | `string?`  | 附加到可見訊息的額外細節，用 `<context>` 標籤包裹。不會對使用者隱藏 |
-| `submit`      | `boolean?` | true = 自動提交，false = 僅預填                                     |
-| `newTab`      | `boolean?` | 為此提示建立一個獨立的聊天對話串                                    |
-| `openSidebar` | `boolean?` | 設為 false 可在不開啟側邊欄的情況下提交/預填                        |
+| 選項          | 型別       | 描述                                                     |
+| ------------- | ---------- | -------------------------------------------------------- |
+| `message`     | `string`   | 傳送到聊天的提示，也是聊天介面中唯一顯示的部分           |
+| `context`     | `string?`  | 傳送前附加到訊息中的模型可見內容。會從聊天介面顯示中移除 |
+| `submit`      | `boolean?` | true = 自動提交，false = 僅預填                          |
+| `newTab`      | `boolean?` | 為此提示建立一個獨立的聊天對話串                         |
+| `openSidebar` | `boolean?` | 設為 false 可在不開啟側邊欄的情況下提交/預填             |
 
 從 MCP App 嵌入內部執行此操作，或在不開啟側邊欄的情況下將執行放到背景，這兩者都在[進階](/docs/client-advanced#background-send)中涵蓋。
 
diff --git a/packages/core/src/client/hooks/index.ts b/packages/core/src/client/hooks/index.ts
index ebbe8558a1..4ac1a5b182 100644
--- a/packages/core/src/client/hooks/index.ts
+++ b/packages/core/src/client/hooks/index.ts
@@ -2,8 +2,10 @@ export { getBrowserTabId } from "../browser-tab-id.js";
 export {
   deleteClientAppState,
   readClientAppState,
+  readClientAppStateMany,
   setClientAppState,
   writeClientAppState,
+  type ClientAppStateBatch,
   type ClientAppStateReadOptions,
   type ClientAppStateWriteOptions,
 } from "../application-state.js";
diff --git a/packages/docs/app/components/blocks/media-shared.test.ts b/packages/docs/app/components/blocks/media-shared.test.ts
new file mode 100644
index 0000000000..e9ce675818
--- /dev/null
+++ b/packages/docs/app/components/blocks/media-shared.test.ts
@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+
+import { mediaSrcSchema } from "./media-shared";
+
+describe("mediaSrcSchema", () => {
+  it.each(["/images/foo.png", "/videos/demo.mp4", "/"])(
+    "accepts an absolute local path: %s",
+    (src) => {
+      expect(mediaSrcSchema.safeParse(src).success).toBe(true);
+    },
+  );
+
+  it.each([
+    "https://cdn.example.com/foo.mp4",
+    "http://cdn.example.com/foo.mp4",
+  ])("accepts an http(s) URL: %s", (src) => {
+    expect(mediaSrcSchema.safeParse(src).success).toBe(true);
+  });
+
+  it.each([
+    "//attacker.example/media.mp4",
+    "//attacker.example",
+    "javascript:alert(1)",
+    "data:text/html,<script>alert(1)</script>",
+    "file:///etc/passwd",
+    "vbscript:msgbox(1)",
+  ])("rejects an unsafe or protocol-relative src: %s", (src) => {
+    expect(mediaSrcSchema.safeParse(src).success).toBe(false);
+  });
+});
diff --git a/packages/docs/app/components/blocks/media-shared.ts b/packages/docs/app/components/blocks/media-shared.ts
index 7eafbdc49d..0141fc4a21 100644
--- a/packages/docs/app/components/blocks/media-shared.ts
+++ b/packages/docs/app/components/blocks/media-shared.ts
@@ -15,7 +15,7 @@ export const mediaSrcSchema = z
   .trim()
   .min(1)
   .max(2_000)
-  .regex(/^(https?:\/\/|\/)/i, {
+  .regex(/^(https?:\/\/|\/(?!\/))/i, {
     message: "src must be an absolute path (/...) or an https URL",
   });
 
diff --git a/packages/docs/app/components/blocks/video.test.tsx b/packages/docs/app/components/blocks/video.test.tsx
new file mode 100644
index 0000000000..1ba0ab41be
--- /dev/null
+++ b/packages/docs/app/components/blocks/video.test.tsx
@@ -0,0 +1,93 @@
+// @vitest-environment jsdom
+
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { renderToStaticMarkup } from "react-dom/server";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { VideoBlock } from "./video";
+import type { VideoData } from "./video.config";
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+function baseData(overrides: Partial<VideoData> = {}): VideoData {
+  return {
+    src: "/videos/demo.mp4",
+    alt: "Demo video",
+    autoplay: true,
+    ...overrides,
+  };
+}
+
+function stubMatchMedia(matches: boolean) {
+  vi.stubGlobal(
+    "matchMedia",
+    vi.fn().mockReturnValue({
+      matches,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }),
+  );
+}
+
+describe("VideoBlock autoplay", () => {
+  it("never emits autoplay in the pre-hydration SSR markup, even when requested", () => {
+    // No `window`/`matchMedia` at all during SSR — the reduced-motion
+    // preference cannot be known yet, so autoplay must not appear in the
+    // markup a browser parses before React's effect has a chance to run.
+    // `renderToStaticMarkup` emits boolean attributes camelCased
+    // (`autoPlay=""`), so match case-insensitively rather than assuming the
+    // lowercase HTML spelling.
+    const html = renderToStaticMarkup(
+      <VideoBlock data={baseData()} ctx={{}} blockId="video" />,
+    );
+    expect(html).not.toMatch(/autoplay/i);
+    expect(html).not.toMatch(/playsinline/i);
+  });
+
+  it("keeps autoplay off once resolved to prefers-reduced-motion", async () => {
+    stubMatchMedia(true);
+    const { container } = render(
+      <VideoBlock data={baseData()} ctx={{}} blockId="video" />,
+    );
+
+    await waitFor(() => {
+      const video = container.querySelector("video");
+      expect(video?.hasAttribute("autoplay")).toBe(false);
+      // `muted` is a live media property React sets directly, not an
+      // attribute — assert via the element property, not `hasAttribute`.
+      expect((video as HTMLVideoElement | null)?.muted).toBe(false);
+    });
+  });
+
+  it("turns autoplay on only after resolving that reduced motion is not requested", async () => {
+    stubMatchMedia(false);
+    const { container } = render(
+      <VideoBlock data={baseData()} ctx={{}} blockId="video" />,
+    );
+
+    await waitFor(() => {
+      const video = container.querySelector("video");
+      expect(video?.hasAttribute("autoplay")).toBe(true);
+      expect((video as HTMLVideoElement | null)?.muted).toBe(true);
+    });
+  });
+
+  it("never autoplays when the caller did not request it, regardless of motion preference", async () => {
+    stubMatchMedia(false);
+    const { container } = render(
+      <VideoBlock
+        data={baseData({ autoplay: false })}
+        ctx={{}}
+        blockId="video"
+      />,
+    );
+
+    await waitFor(() => {
+      const video = container.querySelector("video");
+      expect(video?.hasAttribute("autoplay")).toBe(false);
+    });
+  });
+});
diff --git a/packages/docs/app/components/blocks/video.tsx b/packages/docs/app/components/blocks/video.tsx
index 63b35bee02..e9c0192212 100644
--- a/packages/docs/app/components/blocks/video.tsx
+++ b/packages/docs/app/components/blocks/video.tsx
@@ -8,15 +8,21 @@ import { videoSchema, videoMdx, type VideoData } from "./video.config";
 export type { VideoData };
 
 /**
- * Tracks `prefers-reduced-motion: reduce`. Starts `false` (matches SSR, where
- * there's no `window` to ask) and updates after mount, so a reduced-motion
- * viewer never sees a flash of autoplay before it's suppressed.
+ * Tracks `prefers-reduced-motion: reduce`. Starts `null` (unresolved — SSR
+ * and the first client paint have no answer yet) and only resolves to
+ * `true`/`false` once the `matchMedia` effect runs after mount. Autoplay must
+ * treat `null` as "not yet safe to play": a reduced-motion browser can start
+ * an `autoPlay` video the instant it's in the DOM, and removing the prop on a
+ * later render does not reliably stop playback already in progress.
  */
-function usePrefersReducedMotion(): boolean {
-  const [reduced, setReduced] = useState(false);
+function usePrefersReducedMotion(): boolean | null {
+  const [reduced, setReduced] = useState<boolean | null>(null);
 
   useEffect(() => {
-    if (typeof window === "undefined" || !window.matchMedia) return;
+    if (typeof window === "undefined" || !window.matchMedia) {
+      setReduced(false);
+      return;
+    }
     const query = window.matchMedia("(prefers-reduced-motion: reduce)");
     setReduced(query.matches);
     const onChange = (event: MediaQueryListEvent) => setReduced(event.matches);
@@ -29,11 +35,13 @@ function usePrefersReducedMotion(): boolean {
 
 export function VideoBlock({ data, ctx }: BlockReadProps<VideoData>) {
   const prefersReducedMotion = usePrefersReducedMotion();
-  // Autoplay only fires when requested AND the viewer hasn't asked for less
-  // motion. Muted/playsInline are tied to that same resolved decision, not to
-  // the raw `autoplay` flag: a reduced-motion viewer who presses play
-  // themselves gets a normal, unmuted playback, not a silently-muted one.
-  const shouldAutoplay = Boolean(data.autoplay) && !prefersReducedMotion;
+  // Autoplay only fires once the reduced-motion preference has actually
+  // resolved (not `null`) AND it came back `false`. Muted/playsInline are
+  // tied to that same resolved decision, not to the raw `autoplay` flag: a
+  // reduced-motion viewer who presses play themselves gets a normal,
+  // unmuted playback, not a silently-muted one.
+  const shouldAutoplay =
+    Boolean(data.autoplay) && prefersReducedMotion === false;
 
   return (
     <MediaFrame

From 1949280fb176721a959a68cb59d931fba0f08c20 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Tue, 11 Aug 2026 10:18:00 -0700
Subject: [PATCH 18/22] chore: sync template frontend-design skill after merge
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Leftover from resolving the sync-workspace-core-skills.ts merge conflict —
pnpm sync:workspace-skills also updates the per-template shared-skill copies
under templates/*/.agents/skills/, which I missed staging alongside the
packages/core/src/templates/ copies in the merge commit.
---
 templates/analytics/.agents/skills/frontend-design/SKILL.md | 5 +++++
 templates/assets/.agents/skills/frontend-design/SKILL.md    | 5 +++++
 templates/brain/.agents/skills/frontend-design/SKILL.md     | 5 +++++
 templates/calendar/.agents/skills/frontend-design/SKILL.md  | 5 +++++
 templates/chat/.agents/skills/frontend-design/SKILL.md      | 5 +++++
 templates/clips/.agents/skills/frontend-design/SKILL.md     | 5 +++++
 templates/content/.agents/skills/frontend-design/SKILL.md   | 5 +++++
 templates/design/.agents/skills/frontend-design/SKILL.md    | 5 +++++
 templates/dispatch/.agents/skills/frontend-design/SKILL.md  | 5 +++++
 templates/factory/.agents/skills/frontend-design/SKILL.md   | 5 +++++
 templates/forms/.agents/skills/frontend-design/SKILL.md     | 5 +++++
 templates/macros/.agents/skills/frontend-design/SKILL.md    | 5 +++++
 templates/mail/.agents/skills/frontend-design/SKILL.md      | 5 +++++
 templates/plan/.agents/skills/frontend-design/SKILL.md      | 5 +++++
 templates/slides/.agents/skills/frontend-design/SKILL.md    | 5 +++++
 templates/tasks/.agents/skills/frontend-design/SKILL.md     | 5 +++++
 16 files changed, 80 insertions(+)

diff --git a/templates/analytics/.agents/skills/frontend-design/SKILL.md b/templates/analytics/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/analytics/.agents/skills/frontend-design/SKILL.md
+++ b/templates/analytics/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/assets/.agents/skills/frontend-design/SKILL.md b/templates/assets/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/assets/.agents/skills/frontend-design/SKILL.md
+++ b/templates/assets/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/brain/.agents/skills/frontend-design/SKILL.md b/templates/brain/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/brain/.agents/skills/frontend-design/SKILL.md
+++ b/templates/brain/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/calendar/.agents/skills/frontend-design/SKILL.md b/templates/calendar/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/calendar/.agents/skills/frontend-design/SKILL.md
+++ b/templates/calendar/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/chat/.agents/skills/frontend-design/SKILL.md b/templates/chat/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/chat/.agents/skills/frontend-design/SKILL.md
+++ b/templates/chat/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/clips/.agents/skills/frontend-design/SKILL.md b/templates/clips/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/clips/.agents/skills/frontend-design/SKILL.md
+++ b/templates/clips/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/content/.agents/skills/frontend-design/SKILL.md b/templates/content/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/content/.agents/skills/frontend-design/SKILL.md
+++ b/templates/content/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/design/.agents/skills/frontend-design/SKILL.md b/templates/design/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/design/.agents/skills/frontend-design/SKILL.md
+++ b/templates/design/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/dispatch/.agents/skills/frontend-design/SKILL.md b/templates/dispatch/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/dispatch/.agents/skills/frontend-design/SKILL.md
+++ b/templates/dispatch/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/factory/.agents/skills/frontend-design/SKILL.md b/templates/factory/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/factory/.agents/skills/frontend-design/SKILL.md
+++ b/templates/factory/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/forms/.agents/skills/frontend-design/SKILL.md b/templates/forms/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/forms/.agents/skills/frontend-design/SKILL.md
+++ b/templates/forms/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/macros/.agents/skills/frontend-design/SKILL.md b/templates/macros/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/macros/.agents/skills/frontend-design/SKILL.md
+++ b/templates/macros/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/mail/.agents/skills/frontend-design/SKILL.md b/templates/mail/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/mail/.agents/skills/frontend-design/SKILL.md
+++ b/templates/mail/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/plan/.agents/skills/frontend-design/SKILL.md b/templates/plan/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/plan/.agents/skills/frontend-design/SKILL.md
+++ b/templates/plan/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/slides/.agents/skills/frontend-design/SKILL.md b/templates/slides/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/slides/.agents/skills/frontend-design/SKILL.md
+++ b/templates/slides/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
diff --git a/templates/tasks/.agents/skills/frontend-design/SKILL.md b/templates/tasks/.agents/skills/frontend-design/SKILL.md
index 7621834eed..a69883599b 100644
--- a/templates/tasks/.agents/skills/frontend-design/SKILL.md
+++ b/templates/tasks/.agents/skills/frontend-design/SKILL.md
@@ -168,6 +168,11 @@ the useful information remains dense and scannable.
 - Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
 - Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
 - Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Never guess a Tabler icon name. Names like `IconPartyPopper` or `IconConfettiCannon` feel
+  plausible but don't exist and crash Vite with a "Named export not found" error. Before importing
+  an icon you haven't used elsewhere in this app, confirm it exists by grepping
+  `node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts` (or the package's icon list)
+  for the exact name, and pick the closest real match if your first guess isn't there.
 - Keep inline help/info glyphs next to labels at `size-3` (12px) or smaller than the adjacent text. Preserve a larger hit area on the trigger, not the glyph. Use `guard:allow-large-help-icon` only for deliberate heading documentation or menu action exceptions.
 - Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
 - Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.

From 406c0b4421cfbf670325c7aa20fde0080002f48e Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Wed, 12 Aug 2026 10:36:11 -0700
Subject: [PATCH 19/22] fix: detect MDX blocks whose opening tag has no
 same-line attributes

hasDocBlockSyntax only matched a JSX opening tag when something followed
the tag name on the same line, so pages authoring blocks with the tag name
alone on its own line (e.g. client-agent-chat.mdx) fell back to plain
markdown rendering, showing every block as raw escaped JSX text instead of
its component.
---
 packages/docs/app/components/doc-block-detection.test.ts | 1 +
 packages/docs/app/components/doc-block-detection.ts      | 2 +-
 2 files changed, 2 insertions(+), 1 deletion(-)

diff --git a/packages/docs/app/components/doc-block-detection.test.ts b/packages/docs/app/components/doc-block-detection.test.ts
index 2604905cbd..096f7aa1d4 100644
--- a/packages/docs/app/components/doc-block-detection.test.ts
+++ b/packages/docs/app/components/doc-block-detection.test.ts
@@ -8,6 +8,7 @@ describe("hasDocBlockSyntax", () => {
     "```mermaid\ngraph TD\n```",
     '<Diagram title="Request lifecycle" />',
     "  <OpenApiSpec>\n  </OpenApiSpec>",
+    '<AnnotatedCode\n  id="x"\n  code={\n    "const value = 1;"\n  }\n/>',
   ])("detects %s", (markdown) => {
     expect(hasDocBlockSyntax(markdown)).toBe(true);
   });
diff --git a/packages/docs/app/components/doc-block-detection.ts b/packages/docs/app/components/doc-block-detection.ts
index 6cfd001987..fca657d605 100644
--- a/packages/docs/app/components/doc-block-detection.ts
+++ b/packages/docs/app/components/doc-block-detection.ts
@@ -5,7 +5,7 @@
  */
 const FENCE_PATTERN = /^\s*(`{3,}|~{3,})/;
 const VISUAL_FENCE_PATTERN = /^\s*`{3,}\s*(?:an-[\w-]+|mermaid)\b/;
-const MDX_COMPONENT_PATTERN = /^\s*<[A-Z][A-Za-z0-9-]*(?:\s|\/?>)/;
+const MDX_COMPONENT_PATTERN = /^\s*<[A-Z][A-Za-z0-9-]*(?:\s|\/?>|$)/;
 
 export function hasDocBlockSyntax(markdown: string): boolean {
   let fenceCharacter: "`" | "~" | null = null;

From 22f70d01e41699a92bb9dc3acb827ad1bfbd5dff Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Wed, 12 Aug 2026 11:02:04 -0700
Subject: [PATCH 20/22] fix: format factory i18n spec with oxfmt

---
 templates/factory/app/factory-i18n.spec.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/templates/factory/app/factory-i18n.spec.ts b/templates/factory/app/factory-i18n.spec.ts
index c5630e5c67..d7f0adfde1 100644
--- a/templates/factory/app/factory-i18n.spec.ts
+++ b/templates/factory/app/factory-i18n.spec.ts
@@ -45,7 +45,10 @@ describe("Factory i18n catalog", () => {
   it("keeps the Factory route keys aligned across shipped locales", async () => {
     for (const [locale, messages] of Object.entries(localeMessages)) {
       for (const key of requiredKeys) {
-        expect(readKey(messages, key), `${locale} missing ${key}`).toBeDefined();
+        expect(
+          readKey(messages, key),
+          `${locale} missing ${key}`,
+        ).toBeDefined();
       }
     }
 

From c882e5f2cc0ce2ed95eeb3dd4f7edfedd9d7da44 Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Wed, 12 Aug 2026 14:47:52 -0700
Subject: [PATCH 21/22] fix: stop guard:i18n-catalogs false positive in
 SlideEditor zoom controls

Extracting the zoom-comparison expressions into named locals removes the
`>...<` comparison-operator span the raw-literal check misread as JSX text.
---
 templates/slides/app/components/editor/SlideEditor.tsx | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/templates/slides/app/components/editor/SlideEditor.tsx b/templates/slides/app/components/editor/SlideEditor.tsx
index fa416b6c63..93f02ed4bd 100644
--- a/templates/slides/app/components/editor/SlideEditor.tsx
+++ b/templates/slides/app/components/editor/SlideEditor.tsx
@@ -5003,15 +5003,17 @@ export default function SlideEditor({
   const objectOperationSelection = getObjectOperationSelection();
   const hasObjectSelection = objectOperationSelection !== null;
   const objectSelectionCount = objectOperationSelection?.elements.length ?? 0;
+  const canZoomOut = canvasZoom > MIN_CANVAS_ZOOM;
+  const canZoomIn =
+    canvasZoom < CANVAS_ZOOM_PRESETS[CANVAS_ZOOM_PRESETS.length - 1];
   const zoomControls = slide.excalidrawData
     ? undefined
     : {
         value: canvasZoom,
         onZoomOut: canvasZoomOut,
         onZoomIn: canvasZoomIn,
-        canZoomOut: canvasZoom > MIN_CANVAS_ZOOM,
-        canZoomIn:
-          canvasZoom < CANVAS_ZOOM_PRESETS[CANVAS_ZOOM_PRESETS.length - 1],
+        canZoomOut,
+        canZoomIn,
       };
 
   // Excalidraw slides have no selectable slide content, so the row collapses

From 31ab9ee1c119390fae1225a2e4c7fd3e187faf9d Mon Sep 17 00:00:00 2001
From: Wes Reid <bwreid@gmail.com>
Date: Wed, 12 Aug 2026 15:12:54 -0700
Subject: [PATCH 22/22] fix: retry standalone Chat dev startup on
 closed-connection race too

Nitro's env-runner restart during first boot can tear down the DB
connection mid-migration, surfacing as "The database connection is not
open" instead of the already-handled "database is locked"/SQLITE_BUSY
races. Same startup-race category, so retry it the same way.
---
 scripts/qa-standalone-chat-dev-smoke.ts | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/scripts/qa-standalone-chat-dev-smoke.ts b/scripts/qa-standalone-chat-dev-smoke.ts
index 13f68ce337..33663b2107 100644
--- a/scripts/qa-standalone-chat-dev-smoke.ts
+++ b/scripts/qa-standalone-chat-dev-smoke.ts
@@ -517,7 +517,8 @@ async function startDev(): Promise<RunningDev> {
       const retryable =
         !authLocked &&
         (message.includes("database is locked") ||
-          message.includes("SQLITE_BUSY"));
+          message.includes("SQLITE_BUSY") ||
+          message.includes("The database connection is not open"));
       if (!retryable || attempt === devStartAttempts - 1) throw err;
       log(
         `dev startup race (attempt ${attempt + 1}/${devStartAttempts}), retrying…`,