@agent-native/core 0.93.0 → 0.94.0

package/docs/content/real-time-collaboration.mdx

@@ -15,11 +15,10 @@ agent-native collaboration model.
 ## Vision {#vision}
 
 Editing alongside the agent feels like working in a collaborative editor with
-a coworker who is both instant and tireless:
-
-If you just need the UI to refresh when the agent or another user writes to SQL, you don't need any of this — use [`useDbSync`](/docs/client). This page is for character-level co-editing of a single rich-text document (shared cursors, conflict-free merging). Both ride the same `/_agent-native/poll` channel.
-
-This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-free merging), **TipTap** (rich text editor), and **polling-based sync** (works in all deployment environments including serverless and edge).
+a coworker who is both instant and tireless. This is built on three
+battle-tested technologies: **Yjs** (CRDT for conflict-free merging),
+**TipTap** (rich text editor), and **polling-based sync** (works in all
+deployment environments including serverless and edge).
 
 - **CRDT merging** — Concurrent edits from humans and agents merge without
   conflicts. You type in one paragraph; the agent rewrites another; both
@@ -32,6 +31,12 @@ This is built on three battle-tested technologies: **Yjs** (CRDT for conflict-fr
 - **Works everywhere** — Any SQL database Drizzle supports (SQLite, Postgres).
   Any hosting target Nitro supports, 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.
+
+</Callout>
+
 ## Architecture {#architecture}
 
 The collaboration system has five interlocking layers.
@@ -126,21 +131,18 @@ Collab update events travel via two paths:
 
 - **SSE fast-path** — The client subscribes to `/_agent-native/poll-events`
   (the same `EventSource` used by `useDbSync`). Collab update events arrive
-  push-style, typically in tens of milliseconds. While SSE is healthy the
-  poll loop relaxes to a slow cadence (~12 s by default).
-- **Polling fallback** — `/_agent-native/poll?since=N` is polled every 2 s
-  when SSE is unavailable. This makes collaboration work on any deployment
-  target — including serverless functions where persistent connections are
-  impossible and different invocations can handle different requests.
-
-Local Yjs updates are debounced and coalesced with `Y.mergeUpdates` (~80 ms)
-before being sent to the server, reducing keystroke-level network traffic.
-The batch is flushed immediately on `visibilitychange` or `pagehide`. A
-state-vector diff (`GET /:docId/state?stateVector=…`) is fetched only on
-reconnect, ring-buffer overflow, or every 15th poll cycle — not on every
-cycle.
-
-Network errors use exponential backoff with jitter, capped at ~15 s.
+  push-style, and the poll loop relaxes to a slow cadence while SSE is healthy.
+- **Polling fallback** — `/_agent-native/poll?since=N` is polled on a fixed
+  interval when SSE is unavailable. This makes collaboration work on any
+  deployment target — including serverless functions where persistent
+  connections are impossible and different invocations can handle different
+  requests.
+
+Local Yjs updates are debounced and coalesced with `Y.mergeUpdates` before
+being sent to the server, reducing keystroke-level network traffic, and the
+batch is flushed immediately on `visibilitychange` or `pagehide`. See
+[Transport and performance](#transport) for the exact intervals, state-vector
+refetch cadence, and backoff values.
 
 <Diagram id="doc-block-1h873p8" title="Two edit paths, one merge" summary={"Human keystrokes flow Y.Doc → server → SSE. Agent edits go through SQL: the action bumps updatedAt, the lead client reconciles, then the change re-enters Yjs."}>
 
@@ -258,7 +260,7 @@ export default createCollabPlugin({
 ### 4. Use the client hook
 
 ```ts
-import { useCollaborativeDoc } from "@agent-native/core/client";
+import { generateTabId, useCollaborativeDoc } from "@agent-native/core/client";
 import { emailToColor, emailToName } from "@agent-native/toolkit/collab-ui";
 
 const TAB_ID = generateTabId(); // or Math.random().toString(36)
@@ -316,25 +318,14 @@ User identity is derived from the session email. The framework provides `emailTo
 Templates can add a comments system with threaded discussions on documents. The content template's comments system includes a full implementation with:
 
 - `document_comments` SQL table (threads, replies, resolved status)
-- The content template's REST routes for update/delete at `/api/comments/:id`; create and list run through the `add-comment` / `list-comments` actions. Custom templates implement their own equivalent endpoints against the core `POST /_agent-native/collab/:docId/search-replace` route.
+- Comment create and list run through the `add-comment` / `list-comments` actions; the content template also exposes REST routes for update/delete at `/api/comments/:id`. Custom templates can implement their own equivalent endpoints, and comment anchors resolve against the document body through the core `POST /_agent-native/collab/:docId/search-replace` route.
 - Comments sidebar with threaded view and reply UI
 - Resolve/unresolve threads
 - **Send to AI** button — sends the comment thread context to the agent chat via `sendToAgentChat()`
 - Agent actions: `list-comments`, `add-comment`
 - Notion comment sync: `sync-notion-comments` action for bidirectional pull/push
 
-## Collab routes {#collab-routes}
-
-All collab routes are auto-mounted under `/_agent-native/collab/` by the collab plugin:
-
-| Route                         | Purpose                                  |
-| ----------------------------- | ---------------------------------------- |
-| `GET /:docId/state`           | Fetch full Y.Doc state (base64)          |
-| `POST /:docId/update`         | Apply client Yjs update                  |
-| `POST /:docId/text`           | Apply full text replacement (diff-based) |
-| `POST /:docId/search-replace` | Surgical find/replace in Y.XmlFragment   |
-| `POST /:docId/awareness`      | Sync cursor/presence state               |
-| `GET /:docId/users`           | List active users on a document          |
+All collab routes are auto-mounted under `/_agent-native/collab/` — see the [route table](#routes) for the full list.
 
 ## Agent edit action {#edit-document}
 
@@ -351,11 +342,9 @@ pnpm action edit-document --id doc123 --edits '[{"find":"old","replace":"new"}]'
 pnpm action edit-document --id doc123 --find "delete me" --replace ""
 ```
 
----
-
 ## Presence Kit {#presence-kit}
 
-The presence kit provides Liveblocks/collaboration-grade live-cursor and selection primitives on top of the existing awareness layer.
+The presence kit provides Liveblocks/collaboration-grade live-cursor and selection primitives on top of the existing awareness layer. Finer-grained presence — such as which users are viewing a given slide in a deck — layers on top of the same awareness state using the same hooks below.
 
 Import client-side presence and editor UI from the focused browser subpath:
 
@@ -421,7 +410,7 @@ import {
 
 ### Fast awareness {#fast-awareness}
 
-Awareness state changes now propagate at ~150ms instead of the 2s poll cycle:
+Awareness state changes propagate at ~150ms instead of waiting for the full poll cycle:
 
 - **Client → server**: any call to `setPresence()` or `awareness.setLocalStateField()` triggers a throttled POST to `/_agent-native/collab/:docId/awareness` within 150ms, coalescing rapid changes into one request.
 - **Server → clients**: the `postAwareness` handler emits an `AWARENESS_CHANGE_EVENT` after storing. The `/_agent-native/poll-events` SSE stream forwards these events push-style to connected peers. Polling-only deployments continue to work — cursors degrade to poll cadence without errors.
@@ -467,7 +456,7 @@ import { LiveCursorOverlay } from "@agent-native/toolkit/collab-ui";
 </div>;
 ```
 
-The agent's cursor renders distinctly with a sparkle icon. Cursors fade out after 10s of inactivity with smooth CSS transitions at 120ms.
+The agent's cursor renders with a distinct style so it's clear at a glance which cursor is the agent's. Cursors fade out after 10s of inactivity with smooth CSS transitions at 120ms.
 
 ### `RemoteSelectionRings` {#remote-selection-rings}
 
@@ -511,7 +500,7 @@ Participants publish their viewport with `setPresence({ viewport: { fileId, zoom
 
 ### `PresenceBar` follow-mode props {#presence-bar-follow}
 
-The `PresenceBar` component now accepts optional follow-mode props:
+The `PresenceBar` component accepts optional follow-mode props:
 
 ```tsx
 <PresenceBar
@@ -568,8 +557,6 @@ try {
 
 The selection metadata flows through `usePresence` on connected clients as `other.presence.selection`.
 
----
-
 ## Route table {#routes}
 
 All routes are auto-mounted under `/_agent-native/collab/` by the collab
@@ -723,11 +710,6 @@ Key properties:
 
 </Callout>
 
-- **Same-region simultaneous rewrite is LWW** — If the agent rewrites a
-  passage and a human has unsaved edits in the exact same region, the
-  lead-client snapshot can overwrite the human's in-flight changes. Edits in
-  different regions merge correctly via the CRDT. Granular server-side merge
-  (see above) avoids this for structured documents.
 - **In-process write locks on serverless** — The `_writeLocks` map is
   process-local. Concurrent requests landing on different serverless
   invocations serialize at the SQL CAS layer (optimistic concurrency) rather
@@ -738,26 +720,7 @@ Key properties:
   state per invocation. Clients still receive full awareness snapshots on each
   poll cycle, so presence indicators update within one poll interval.
 
-## Presence {#presence}
-
-The `useCollaborativeDoc` hook returns:
-
-- `activeUsers` — array of `CollabUser` (name, email, color) for all peers
-  currently in the document (sourced from awareness).
-- `agentActive` — `true` briefly after the agent makes an edit (use for a
-  transient visual indicator).
-- `agentPresent` — `true` while the agent has an active awareness entry
-  (durable presence heartbeat).
-
-Use `emailToColor(email)` and `emailToName(email)` from
-`@agent-native/toolkit/collab-ui` to generate consistent cursor colors and display
-names from email addresses.
-
-A `PresenceBar` rendered with `activeUsers` shows live human and agent
-collaborators. Per-slide presence (which users are viewing a given slide)
-layers on top of the same awareness state.
-
-## Related docs {#related}
+## What's next {#whats-next}
 
 - [Real-Time Sync](/docs/client#usedbsync) — the `useDbSync` + `useChangeVersion`
   system that delivers the `updatedAt` bump driving editor reconciliation.

package/docs/content/recurring-jobs.mdx

@@ -191,12 +191,14 @@ The scheduler is a framework plugin (the internal `processRecurringJobs()` routi
 
 A single `manage-jobs` tool is registered in every template. The `action` parameter selects the operation:
 
-| Action   | Parameters                                                        | Purpose                                                      |
-| -------- | ----------------------------------------------------------------- | ------------------------------------------------------------ |
-| `create` | `name`, `schedule`, `instructions` (required); `scope`, `runAs`   | Create a new recurring job                                   |
-| `list`   | `scope` (`personal`, `shared`, or all)                            | List all jobs with status (schedule, enabled, last/next run) |
-| `update` | `name` (required); `schedule`, `instructions`, `enabled`, `runAs` | Edit an existing job                                         |
-| `delete` | `name` (required)                                                 | Delete a job — always confirm with the user first            |
+| Action   | Parameters                                                                 | Purpose                                                      |
+| -------- | -------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| `create` | `name`, `schedule`, `instructions` (required); `scope`, `runAs`, `model`   | Create a new recurring job                                   |
+| `list`   | `scope` (`personal`, `shared`, or all)                                     | List all jobs with status (schedule, enabled, last/next run) |
+| `update` | `name` (required); `schedule`, `instructions`, `enabled`, `runAs`, `model` | Edit an existing job                                         |
+| `delete` | `name` (required)                                                          | Delete a job — always confirm with the user first            |
+
+`model` is optional on both `create` and `update` — pass a model id to override the channel/app/engine default for that one routine.
 
 **Personal vs shared scope.** Each job lives in either personal scope (runs as and is visible only to the creator) or shared/org scope (runs on behalf of the creator but is visible to org members). The `scope` and `runAs` parameters control this at create time. Org admins can update or delete any shared job; non-admin members can only manage their own.
 

package/docs/content/routing.mdx

@@ -72,8 +72,7 @@ Prefix a segment with `$` for a dynamic param. Prefix with `_` to make it a path
 
 Create the file and export a default component:
 
-```tsx
-// app/routes/settings.tsx
+```tsx filename="app/routes/settings.tsx"
 export function meta() {
   return [{ title: "Settings" }];
 }
@@ -87,8 +86,7 @@ That's it — React Router picks it up automatically, no registration needed.
 
 ## Dynamic params {#dynamic-params}
 
-```tsx
-// app/routes/inbox/$threadId.tsx
+```tsx filename="app/routes/inbox.$threadId.tsx"
 import { useParams } from "react-router";
 
 export default function ThreadPage() {
@@ -116,3 +114,4 @@ navigate(`/inbox/${threadId}`);
 
 - [**Client**](/docs/client) — the agent-native browser hooks and utilities
 - [**Server**](/docs/server) — file-based server routes and the `/_agent-native/` namespace
+- [**Context Awareness**](/docs/context-awareness) — how the agent learns the current route and selection

package/docs/content/sandbox-adapters.mdx

@@ -6,8 +6,12 @@ search: "adapters sandbox adapter cli adapter run-code SandboxAdapter CliAdapter
 
 # Adapters
 
-> **Who is this for:** host authors extending the runtime. App developers rarely
-> need this — the defaults work out of the box.
+<Callout id="doc-block-adap1who" tone="info">
+
+**Who is this for:** host authors extending the runtime. App developers rarely
+need this — the defaults work out of the box.
+
+</Callout>
 
 Agent-Native has two adapter seams that factor a concern out behind a narrow,
 swappable interface:
@@ -26,15 +30,15 @@ not run on edge/worker runtimes — see [Edge and serverless](#edge-serverless).
 | You want to…                                                               | Use                                          |
 | -------------------------------------------------------------------------- | -------------------------------------------- |
 | Swap the backend that runs the agent's **`run-code` tool**                 | **Sandbox adapters** (this page)             |
-| Wrap a CLI tool (`gh`, `ffmpeg`) for the agent to call                     | **CLI adapters** (this page)                 |
+| Wrap a CLI tool (`gh`, `ffmpeg`) for the agent to call                     | [CLI Adapters](/docs/cli-adapters)           |
 | Render a Claude-Code/Codex-style **coding workspace UI**                   | [Agent-Native Code UI](/docs/code-agents-ui) |
 | Run Claude Code / Codex / Pi **as the agent**, with their own loop + tools | [Harness Agents](/docs/harness-agents)       |
 
-# Sandbox Adapters
+## Sandbox Adapters {#sandbox-adapters}
 
 The `run-code` tool runs agent-supplied JavaScript in an isolated environment. **Sandbox adapters** factor the _execution_ concern out of that tool so the backend can be swapped — a local child process by default, or a Docker / remote / durable runner — without touching the agent loop, `run-code.ts`, the localhost bridge, the env scrub, or the output formatting.
 
-## Why a seam {#why}
+### Why a seam {#why}
 
 The default backend spawns a locked-down local Node child process. That's bounded by the hosting process: on the hosted platform it shares the agent loop's soft execution ceiling (~40s before timeout/continuation thrash). A remote or durable adapter is the lever to exceed that ceiling — it runs large data jobs to completion independently of the request lifecycle.
 
@@ -86,14 +90,13 @@ Keeping the contract narrow means a remote adapter inherits the same security po
 
 </Diagram>
 
-## The interface {#interface}
+### The interface {#interface}
 
 The seam lives in core at `packages/core/src/coding-tools/sandbox/` — `adapter.ts` (the contract), `index.ts` (selection: `getSandboxAdapter()` / `registerSandboxAdapter()`), and `local-child-process-adapter.ts` (the default). It is wired in-package by `run-code.ts`; a host plugs in a different backend through the `index.ts` registration helper (or, for a Docker backend, via the [blueprint](/docs/blueprint-installer) that edits these files directly).
 
 <FileTree
   id="doc-block-b1k8n3"
   title="The sandbox seam in core"
-  title="packages/core/src/coding-tools/sandbox/"
   entries={[
     {
       path: "adapter.ts",
@@ -160,7 +163,7 @@ interface SandboxRunResult {
 }
 ```
 
-## The default: `LocalChildProcessAdapter` {#default}
+### The default: `LocalChildProcessAdapter` {#default}
 
 Out of the box, `getSandboxAdapter()` returns `LocalChildProcessAdapter` (`id: "local-child-process"`). It preserves the historical `run-code` behavior byte-for-byte:
 
@@ -170,10 +173,13 @@ Out of the box, `getSandboxAdapter()` returns `LocalChildProcessAdapter` (`id: "
 - A timeout sends `SIGTERM`, then `SIGKILL` after a 2s grace period.
 - Temp files are cleaned up best-effort after the run.
 
-> [!WARNING]
-> The default adapter uses `node:child_process`, which does not exist on edge/worker runtimes. Run `run-code` in a standard Node.js environment, or register a remote adapter — see [Edge and serverless](#edge-serverless).
+<Callout id="doc-block-adap1def" tone="warning">
+
+The default adapter uses `node:child_process`, which does not exist on edge/worker runtimes. Run `run-code` in a standard Node.js environment, or register a remote adapter — see [Edge and serverless](#edge-serverless).
+
+</Callout>
 
-## Selecting an adapter {#selection}
+### Selecting an adapter {#selection}
 
 Resolution order — an explicitly registered adapter wins; otherwise the env var selects a built-in; otherwise the local default is used:
 
@@ -181,7 +187,7 @@ Resolution order — an explicitly registered adapter wins; otherwise the env va
 registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
 ```
 
-### `AGENT_NATIVE_SANDBOX` env var {#env}
+#### `AGENT_NATIVE_SANDBOX` env var {#env}
 
 Selects a built-in adapter by id. Currently only `local` (the default) is wired; unknown values fall back to local rather than failing the run.
 
@@ -189,7 +195,7 @@ Selects a built-in adapter by id. Currently only `local` (the default) is wired;
 AGENT_NATIVE_SANDBOX=local   # the default — explicit
 ```
 
-### `registerSandboxAdapter()` {#register}
+#### `registerSandboxAdapter()` {#register}
 
 A host process overrides the backend for all subsequent `run-code` invocations through the seam's `index.ts` — for example, to run every call in a remote container:
 
@@ -211,7 +217,7 @@ registerSandboxAdapter(new RemoteSandboxAdapter());
 // Pass `null` to clear the override and fall back to env-var / default resolution.
 ```
 
-## The seam for a durable runner {#durable}
+### The seam for a durable runner {#durable}
 
 This interface is deliberately the seam for a future remote/durable sandbox. A remote or durable adapter (Docker, a Vercel-Sandbox-style runner, or a queued background worker) would:
 
@@ -221,54 +227,25 @@ This interface is deliberately the seam for a future remote/durable sandbox. A r
 
 Register it under a new `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and/or via `registerSandboxAdapter()`. The agent loop and `run-code.ts` never change.
 
-> [!TIP]
-> The `agent-native add sandbox docker` blueprint emits a full, self-contained recipe for implementing a Docker adapter against this seam. See [Blueprint Installer](/docs/blueprint-installer).
+<Callout id="doc-block-adap1tip" tone="info">
 
-# CLI Adapters
+The `agent-native add sandbox docker` blueprint emits a full, self-contained recipe for implementing a Docker adapter against this seam. See [Blueprint Installer](/docs/blueprint-installer).
 
-The other adapter seam wraps a single command-line tool (`gh`, `ffmpeg`, `stripe`, `aws`) so the agent can discover it, check whether it's installed, and run it with a consistent stdout/stderr/exit-code result. Every CLI adapter implements `CliAdapter`:
+</Callout>
 
-```ts
-import type { CliAdapter, CliResult } from "@agent-native/core/adapters/cli";
+## CLI Adapters {#cli-adapters}
 
-interface CliAdapter {
-  name: string; // "gh", "stripe", "ffmpeg"
-  description: string; // What the agent sees during discovery
-  isAvailable(): Promise<boolean>;
-  execute(args: string[]): Promise<CliResult>;
-}
+The other adapter seam wraps a single command-line tool (`gh`, `ffmpeg`, `stripe`, `aws`) behind a `CliAdapter` contract, so the agent can discover it, check whether it's installed, and run it with a consistent stdout/stderr/exit-code result.
 
-interface CliResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-```
+See [CLI Adapters](/docs/cli-adapters) for the `CliAdapter` contract, `ShellCliAdapter`, `CliRegistry`, and the action-wrapping pattern — this page only covers the seam it shares with sandbox adapters.
 
-For most CLIs, `ShellCliAdapter` wraps any binary with sensible defaults, and `CliRegistry` collects adapters for runtime discovery:
-
-```ts
-import { CliRegistry, ShellCliAdapter } from "@agent-native/core/adapters/cli";
-
-const cliRegistry = new CliRegistry();
-cliRegistry.register(
-  new ShellCliAdapter({
-    command: "gh",
-    description: "GitHub CLI — manage repos, PRs, issues, and releases",
-  }),
-);
-
-await cliRegistry.describe(); // [{ name, description, available }] for discovery
-const gh = cliRegistry.get("gh");
-const result = await gh?.execute(["pr", "list", "--json", "title,url"]);
-```
+## Edge and serverless {#edge-serverless}
 
-Wrap a CLI call in `defineAction` to expose it on the action surface. See the [CLI Adapters](/docs/cli-adapters) quick reference for `ShellCliAdapter` options, custom adapters, and the action-wrapping pattern.
+<Callout id="doc-block-adap1edge" tone="warning">
 
-## Edge and serverless {#edge-serverless}
+Both adapter seams rely on Node.js system bindings. The sandbox `LocalChildProcessAdapter` and CLI adapters (`ShellCliAdapter` and custom adapters) use `node:child_process` (`execFile` / `spawn`), which **does not exist** on edge/worker runtimes such as Cloudflare Workers or Netlify Edge Functions. If you deploy server routes to these edge presets, executing these adapters throws a runtime exception. Run adapter endpoints and tasks in a standard Node.js environment (traditional server containers or serverless Node functions) — or, for the sandbox seam, register a remote adapter that ships work out of process.
 
-> [!WARNING]
-> Both adapter seams rely on Node.js system bindings. The sandbox `LocalChildProcessAdapter` and CLI adapters (`ShellCliAdapter` and custom adapters) use `node:child_process` (`execFile` / `spawn`), which **does not exist** on edge/worker runtimes such as Cloudflare Workers or Netlify Edge Functions. If you deploy server routes to these edge presets, executing these adapters throws a runtime exception. Run adapter endpoints and tasks in a standard Node.js environment (traditional server containers or serverless Node functions) — or, for the sandbox seam, register a remote adapter that ships work out of process.
+</Callout>
 
 ## What's next
 

package/docs/content/security.mdx

@@ -415,3 +415,11 @@ AGENT_NATIVE_KEYS_WORKSPACE_FALLBACK=1
 ```
 
 Workspace-scope secret writes still require org owner/admin role regardless of this flag.
+
+## What's next
+
+- [**Authentication**](/docs/authentication) — auth modes, cookie realms, and session details this page builds on
+- [**Multi-Tenancy**](/docs/multi-tenancy) — the org-membership model behind `org_id` scoping
+- [**Sharing**](/docs/sharing) — the `ownableColumns()` and access-guard pattern applied to shareable resources
+- [**Messaging**](/docs/messaging#env-vars) — per-integration webhook signing secrets referenced in the checklist above
+- [**Deployment**](/docs/deployment) — the production environment variables this checklist assumes are set

package/docs/content/server.mdx

@@ -96,8 +96,7 @@ server/routes/
 
 Each route exports a `defineEventHandler`:
 
-```ts
-// server/routes/api/health.get.ts
+```ts filename="server/routes/api/health.get.ts"
 import { defineEventHandler } from "h3";
 
 export default defineEventHandler(() => ({
@@ -137,8 +136,7 @@ Use the action `http` option to shape direct HTTP access: actions are `POST` by
 
 For a read-only status endpoint, keep it as an action:
 
-```ts
-// actions/get-status.ts
+```ts filename="actions/get-status.ts"
 import { defineAction } from "@agent-native/core/action";
 import { z } from "zod";
 
@@ -171,8 +169,7 @@ what happened. For narrow server-side transforms that intentionally do not need
 tools, chat history, or run state, use `completeText()` as an explicit escape
 hatch.
 
-```ts
-// actions/classify-message.ts
+```ts filename="actions/classify-message.ts"
 import { defineAction } from "@agent-native/core/action";
 import { completeText } from "@agent-native/core/server";
 import { z } from "zod";
@@ -237,8 +234,7 @@ Actions mounted by the framework automatically run with request context. Custom
 
 Plugins live in `server/plugins/` and run at startup. Use them for migrations, provider setup, recurring jobs, integration adapters, and framework plugin configuration.
 
-```ts
-// server/plugins/db.ts
+```ts filename="server/plugins/db.ts"
 import { runMigrations } from "@agent-native/core/db";
 
 export default runMigrations(
@@ -416,8 +412,11 @@ Inbound webhooks should verify, persist, and return quickly. Long-running agent
 
 </Diagram>
 
-> [!WARNING]
-> Do not rely on unawaited promises after returning a response — serverless hosts freeze the execution. See [Messaging](/docs/messaging) for the canonical integration queue.
+<Callout tone="warning">
+  Do not rely on unawaited promises after returning a response — serverless
+  hosts freeze the execution. See [Messaging](/docs/messaging) for the canonical
+  integration queue.
+</Callout>
 
 ## Advanced: Escape Hatches {#advanced-escape-hatches}
 
@@ -459,3 +458,11 @@ const handler = createProductionAgentHandler({
   systemPrompt: "You are the app agent...",
 });
 ```
+
+## What's next
+
+- [**Actions**](/docs/actions) — the default operation surface; reach for a custom route only when it doesn't fit
+- [**Database**](/docs/database) — the `getDb()`/`schema` pattern custom routes and actions both import
+- [**Security**](/docs/security#access-guards) — `accessFilter`/`assertAccess` and the full data-scoping model
+- [**Messaging**](/docs/messaging) — the canonical inbound-webhook integration queue pattern
+- [**MCP Protocol**](/docs/mcp-protocol) — the `/_agent-native/mcp` endpoint this server mounts automatically

package/docs/content/sharing.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Sharing & Privacy"
-description: "Google-Docs-style sharing, built into the framework. Every user-created resource — docs, dashboards, designs, decks, clips, recordings, forms — gets the same private-by-default model with one consistent share UI."
+description: "Familiar, consistent sharing built into the framework. Every user-created resource — docs, dashboards, designs, decks, clips, recordings, forms — gets the same private-by-default model with one consistent share UI."
 ---
 
 # Sharing & Privacy
 
 Every resource a user creates in an agent-native app — a document, a dashboard, a design, a deck, a screen recording, a meeting transcript, a form, a booking link — is **private to the creator by default**. Other people see it only when the creator explicitly shares it, or changes its visibility to `org` or `public`.
 
-It looks and works like Google Docs. The same share button, the same dialog, the same three-tier visibility model, the same per-user/per-org grants — across every template, with no per-app reinvention.
+It's one familiar sharing model everywhere: the same share button, the same dialog, the same three-tier visibility model, the same per-user/per-org grants — across every template, with no per-app reinvention.
 
 ## Why one model {#why}
 
@@ -92,7 +92,7 @@ Every template that stores user-authored work uses this model. Concretely:
 - **Content** — documents
 - **Slides** — decks
 - **Design** — designs and assets
-- **Clips** — screen recordings (Loom-style)
+- **Clips** — screen recordings
 - **Plan** — visual plans and PR recaps
 - **Forms** — form definitions
 - **Calendar** — events and booking links
@@ -115,7 +115,7 @@ Every shareable resource gets a share button in its header. Clicking it opens a
 
 - Visibility selector (`Private` / `Organization` / `Public link`).
 - "Add people or teams" autocomplete — search users in the org or paste an email.
-- A Google Docs-style `Notify people` checkbox for individual email grants.
+- A `Notify people` checkbox for individual email grants.
 - A list of current grants with role pickers and a remove control.
 - A copy-link button that respects the current visibility.
 
@@ -294,7 +294,7 @@ export const deckShares = createSharesTable("deck_shares");
 
 One registration call in `server/db/index.ts`:
 
-```ts
+```ts filename="server/db/index.ts"
 import { registerShareableResource } from "@agent-native/core/sharing";
 
 registerShareableResource({
@@ -339,9 +339,9 @@ For resources that execute code or carry elevated trust (like extensions), set `
 
 Sharing rides on the framework's broader data-scoping model — list/read/write access to ownable tables goes through `accessFilter()` / `resolveAccess()` / `assertAccess()`, and `org_id`-tagged resources are invisible across orgs. See [Security → Data Scoping](/docs/security#data-scoping) for the full pipeline, the CI guard, and the threat surface.
 
-## See also {#see-also}
+## What's next {#see-also}
 
-- [Security & Data Scoping](/docs/security) — the access-filter and ownership model that sharing rides on.
-- [Authentication](/docs/authentication) — sessions, organizations, and how identity flows into the request context.
-- [Extensions](/docs/extensions#sharing) — sharing in the sandboxed mini-app surface.
-- [Creating Templates](/docs/creating-templates) — wiring `ownableColumns` into a new template's schema.
+- [**Security — Data Scoping**](/docs/security#data-scoping) — the access-filter and ownership model that sharing rides on
+- [**Authentication**](/docs/authentication) — sessions, organizations, and how identity flows into the request context
+- [**Extensions**](/docs/extensions#sharing) — sharing in the sandboxed mini-app surface
+- [**Creating Templates**](/docs/creating-templates) — wiring `ownableColumns` into a new template's schema

package/docs/content/skills-guide.mdx

@@ -5,7 +5,7 @@ description: "How skills work in agent-native: framework skills, domain skills,
 
 # Skills Guide
 
-Skills are Markdown files that give the agent deep knowledge about specific patterns and workflows.
+Skills are Markdown files that give the agent deep knowledge about specific patterns and workflows. Instead of cramming every rule into one system prompt, you split knowledge into focused files the agent loads only when a task actually needs them — keeping the default context small while still letting the agent go deep on demand.
 
 ## What are skills {#what-are-skills}
 
@@ -124,7 +124,11 @@ Current app-backed skills include `visual-plan`, `visual-recap`, and
 `visualize-repo` from Plan, `visual-edit` from Design, `assets` from Assets, and
 `content` for repo-backed docs/blog/MDX editing.
 
-> **Full details below:** the mechanics of app-backed skills (manifest format, CLI commands, marketplace adapters, auto-update hashing) are covered in [App-backed skills — full details](#app-backed-skills-full).
+<Callout tone="info">
+
+**Full details below:** the mechanics of app-backed skills (manifest format, CLI commands, marketplace adapters, auto-update hashing) are covered in [App-backed skills — full details](#app-backed-skills-full).
+
+</Callout>
 
 ## Creating custom skills {#creating-skills}
 
@@ -179,7 +183,11 @@ The frontmatter `name` and `description` are used by the agent's tool system for
 
 Save the file at `.agents/skills/my-skill/SKILL.md`. The directory name should match the `name` in frontmatter.
 
-> **See also:** [Writing Agent Instructions](/docs/writing-agent-instructions) for how to word skill descriptions, apply progressive disclosure, and keep `AGENTS.md` lean. Both pages use the `project-imports` skill as a running example.
+<Callout tone="info">
+
+**See also:** [Writing Agent Instructions](/docs/writing-agent-instructions) for how to word skill descriptions, apply progressive disclosure, and keep `AGENTS.md` lean. Both pages use the `project-imports` skill as a running example.
+
+</Callout>
 
 ## Skill scope: runtime vs dev {#skill-scope}
 
@@ -269,33 +277,37 @@ This replaces the old hack of relying on Claude Code only reading `.claude/skill
 
 </Diagram>
 
-> **See also:** [Writing Agent Instructions](/docs/writing-agent-instructions) for how to word skill descriptions, apply progressive disclosure, and keep `AGENTS.md` lean.
-
 ## Skills vs AGENTS.md {#skills-vs-agents-md}
 
-> **AGENTS.md** — The overview. Lists all scripts, describes the data model, explains the app architecture. The agent reads this first to understand the app.
->
-> **Skills** — Deep dives. Each skill focuses on one pattern with detailed rules, code examples, and do/don't lists. The agent reads these when it needs to follow a specific pattern.
+<Callout tone="info">
+
+**AGENTS.md** — The overview. Lists all scripts, describes the data model, explains the app architecture. The agent reads this first to understand the app.
+
+**Skills** — Deep dives. Each skill focuses on one pattern with detailed rules, code examples, and do/don't lists. The agent reads these when it needs to follow a specific pattern.
+
+</Callout>
 
 `AGENTS.md` tells the agent _what_ the app does. Skills tell the agent _how_ to do specific things correctly. Both are needed — `AGENTS.md` for orientation, skills for execution.
 
 ## Skills vs memory {#skills-vs-memory}
 
-> **Skills** — Authored, reusable how-to guides. Apply to every user, invoked on demand when the task matches.
->
-> **Memory (`LEARNINGS.md` / `memory/MEMORY.md`)** — Shared project learnings and personal structured memory loaded every turn.
+<Callout tone="info">
+
+**Skills** — Authored, reusable how-to guides. Apply to every user, invoked on demand when the task matches.
+
+**Memory (`LEARNINGS.md` / `memory/MEMORY.md`)** — Shared project learnings and personal structured memory loaded every turn.
+
+</Callout>
 
 If the knowledge applies to _everyone_ working in the app ("always prefer CTEs over subqueries"), it's a skill or shared `LEARNINGS.md`. If it's about _this particular user_ ("Steve likes concise answers"), it belongs in `memory/MEMORY.md`. See [Workspace Memory](/docs/workspace#memory) for the full treatment.
 
----
+## Skills vs SQL resources {#skills-vs-resources}
 
-# Advanced
+This page frames a skill as a file at `.agents/skills/<name>/SKILL.md`. [Workspace](/docs/workspace#skills) frames the same skill as a SQL resource at path `skills/<slug>/SKILL.md`, scoped workspace/shared/personal. These are the same concept from two angles: Code mode reads and writes the file directly; App mode stores it as a resource row so it works without a filesystem. Author the content using this page's format either way.
 
 ## App-backed skills — full details {#app-backed-skills-full}
 
-App-backed skills package an agent-native app as a skill marketplace artifact.
-The bundle can include agent instructions, exported skills, MCP connector
-metadata, hosted/local launch instructions, and UI surfaces such as MCP Apps.
+The manifest format, CLI commands, marketplace adapters, and auto-update hashing behind [app-backed skills](#app-backed-skills) in full:
 
 Each app-backed skill starts with `agent-native.app-skill.json` at the app root:
 
@@ -412,3 +424,10 @@ npx @agent-native/core@latest skills update scaffold --project
 `AGENTS.md` and `.agents/skills` stay canonical. The update command also repairs
 Claude compatibility links (`CLAUDE.md` and `.claude/skills`) so Claude Code sees
 the same instructions without maintaining a second copy.
+
+## What's next {#whats-next}
+
+- [**Writing Agent Instructions**](/docs/writing-agent-instructions) — word skill descriptions and split guidance across AGENTS.md, skills, and memory
+- [**Workspace**](/docs/workspace#skills) — where skills live as SQL resources in App mode
+- [**Agent Mentions**](/docs/agent-mentions) — the `/`-command trigger that invokes a skill in chat
+- [**Plan plugin & marketplace**](/docs/plan-plugin) — a real app-backed skill's end-to-end install and auto-update flow