@agent-native/core 0.42.0 → 0.44.0

package/dist/templates/default/.agents/skills/storing-data/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem.
 
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
 ## How It Works
 
 Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.

package/dist/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: performance
+description: >-
+  Keep apps and templates loading fast. Read when adding a data model, a
+  list/read action, a page or sidebar that loads data, or when something loads
+  slowly. Covers column projection, indexing hot-path queries, avoiding N+1 and
+  round-trip waterfalls, cheap polling, and not recomputing on every read.
+metadata:
+  internal: true
+---
+
+# Performance — Keep Loads Fast
+
+## Rule
+
+Treat every list, every read, and every page load as a latency budget. Two
+things dominate it: **how much data crosses the wire**, and **how many
+round-trips and table scans it takes**. On a hosted/serverless SQL backend each
+query is a network round-trip, and an unindexed filter scans the whole — often
+shared and growing — table. So default to **projected columns**, **indexed
+hot-path queries**, and **parallel/batched** fetches. These rules are
+provider-agnostic: they hold on SQLite, Postgres, or any managed SQL backend.
+
+This skill is about the data and load path. See the `storing-data` skill for the schema
+and migration mechanics it references, and the `real-time-sync` skill for how updates
+already reach the UI without polling.
+
+## 1. Project columns — never `SELECT *` on a list
+
+A list/index query should select only the columns the list actually renders.
+
+- **Never return heavy columns in a list**: large JSON/text blobs such as
+  document bodies, rendered HTML, `config`/`layout`/`spec`/`data`/`tracks`,
+  tool results, or base64 attachments. Pulling them for every row is the single
+  most common cause of a slow list.
+- Heavy/full columns belong on the **single-item GET/detail** path only.
+- Need a preview from a big column? Select a **truncated substring at the DB**,
+  not the whole column — and it stays portable:
+
+  ```ts
+  // Drizzle — project, and truncate the heavy column for the preview
+  const rows = await db
+    .select({
+      id: docs.id,
+      title: docs.title,
+      updatedAt: docs.updatedAt,
+      // substr/length work on both SQLite and Postgres
+      preview: sql<string>`substr(${docs.content}, 1, 400)`,
+    })
+    .from(docs)
+    .where(accessFilter(docs, docShares))
+    .orderBy(desc(docs.updatedAt));
+  ```
+
+- After narrowing the projection, update the row mapper and its return type so a
+  dropped column is provably unused on the list path. If the list genuinely
+  renders a heavy column (a thumbnail, an inline preview the UI shows), keep it —
+  don't break behavior to chase a payload win.
+
+## 2. Index the hot paths
+
+Indexes are added through the **versioned migration array** in
+`server/plugins/db.ts` as `CREATE INDEX IF NOT EXISTS …` — not through a
+schema-level `index()` helper (the framework applies indexes via migrations; see
+the `storing-data` skill). Add an index for any column a hot query **filters or sorts**
+on. The recurring ones:
+
+- **Ownable tables** → `(owner_email, org_id, <the list's ORDER BY column>)`.
+  Access scoping filters by owner/org and lists sort by `updated_at`/`created_at`.
+- **Shares tables** (`{resource}_shares`) → `(resource_id, principal_type, principal_id)`.
+  Access checks run correlated `EXISTS` subqueries against these on every list.
+- **Child / foreign-key columns** used to load children (e.g. `responses.form_id`,
+  `comments.parent_id`, an events log's `*_id`) → index the FK, plus its sort
+  column when the children are ordered. An unindexed FK means a full scan of the
+  child table on every parent open. **A foreign-key reference does not create an
+  index automatically** — add it explicitly.
+- **Status-filtered lists** → match the real `WHERE`, e.g. `(owner_email, status)`
+  or `(status, <sort>)`.
+
+Keep index DDL **dialect-agnostic and idempotent**:
+
+```sql
+CREATE INDEX IF NOT EXISTS forms_owner_org_updated_idx ON forms (owner_email, org_id, updated_at)
+```
+
+No `DESC`, no partial `WHERE`, no provider-specific syntax — it then runs on
+SQLite and Postgres alike, is safe to re-run, and applies on next startup.
+Indexes mostly bite **as data grows** and on **unbounded child tables** (a
+seq-scan of 10 rows is instant; of a shared, ever-growing log it is not), so
+index the growing tables first.
+
+## 3. Don't fan out queries — batch and parallelize
+
+- **No N+1.** Never loop issuing one query per item. Load children for many
+  parents in one `inArray(child.parentId, ids)` query, then group in memory.
+- **Count in SQL** (`count()`), never "select all rows then `.length`".
+- **Parallelize independent queries** with `Promise.all` rather than sequential
+  `await`s — each `await` is another round-trip.
+- Prefer **one composed endpoint** over several dependent calls.
+
+## 4. Avoid client-side waterfalls
+
+- Don't gate query B on query A's result unless B truly needs it. Fire
+  independent `useActionQuery` / `useQuery` hooks **in parallel**; never make the
+  loading skeleton wait on a serial chain.
+- Load the visible page from one read where possible, and **lazy-load**
+  secondary / below-the-fold data after first paint.
+
+## 5. Poll cheaply; compute once
+
+- Updates already reach the UI through the `real-time-sync` skill (`useDbSync` / SSE).
+  Don't add an aggressive `refetchInterval` that re-runs a heavy list/read every
+  couple of seconds. If you must poll, use a **wide interval** and a **cheap**
+  endpoint.
+- **Never do expensive per-request work on a read that runs on every load/poll**:
+  re-rendering HTML/markdown, pretty-printing, re-parsing / migrating /
+  normalizing / sanitizing stored JSON. Do that work at **write time** (store the
+  result) or compute it **lazily only for the caller that needs it**. Reads on
+  the hot path must be cheap.
+- Data the UI doesn't display (export formats, alternate renderings) belongs in a
+  separate on-demand action, not baked into the hot read.
+
+## 6. Big payloads and long lists
+
+- **Paginate or window** unbounded lists (messages, responses, events, activity).
+  Don't load the entire history on open; load a recent window and fetch older on
+  demand.
+- Don't store **unbounded blobs inline** in a row that a list/load pulls.
+  Reference large content separately so opening the parent stays cheap.
+- **Virtualize** very long rendered lists on the client so off-screen rows aren't
+  parsed/rendered every update.
+
+## Checklist — run before shipping a list/read or a new table
+
+- [ ] List selects only displayed columns; heavy blobs excluded or `substr`-truncated.
+- [ ] Every hot-path `WHERE` / `ORDER BY` column is indexed (owner/org/sort,
+      shares `resource_id`, child FKs, status filters) via a `db.ts` migration.
+- [ ] No N+1; independent queries parallelized; counts via SQL `count()`.
+- [ ] Client fires independent queries in parallel, not a waterfall.
+- [ ] No heavy recompute on every read; no aggressive polling of heavy endpoints.
+- [ ] Unbounded lists are paginated/windowed; large blobs aren't inlined on the hot path.

package/dist/templates/workspace-core/.agents/skills/storing-data/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem.
 
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
 ## How It Works
 
 Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.

package/docs/content/plan-plugin.md

@@ -1,20 +1,20 @@
 ---
 title: "Plan plugin & marketplace"
-description: "Install the Agent-Native Plan skills (/visual-plan, /visual-recap, /ui-plan, /prototype-plan, /plan-design, /visual-questions) plus the hosted Plan MCP connector as a Claude Code or Codex plugin, or with the universal CLI. How updates work and whether you need to submit anything."
+description: "Install the Agent-Native Plan skills (/visual-plan, /visual-recap) plus the hosted Plan MCP connector as a Claude Code or Codex plugin, or with the universal CLI. How updates work and whether you need to submit anything."
 ---
 
 # Plan plugin & marketplace
 
-The Agent-Native **Plan** app ships as one installable bundle. A single install adds all six Plan slash-command skills **and** wires up the hosted Plan MCP connector, so the agent can generate plans and the skills can publish them straight into the Plan app.
+The Agent-Native **Plan** app ships as one installable bundle. A single install adds both Plan slash-command skills **and** wires up the hosted Plan MCP connector, so the agent can generate plans and the skills can publish them straight into the Plan app.
 
 ## What you get {#what-you-get}
 
 One install gives you:
 
-- **Six skills** — `/visual-plan` (the canonical entry point), `/visual-recap`, `/ui-plan`, `/prototype-plan`, `/plan-design`, and `/visual-questions`.
+- **Two skills** — `/visual-plan` (the canonical entry point) and `/visual-recap`.
 - **The Plan MCP connector** — registered against the hosted app at `https://plan.agent-native.com` (MCP endpoint `https://plan.agent-native.com/_agent-native/mcp`, server name `agent-native-plans`).
 
-All six skills **always publish to the hosted Plan app** — they create a plan via the MCP connector and hand you a link or inline plan to review. They never dump an inline Markdown/ASCII plan into chat as the deliverable. If a Plan tool returns `needs auth`, `Unauthorized`, or `Session terminated`, authenticate the connector (see each route below) instead of falling back to inline output.
+Both skills **always publish to the hosted Plan app** — they create a plan via the MCP connector and hand you a link or inline plan to review. They never dump an inline Markdown/ASCII plan into chat as the deliverable. If a Plan tool returns `needs auth`, `Unauthorized`, or `Session terminated`, authenticate the connector (see each route below) instead of falling back to inline output.
 
 > The plugin (`agent-native-visual-plans`) carries app id `visual-plans`, which is why the Claude Code plugin name and Codex plugin name are both `agent-native-visual-plans`. The Plan app's display name is "Agent-Native Plan".
 
@@ -24,7 +24,7 @@ There are three ways in. The **universal CLI route** is the one we recommend by
 
 ### Universal skill route (any MCP host) {#universal}
 
-Works for any host — Claude Code, Codex, Cursor, Cline, Goose, ChatGPT custom MCP apps, Claude Cowork, and anything else MCP-compatible. The Agent-Native CLI installs the six skills, registers the hosted Plan MCP connector, **and authenticates it in the same step**, so your first tool call does not hit an OAuth wall:
+Works for any host — Claude Code, Codex, Cursor, Cline, Goose, ChatGPT custom MCP apps, Claude Cowork, and anything else MCP-compatible. The Agent-Native CLI installs both skills, registers the hosted Plan MCP connector, **and authenticates it in the same step**, so your first tool call does not hit an OAuth wall:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan
@@ -32,7 +32,7 @@ npx @agent-native/core@latest skills add visual-plan
 agent-native skills add visual-plan
 ```
 
-This installs `visual-plan` plus the companion `visual-recap`, `visual-questions`, `ui-plan`, `prototype-plan`, and `plan-design` skills, then registers the `agent-native-plans` connector and runs auth (OAuth prompt for hosted/account-backed sharing). Useful flags:
+This installs `visual-plan` plus the companion `visual-recap` skill, then registers the `agent-native-plans` connector and runs auth (OAuth prompt for hosted/account-backed sharing). Useful flags:
 
 - `--client codex|claude-code|claude-code-cli|cowork|all` — which local agents to write the MCP config for (default `codex`).
 - `--no-connect` — register the connector without authenticating; run `agent-native connect https://plan.agent-native.com` later.
@@ -54,7 +54,7 @@ The public `BuilderIO/agent-native` repo is itself a Claude Code plugin marketpl
 /mcp        # authenticate the Plan connector (one OAuth approval)
 ```
 
-`/plugin install` adds the six Plan skills and a **URL-only** MCP config (no secrets in the package); `/mcp` → **Authenticate** completes the OAuth handshake.
+`/plugin install` adds both Plan skills and a **URL-only** MCP config (no secrets in the package); `/mcp` → **Authenticate** completes the OAuth handshake.
 
 > The marketplace catalog is named `agent-native-apps` and the Plan plugin is `agent-native-visual-plans`, so the install target is always `agent-native-visual-plans@agent-native-apps`.
 
@@ -101,7 +101,7 @@ Under the hood, all three routes are produced from the same source by the `agent
 
 ## What's next {#whats-next}
 
-- [**Visual Plans**](/docs/visual-plans) — what the skills do and how to use them
+- [**Visual Plans**](/docs/template-plan) — what the skills do and how to use them
 - [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request
 - [**Skills Guide**](/docs/skills-guide) — app-backed skills and the manifest format
 - [**External Agents**](/docs/external-agents) — connect any MCP host and round-trip artifacts

package/docs/content/pr-visual-recap.md

@@ -5,7 +5,7 @@ description: "A GitHub Action that runs your repo's visual-recap skill on every
 
 # PR Visual Recap
 
-PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs your repo's [`visual-recap`](/docs/visual-plans) skill against the PR diff, publishes a structured recap plan to the hosted Plans app, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
+PR Visual Recap is a GitHub Action that turns every pull request into a **visual code review**. On each push, an LLM coding agent runs your repo's [`visual-recap`](/docs/template-plan) skill against the PR diff, publishes a structured recap plan to the hosted Plans app, and upserts **one sticky PR comment** that links to the interactive plan with an **inline screenshot** embedded right in the comment.
 
 This is not a deterministic diff renderer. The action invokes a real coding agent (Claude Code CLI by default, or OpenAI Codex CLI) that reads the change, decides what matters, and authors the recap by calling the Plans MCP tool `create-visual-recap` — the same tool the `/visual-recap` slash command uses. You get a high-altitude, schema/API/before-after view of the change instead of a wall of raw diff.
 
@@ -99,5 +99,5 @@ The recap is a review aid layered on top of the normal PR flow:
 
 ## Related
 
-- [Visual Plans](/docs/visual-plans) — the `/visual-plan` and `/visual-recap` skills, the hosted Plans connector, and the interactive review surface this action publishes to.
+- [Visual Plans](/docs/template-plan) — the `/visual-plan` and `/visual-recap` skills, the hosted Plans connector, and the interactive review surface this action publishes to.
 - [Skills](/docs/skills-guide) — installing agent-native skills into your coding agent.

package/docs/content/template-plan.md

@@ -1,9 +1,9 @@
 ---
-title: "Plans"
-description: "Install Agent-Native Plans as an app-backed skill for Codex, Claude Code, and other coding agents. Create structured visual plans with diagrams, wireframes, annotations, comments, and share links."
+title: "Visual Plans"
+description: "Agent-Native Plans turns your coding agent's plan into a structured, reviewable document — diagrams, wireframes, annotated code, comments, and share links. Install once from the CLI; reviewers you share with edit as a guest and sign in only to save or share."
 ---
 
-# Plans
+# Visual Plans
 
 Agent-Native Plans is visual plan mode for coding agents. It turns an ordinary
 Codex, Claude Code, Markdown, or pasted implementation plan into a structured
@@ -18,11 +18,20 @@ agent the same way.
 
 ![Agent-Native Plans review surface](https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2Fdd73f749f8c54dbcb577420ab1a18788)
 
-## Install the skill
+There are two ways into Plans:
+
+- **From your coding agent (CLI)** — one command installs the skill, registers
+  the hosted Plans connector, and authenticates it.
+- **In the browser** — anyone you share with can open the editor and create or
+  edit as a **guest, with no sign-up**. They sign in only when they want to save
+  or share.
+
+## Install the skill {#install}
 
 Use the Agent-Native CLI. This is the recommended setup because it installs the
-Plans skill instructions, registers the hosted Plans MCP connector, and runs the
-client-specific auth/setup flow in one step:
+Plans skill instructions, registers the hosted Plans MCP connector, **and** runs
+the client-specific auth/setup flow in one step, so your first tool call does not
+hit an OAuth wall:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan
@@ -36,10 +45,16 @@ agent-native skills add visual-plan
 
 The command installs both commands: `/visual-plan` and `/visual-recap`.
 
-Use `/visual-plan` for both fresh plans and existing Codex, Claude Code,
-Markdown, or pasted plans; when source plan text already exists, the agent builds
-from that plan instead of starting over. Use `/visual-recap` to review a change
-that already landed instead of writing one up by hand.
+Authentication is a one-time browser sign-in at setup — this is intended, and it
+is what lets the agent persist and share the plans it generates. What the auth
+step does depends on your client:
+
+- **OAuth-capable hosts** (Claude Code) get a URL-only MCP entry plus a prompt to
+  run `/mcp` and choose **Authenticate**.
+- **Codex / Cowork** run a short browser device-code flow: the CLI prints a code,
+  opens the verification page, and writes the connector once you approve.
+- In a **non-interactive shell or CI**, the auth step is skipped and the exact
+  command to run later is printed for you.
 
 By default the CLI targets Codex. Add `--client claude-code` or `--client all`
 when you want to configure another host:
@@ -48,6 +63,22 @@ when you want to configure another host:
 npx @agent-native/core@latest skills add visual-plan --client all
 ```
 
+Pass `--no-connect` to register the connector without authenticating, then run
+`agent-native connect https://plan.agent-native.com` whenever you are ready:
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --no-connect
+```
+
+To auto-generate a recap on **every pull request**, pass `--with-github-action`.
+This writes a GitHub Action that runs the `visual-recap` skill on each PR and
+posts an interactive recap plan with an inline screenshot as a sticky comment —
+see [PR Visual Recap](/docs/pr-visual-recap).
+
+```bash
+npx @agent-native/core@latest skills add visual-plan --with-github-action
+```
+
 If you only want the portable instruction file through the open Skills CLI, use:
 
 ```bash
@@ -57,6 +88,11 @@ npx skills add BuilderIO/agent-native --skill visual-plan
 That installs the skill instructions only. It does not register the hosted MCP
 connector, so use the Agent-Native CLI path when you want the one-command setup.
 
+> **Prefer a one-install plugin?** Claude Code and Codex can add
+> `BuilderIO/agent-native` directly as a plugin marketplace, which bundles the
+> Plan skills _and_ the connector in one install and auto-updates as the skills
+> improve — see [Plan plugin & marketplace](/docs/plan-plugin).
+
 ## Use it from your coding agent
 
 After installation, ask your agent for the command that fits the work:
@@ -74,6 +110,10 @@ wrong direction would be costly. The returned Plans link opens the review UI so
 you can annotate, correct, choose options, and ask for updates before code
 changes begin.
 
+When a Codex, Claude Code, Markdown, or pasted plan already exists, use
+`/visual-plan`; the agent preserves that source plan and builds the richer review
+surface from it instead of starting over.
+
 If the first pass still has answerable decisions, the agent can place an
 **Open Questions** form at the bottom of the same plan. Answering it and sending
 it to the agent starts a revision turn against the existing plan.
@@ -91,14 +131,36 @@ it to the agent starts a revision turn against the existing plan.
   prose block, visual comments include exact target metadata, and browser
   handoff includes focused screenshots for a small set of visual/canvas comment
   locations instead of one hard-to-read giant image.
-- **Share with reviewers.** Hosted Plans can create private review links and
-  account-backed sharing. Viewing shared plans works from the browser; saving
-  and sharing require sign-in.
 - **Export the result.** Keep an HTML, Markdown, or JSON receipt of the plan
   when you need a source-control-friendly handoff.
-- **Run locally when needed.** The template can be self-hosted for development
-  or offline workflows, while the hosted skill is the easiest path for normal
-  coding-agent use.
+
+## Editing in the browser as a guest {#guest}
+
+People you share a plan with do not need to install anything. They open the Plans
+editor and **create and edit with no sign-up** — they work as a guest. Signing in
+is only required when someone wants to **save or share** their own work.
+
+When a guest signs in, the plans they created as a guest are **claimed** into
+their account, so nothing they built is lost.
+
+Plan prose edits inline: click into any text section, type, format with the rich
+editor toolbar or slash menu, and Plans autosaves the underlying markdown. Review
+annotation mode temporarily turns text sections read-only so clicks can pin
+feedback; leave review mode to keep editing prose.
+
+## Sharing and commenting {#sharing}
+
+Sharing and commenting are the workflows that need an account:
+
+- **Viewing** a public or shared plan works for anyone with the link — no account
+  required.
+- **Commenting** on a shared plan requires an agent-native account.
+- **Sharing** a plan (publishing it to a link, private sharing, reviewer access,
+  cross-device or team review) requires signing in. Google sign-in appears when
+  the standard Google OAuth env vars are configured.
+
+The hosted Plans connector lives at `https://plan.agent-native.com/_agent-native/mcp`.
+Never put shared secrets in skill files.
 
 ## Useful prompts
 
@@ -108,6 +170,14 @@ it to the agent starts a revision turn against the existing plan.
 - "Run `/visual-recap` on this PR so I can review the shape of the change first."
 - "Use `/visual-recap` on the diff between `main` and this branch."
 
+## Recovering from auth errors {#auth-errors}
+
+If a Plans tool ever returns `needs auth`, `Unauthorized`, or `Session
+terminated`, do not keep retrying it. Authenticate the connector with
+`agent-native connect https://plan.agent-native.com` (or re-run `/mcp` →
+**Authenticate** in an OAuth-capable host), then continue once the connector is
+available.
+
 ## For developers
 
 The rest of this doc is for anyone forking or self-hosting the Plans template.
@@ -130,10 +200,17 @@ The hosted app-backed skill uses:
 The local template is useful when you are developing Plans itself, testing local
 persistence, or running a fully self-hosted review surface.
 
+### Local mode (advanced, offline)
+
+For fully offline, no-account use, you can run the Plans app locally and sync
+your plans to your repo as MDX. This local mode is a separate, advanced path —
+not the default hosted flow — and is best when you need everything to stay on
+your machine and in version control.
+
 ## What's next
 
-- [**Visual Plans**](/docs/visual-plans) — the full skill flow and auth details
 - [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request
+- [**Plan plugin & marketplace**](/docs/plan-plugin) — install the Plan skills as a Claude Code or Codex plugin
 - [**Skills**](/docs/skills-guide) — how Agent-Native installs skills
 - [**MCP Clients**](/docs/mcp-clients) — configuring hosted MCP connectors
 - [**Templates**](/docs/cloneable-saas) — the clone-and-own model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -198,6 +198,7 @@
     "react-router": "^7.16.0",
     "recharts": "3.8.1",
     "remark-gfm": "^4.0.1",
+    "roughjs": "4.6.6",
     "shiki": "^4.0.2",
     "tailwind-merge": "^3.5.0",
     "tiptap-markdown": "^0.9.0",

package/src/templates/default/.agents/skills/storing-data/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem.
 
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
 ## How It Works
 
 Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.

package/src/templates/workspace-core/.agents/skills/performance/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: performance
+description: >-
+  Keep apps and templates loading fast. Read when adding a data model, a
+  list/read action, a page or sidebar that loads data, or when something loads
+  slowly. Covers column projection, indexing hot-path queries, avoiding N+1 and
+  round-trip waterfalls, cheap polling, and not recomputing on every read.
+metadata:
+  internal: true
+---
+
+# Performance — Keep Loads Fast
+
+## Rule
+
+Treat every list, every read, and every page load as a latency budget. Two
+things dominate it: **how much data crosses the wire**, and **how many
+round-trips and table scans it takes**. On a hosted/serverless SQL backend each
+query is a network round-trip, and an unindexed filter scans the whole — often
+shared and growing — table. So default to **projected columns**, **indexed
+hot-path queries**, and **parallel/batched** fetches. These rules are
+provider-agnostic: they hold on SQLite, Postgres, or any managed SQL backend.
+
+This skill is about the data and load path. See the `storing-data` skill for the schema
+and migration mechanics it references, and the `real-time-sync` skill for how updates
+already reach the UI without polling.
+
+## 1. Project columns — never `SELECT *` on a list
+
+A list/index query should select only the columns the list actually renders.
+
+- **Never return heavy columns in a list**: large JSON/text blobs such as
+  document bodies, rendered HTML, `config`/`layout`/`spec`/`data`/`tracks`,
+  tool results, or base64 attachments. Pulling them for every row is the single
+  most common cause of a slow list.
+- Heavy/full columns belong on the **single-item GET/detail** path only.
+- Need a preview from a big column? Select a **truncated substring at the DB**,
+  not the whole column — and it stays portable:
+
+  ```ts
+  // Drizzle — project, and truncate the heavy column for the preview
+  const rows = await db
+    .select({
+      id: docs.id,
+      title: docs.title,
+      updatedAt: docs.updatedAt,
+      // substr/length work on both SQLite and Postgres
+      preview: sql<string>`substr(${docs.content}, 1, 400)`,
+    })
+    .from(docs)
+    .where(accessFilter(docs, docShares))
+    .orderBy(desc(docs.updatedAt));
+  ```
+
+- After narrowing the projection, update the row mapper and its return type so a
+  dropped column is provably unused on the list path. If the list genuinely
+  renders a heavy column (a thumbnail, an inline preview the UI shows), keep it —
+  don't break behavior to chase a payload win.
+
+## 2. Index the hot paths
+
+Indexes are added through the **versioned migration array** in
+`server/plugins/db.ts` as `CREATE INDEX IF NOT EXISTS …` — not through a
+schema-level `index()` helper (the framework applies indexes via migrations; see
+the `storing-data` skill). Add an index for any column a hot query **filters or sorts**
+on. The recurring ones:
+
+- **Ownable tables** → `(owner_email, org_id, <the list's ORDER BY column>)`.
+  Access scoping filters by owner/org and lists sort by `updated_at`/`created_at`.
+- **Shares tables** (`{resource}_shares`) → `(resource_id, principal_type, principal_id)`.
+  Access checks run correlated `EXISTS` subqueries against these on every list.
+- **Child / foreign-key columns** used to load children (e.g. `responses.form_id`,
+  `comments.parent_id`, an events log's `*_id`) → index the FK, plus its sort
+  column when the children are ordered. An unindexed FK means a full scan of the
+  child table on every parent open. **A foreign-key reference does not create an
+  index automatically** — add it explicitly.
+- **Status-filtered lists** → match the real `WHERE`, e.g. `(owner_email, status)`
+  or `(status, <sort>)`.
+
+Keep index DDL **dialect-agnostic and idempotent**:
+
+```sql
+CREATE INDEX IF NOT EXISTS forms_owner_org_updated_idx ON forms (owner_email, org_id, updated_at)
+```
+
+No `DESC`, no partial `WHERE`, no provider-specific syntax — it then runs on
+SQLite and Postgres alike, is safe to re-run, and applies on next startup.
+Indexes mostly bite **as data grows** and on **unbounded child tables** (a
+seq-scan of 10 rows is instant; of a shared, ever-growing log it is not), so
+index the growing tables first.
+
+## 3. Don't fan out queries — batch and parallelize
+
+- **No N+1.** Never loop issuing one query per item. Load children for many
+  parents in one `inArray(child.parentId, ids)` query, then group in memory.
+- **Count in SQL** (`count()`), never "select all rows then `.length`".
+- **Parallelize independent queries** with `Promise.all` rather than sequential
+  `await`s — each `await` is another round-trip.
+- Prefer **one composed endpoint** over several dependent calls.
+
+## 4. Avoid client-side waterfalls
+
+- Don't gate query B on query A's result unless B truly needs it. Fire
+  independent `useActionQuery` / `useQuery` hooks **in parallel**; never make the
+  loading skeleton wait on a serial chain.
+- Load the visible page from one read where possible, and **lazy-load**
+  secondary / below-the-fold data after first paint.
+
+## 5. Poll cheaply; compute once
+
+- Updates already reach the UI through the `real-time-sync` skill (`useDbSync` / SSE).
+  Don't add an aggressive `refetchInterval` that re-runs a heavy list/read every
+  couple of seconds. If you must poll, use a **wide interval** and a **cheap**
+  endpoint.
+- **Never do expensive per-request work on a read that runs on every load/poll**:
+  re-rendering HTML/markdown, pretty-printing, re-parsing / migrating /
+  normalizing / sanitizing stored JSON. Do that work at **write time** (store the
+  result) or compute it **lazily only for the caller that needs it**. Reads on
+  the hot path must be cheap.
+- Data the UI doesn't display (export formats, alternate renderings) belongs in a
+  separate on-demand action, not baked into the hot read.
+
+## 6. Big payloads and long lists
+
+- **Paginate or window** unbounded lists (messages, responses, events, activity).
+  Don't load the entire history on open; load a recent window and fetch older on
+  demand.
+- Don't store **unbounded blobs inline** in a row that a list/load pulls.
+  Reference large content separately so opening the parent stays cheap.
+- **Virtualize** very long rendered lists on the client so off-screen rows aren't
+  parsed/rendered every update.
+
+## Checklist — run before shipping a list/read or a new table
+
+- [ ] List selects only displayed columns; heavy blobs excluded or `substr`-truncated.
+- [ ] Every hot-path `WHERE` / `ORDER BY` column is indexed (owner/org/sort,
+      shares `resource_id`, child FKs, status filters) via a `db.ts` migration.
+- [ ] No N+1; independent queries parallelized; counts via SQL `count()`.
+- [ ] Client fires independent queries in parallel, not a waterfall.
+- [ ] No heavy recompute on every read; no aggressive polling of heavy endpoints.
+- [ ] Unbounded lists are paginated/windowed; large blobs aren't inlined on the hot path.

package/src/templates/workspace-core/.agents/skills/storing-data/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. Do not store durable app data in the filesystem.
 
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
 ## How It Works
 
 Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.