@agent-native/core 0.51.6 → 0.51.7

package/docs/content/template-analytics.md

@@ -67,14 +67,6 @@ The app has three primary surfaces you'll spend time in:
 
 The dictionary is seeded by asking the agent: "import our dbt definitions" or "pull the metrics from our Notion handbook" and it does the work.
 
-## Why it's interesting
-
-Three things make Analytics a good showcase of the framework:
-
-1. **The data dictionary keeps SQL grounded.** The agent consults the dictionary before writing any query, so it uses real warehouse column names and honors documented caveats. The dictionary is itself an agent-native resource — seeded and edited through the same chat interface that runs the queries.
-2. **Multi-source, single action surface.** BigQuery, GA4, Mixpanel, Amplitude, HubSpot, Jira, and a dozen other sources are each a single action file. Adding a new connector is adding a file; the agent picks it up automatically with no registration step.
-3. **Reusable workspace integrations.** When a workspace already has a provider connected (e.g. HubSpot), Analytics requests a grant instead of requiring a second copy of the same credentials. The Data Sources page shows workspace-level readiness alongside local-credential status.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Analytics template or extending it.

package/docs/content/template-assets.md

@@ -83,12 +83,6 @@ Generate and pick brand media without leaving Codex, Claude Code, Claude, or Cha
 
 4. **Apply to code.** The chosen Media URL and `assetId` come back to the agent, which uses the URL directly in the code it writes (an `<img>` src, a download) or calls `export-asset`.
 
-## Why it's interesting
-
-Most AI media tools treat brand consistency as a prompt-writing problem. Assets treats it as application state: references, folders, collections, style briefs, run history, descriptions, and saved assets live in SQL, while binary media lives in object storage or the local file-upload fallback during development.
-
-Because generation and library management are actions and chat workflows, the UI and the agent share the same operations. A user can start from the big prompt box, a library detail page, another app's chat, or an A2A request from Slides, and the same audit and lineage model is preserved. Once enabled, the provider path prefers Builder-managed image generation so teams do not need to paste model-provider keys into every app.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Assets template or extending it.

package/docs/content/template-brain.md

@@ -79,14 +79,6 @@ For a public demo, the seeded corpus demonstrates product-decision recall,
 citation links, supersede behavior, review gating, redaction, personal-content
 exclusion, and honest not-found behavior without connecting a real workspace.
 
-## Why it's interesting
-
-Three things make Brain a good showcase of the framework:
-
-1. **No vector database required.** Brain uses SQL text search with agentic query expansion, so it stays portable across SQLite, Postgres, Neon, D1, and Turso without an additional service dependency. This demonstrates that semantic-enough retrieval can be built without embedding infrastructure.
-2. **Human-in-the-loop distillation.** Raw captures don't become company knowledge automatically. High-confidence entries can auto-publish; sensitive or low-confidence ones queue as proposals for human review. The Review surface is a first-class part of the product, not a settings screen.
-3. **Shared workspace integrations.** Brain sources resolve credentials from workspace grants first, not duplicated env vars. It's a live example of the grant pattern — one Slack token at workspace level, per-app access requests.
-
 ## For developers
 
 The rest of this section is for anyone forking or extending the Brain template.

package/docs/content/template-calendar.md

@@ -61,14 +61,6 @@ Or just ask the agent: "Create a 15-minute intro booking link with a name field.
 
 The agent will query Google Calendar live for any schedule question — it never guesses.
 
-## Why it's interesting
-
-Three things make Calendar a good showcase of the framework:
-
-1. **Live API queries, no local sync.** Events live in Google Calendar; the app queries the API on demand rather than maintaining a local mirror. This avoids stale data and webhook infrastructure while still giving the agent full read/write access through actions.
-2. **Booking links as a Calendly replacement.** The public booking page (`/book/{slug}`) is stateless to visitors — it queries availability live and creates a booking on submit. The `booking_link_shares` table wires into the framework sharing primitive so teammates can manage links collaboratively.
-3. **Multi-account overlay.** Connecting a second Google account is an action call; the UI overlays events from all connected calendars in the same view. This pattern — one row per account in `oauth_tokens`, list action that fans out — is reusable for any multi-account integration.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Calendar template or extending it.

package/docs/content/template-clips.md

@@ -51,14 +51,6 @@ Live demo: [clips.agent-native.com](https://clips.agent-native.com).
 - "Create action items from the last sales call."
 - "Clean up this dictation and turn it into a Linear ticket."
 
-## Why it's interesting
-
-Three things make Clips a good showcase of what agent-native enables:
-
-1. **The agent edits the transcript.** Fix a mis-transcribed word, generate chapter timestamps, pull quotes for a blog post — all in natural language, in the chat, with the UI updating live via polling.
-2. **Context awareness on recordings.** When you're viewing a clip, the agent knows the clip id, the current playhead, and the selected transcript range. Ask "summarize from here to the end" and it understands what "here" means.
-3. **Clips you own, not a vendor.** The recordings live in your storage, the transcripts live in your SQL, and the agent is yours. Fork the template, change how chapters get built, wire it to your own CDN — it's your code.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Clips template or extending it.

package/docs/content/template-content.md

@@ -86,20 +86,6 @@ SQL-backed sharing. See [Local File Mode](/docs/local-file-mode) for the
 standalone repo layout, configuration, custom MDX components, local
 `extensions/` widgets, and production safety guide.
 
-## Why it's interesting
-
-Five things make Content a good showcase of the framework:
-
-1. **Local MDX can be the source of truth.** Content can operate directly on
-   repo files while keeping the same editor and action surface, which makes it
-   feel like open-source Obsidian for MDX rather than a hosted-only doc store.
-2. **Custom interactive blocks are just local code.** Docs can use workspace
-   components such as tabs, calculators, or product-specific demos, and the
-   agent can generate or edit those components alongside the MDX.
-3. **Agent and editor share one Yjs document.** The same CRDT that prevents conflicts between two simultaneous human typists is what the agent writes through via `edit-document`. There is no separate AI path — the diff appears live in every open browser tab.
-4. **Notion sync as a two-way bridge.** Rather than replacing Notion, the template treats it as a peer: pull, push, bidirectional comment sync, conflict detection, and content-hash deduplication are all first-class. It demonstrates how agent-native apps can round-trip with external systems without losing their SQL-backed canonical form.
-5. **Inline databases alongside prose.** The `content_databases` / `content_database_items` / `document_property_definitions` stack shows how structured tabular data can live inside an agent-native document without needing a separate app or a custom Airtable integration.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Content template or extending it.

package/docs/content/template-design.md

@@ -41,12 +41,6 @@ Live demo: [design.agent-native.com](https://design.agent-native.com).
 - "Export this prototype as a ZIP once the final variant is selected."
 - "Turn this HTML into a stronger pricing page without changing the brand colors."
 
-## Why it's interesting
-
-Design is useful because the agent edits an artifact that is already close to shippable web UI. There is no separate "AI mockup" format to translate later: the preview, the editable source, and the exported artifact all come from the same HTML.
-
-The template is also a good example of agent-native ownership. The app stores designs in SQL, exposes template operations as actions, and lets you fork the whole workflow when your team needs a different renderer, exporter, or design-system model.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Design template or extending it.

package/docs/content/template-forms.md

@@ -49,16 +49,6 @@ Live demo: [forms.agent-native.com](https://forms.agent-native.com).
 - "Summarize this week's submissions and group them by customer segment."
 - "Make this form shorter without losing the fields we need for routing."
 
-## Why it's interesting
-
-Three things make Forms a good showcase of the framework:
-
-1. **Single SQL record, two editors.** The form's `fields` JSON column is the source of truth for both the visual builder and the agent. Ask the agent to add a field and the builder re-renders — no sync step, no separate "AI draft" state.
-2. **Public and private surfaces from one schema.** The same form row serves authenticated editors (full field + settings access) and anonymous respondents (public fill page with secrets stripped). `toPublicFormSettings` handles the split at the action layer.
-3. **Integrations as settings, not infrastructure.** Slack, Discord, Google Sheets, and webhook destinations are stored as JSON in the form's settings column and executed server-side at submission time — adding a new integration type is an action-layer change, not a schema migration.
-
-See [What is agent-native?](/docs/what-is-agent-native) for the broader framework model.
-
 ## For developers
 
 ### Scaffolding

package/docs/content/template-mail.md

@@ -82,14 +82,6 @@ If you select text and hit Cmd+I, that selection travels with your next message
 | `G A`     | Go to Archive               |
 | `Esc`     | Close thread / clear search |
 
-## Why it's interesting
-
-Three things make Mail a good showcase of the framework:
-
-1. **Gmail as a view, not a copy.** Email lives in Gmail; the app is a fast keyboard-first view on top. Actions like `list-emails` and `search-emails` query the Gmail API live rather than maintaining a local sync — demonstrating how agent-native apps can wrap external services without duplicating state.
-2. **Shared compose state between the agent and the UI.** Each draft tab is an `application_state` entry at `compose-{id}`. The agent can create, edit, or close drafts via `manage-draft`; the UI reads the same entry and renders it live. No separate draft format, no polling — same row.
-3. **Queued-draft review.** Teammates or Slack users can ask the agent to prepare an email on behalf of an org member. The draft sits in the `queued_email_drafts` SQL table until the owner reviews and explicitly sends — demonstrating how agent-native apps can keep humans in the loop for consequential, irreversible actions.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Mail template or extending it.

package/docs/content/template-plan.md

@@ -298,6 +298,186 @@ Actions in `templates/plan/actions/`:
 - **Prototype** — `convert-visual-plan-to-prototype`, `create-prototype-plan`
 - **Context & navigation** — `view-screen`, `navigate`
 
+### Custom MDX blocks {#custom-mdx-blocks}
+
+Plans source files are MDX, but the app does not render arbitrary imported JSX
+components. A custom MDX tag must be registered as a Plan block so the server can
+parse and serialize it, the browser can render and edit it, and the agent can
+see it in the block vocabulary returned by `get-plan-blocks`.
+
+A registered block has three surfaces:
+
+- A React-free schema and MDX config, safe for server and agent code.
+- A normalized runtime type/schema entry in `shared/plan-content.ts`.
+- A browser block spec with `Read` and optional `Edit` React components.
+
+Keep the block `type` and MDX `tag` stable. The `type` is stored in normalized
+plan JSON; the `tag` is the component name in `plan.mdx`. The registry handles
+the base MDX attributes `id`, `title`, `summary`, and `editable`, so do not
+repeat them in `toAttrs`.
+
+1. Add a shared config for the data shape and MDX round trip.
+
+```ts
+// templates/plan/shared/risk-card.config.ts
+import { z } from "zod";
+import {
+  markdown,
+  type BlockMdxConfig,
+} from "@agent-native/core/blocks/server";
+
+export type RiskCardSeverity = "low" | "medium" | "high";
+
+export interface RiskCardData {
+  severity?: RiskCardSeverity;
+  body: string;
+}
+
+const severities = new Set(["low", "medium", "high"]);
+
+export const riskCardSchema = z.object({
+  severity: z.enum(["low", "medium", "high"]).optional(),
+  body: markdown(z.string().trim().min(1).max(10_000)),
+}) as z.ZodType<RiskCardData>;
+
+export const riskCardMdx: BlockMdxConfig<RiskCardData> = {
+  tag: "RiskCard",
+  childrenField: "body",
+  toAttrs: (data) => ({
+    severity: data.severity,
+  }),
+  fromAttrs: (attrs, children) => {
+    const severity = attrs.string("severity");
+
+    return {
+      severity: severities.has(severity ?? "")
+        ? (severity as RiskCardSeverity)
+        : undefined,
+      body: children,
+    };
+  },
+};
+```
+
+2. Extend the normalized Plan content model in
+   `templates/plan/shared/plan-content.ts`.
+
+Add the new `type` to `PlanBlockType`, add a matching block interface to the
+`PlanBlock` union, and add the same data shape to `planBlockSchema`. This keeps
+database saves, source imports, and `update-block` patches validating the custom
+block instead of rejecting it as an unknown type.
+
+3. Register the React-free server spec in
+   `templates/plan/shared/plan-block-registry.ts`.
+
+```ts
+import {
+  BlockRegistry,
+  defineBlock,
+  registerLibraryBlockConfigs,
+  registerBlocks,
+} from "@agent-native/core/blocks/server";
+import {
+  riskCardMdx,
+  riskCardSchema,
+  type RiskCardData,
+} from "./risk-card.config.js";
+
+const ServerReadStub = () => null;
+
+const riskCardServerBlock = defineBlock<RiskCardData>({
+  type: "risk-card",
+  schema: riskCardSchema,
+  mdx: riskCardMdx,
+  Read: ServerReadStub,
+  placement: ["block"],
+  label: "Risk card",
+  description: "A markdown risk note with a low, medium, or high severity.",
+});
+
+export function registerPlanBlocks(registry: BlockRegistry): void {
+  registerLibraryBlockConfigs(registry, {
+    overrides: PLAN_SERVER_LIBRARY_OVERRIDES,
+  });
+  registerBlocks(registry, [riskCardServerBlock]);
+}
+```
+
+4. Register the browser spec in
+   `templates/plan/app/components/plan/planBlocks.tsx`.
+
+```tsx
+import {
+  defineBlock,
+  registerLibraryBlocks,
+  registerBlocks,
+  type BlockReadProps,
+} from "@agent-native/core/blocks";
+import {
+  riskCardMdx,
+  riskCardSchema,
+  type RiskCardData,
+} from "@shared/risk-card.config";
+
+function RiskCardBlock({ data, blockId, ctx }: BlockReadProps<RiskCardData>) {
+  return (
+    <section
+      className="rounded-md border border-border bg-card p-4"
+      data-block-id={blockId}
+      data-severity={data.severity}
+    >
+      <div className="mb-2 text-xs font-semibold uppercase text-muted-foreground">
+        {data.severity ?? "risk"}
+      </div>
+      {ctx.renderMarkdown?.(data.body) ?? (
+        <p className="whitespace-pre-wrap text-sm">{data.body}</p>
+      )}
+    </section>
+  );
+}
+
+const riskCardBlock = defineBlock<RiskCardData>({
+  type: "risk-card",
+  schema: riskCardSchema,
+  mdx: riskCardMdx,
+  Read: RiskCardBlock,
+  placement: ["block"],
+  editSurface: "panel",
+  label: "Risk card",
+  description: "A markdown risk note with a low, medium, or high severity.",
+  empty: () => ({ severity: "medium", body: "Describe the risk." }),
+});
+
+registerLibraryBlocks(planBlockRegistry, {
+  overrides: PLAN_LIBRARY_OVERRIDES,
+});
+registerBlocks(planBlockRegistry, [riskCardBlock]);
+```
+
+With that in place, Plan MDX can use:
+
+```mdx
+<RiskCard id="risk-auth" severity="high">
+
+Token refresh failures can strand active reviewer sessions.
+
+</RiskCard>
+```
+
+The server registry makes this source importable/exportable, and the client
+registry makes it render in `PlanBlockView`. If the block should be generated by
+agents, keep `label`, `description`, `placement`, and `empty` precise; those
+fields flow into the live block vocabulary.
+
+When overriding an existing block, register the override after the shared
+library registration. Last registration wins for both `type` and MDX `tag`.
+
+After adding a block, run focused Plan tests:
+
+```bash
+pnpm --filter plan test -- plan-mdx plan-block-registry
+```
+
 ### Route map
 
 - `app/routes/plans.$id.tsx` — plan editor / review surface

package/docs/content/template-slides.md

@@ -54,14 +54,6 @@ When you open the app:
 
 Select text on a slide and hit Cmd+I to focus the agent with that selection — it'll act only on what you selected.
 
-## Why it's interesting
-
-Three things make Slides a good showcase of the framework:
-
-1. **Streamed, parallel generation.** The agent fires parallel `add-slide` calls so you see the deck assemble in real time — one slide at a time — rather than waiting for a full batch. That pattern works for any content type that benefits from progressive rendering.
-2. **Agent and editor share one document.** The same Yjs CRDT that lets two humans type concurrently is what the agent writes through via `update-slide --find/--replace`. There is no separate "AI-only" edit path.
-3. **Multi-modal source ingestion.** PPTX, DOCX, Google Docs, PDFs, URLs, and GitHub repos all feed through the same `import-*` action surface. Adding a new source format is a single action file; the agent picks it up immediately.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Slides template or extending it.

package/docs/content/template-videos.md

@@ -52,14 +52,6 @@ When you open the studio:
 
 If you select a track in the timeline and hit Cmd+I, the agent picks up that selection — "make this one snappier" just works.
 
-## Why it's interesting
-
-Three things make the Video template a good showcase of the framework:
-
-1. **Code as the authoring format.** Each composition is a React component, so the agent can write entirely new animation types — not just adjust parameters. The template demonstrates that an agent-native app can treat source code as a first-class editable artifact rather than a fixed runtime.
-2. **Track-based animation as structured data.** Animations are `AnimationTrack` rows (start, end, easing, animated props) rather than hardcoded frame checks. This makes AI edits ("shift this track 10 frames later") reliable and composable without touching render logic.
-3. **SQL + localStorage fusion.** User-created compositions persist in SQL; per-session tweaks (easing experiments, parameter knobs) persist in localStorage and deep-merge on load. This two-layer approach shows how to keep the agent's durable state separate from ephemeral in-session exploration.
-
 ## For developers
 
 The rest of this doc is for anyone forking the Video template or extending it. This template is more code-forward than the others — every composition is a React component and every animation is data on a track.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.51.6",
+  "version": "0.51.7",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -108,6 +108,8 @@
     "./usage": "./dist/usage/store.js",
     "./connections": "./dist/connections/index.js",
     "./provider-api": "./dist/provider-api/index.js",
+    "./provider-api/corpus-jobs": "./dist/provider-api/corpus-jobs.js",
+    "./provider-api/corpus-jobs-store": "./dist/provider-api/corpus-jobs-store.js",
     "./provider-api/staging": "./dist/provider-api/staging.js",
     "./provider-api/staged-datasets-store": "./dist/provider-api/staged-datasets-store.js",
     "./provider-api/staged-datasets-aggregate": "./dist/provider-api/staged-datasets-aggregate.js",