npm - @agent-native/core - Versions diffs - 0.101.14 → 0.102.1 - Mend

@agent-native/core 0.101.14 → 0.102.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (316) hide show

package/corpus/templates/tasks/.agents/skills/visual-recap/references/wireframe.md ADDED Viewed

@@ -0,0 +1,264 @@
+# HTML wireframe quality — single source of truth
+This file is the canonical quality bar for HTML wireframes / `<Screen>` /
+`WireframeBlock` content, shared word for word by `/visual-plan` and
+`/visual-recap`. Read it in full before authoring ANY wireframe; do not
+author wireframes from memory or paraphrase these rules per command.
+<!-- SHARED-CORE:wireframe-quality START -->
+**A wireframe is an HTML mockup. The renderer owns the look; you write the
+content.** Set `data.html` to a self-contained, semantic HTML fragment of the
+screen and set `data.surface`. The renderer owns the surface footprint/aspect,
+the dark/light theme, the hand-drawn font, and the rough.js sketch overlay — you
+never write `<html>`/`<body>`/`<script>`/`<style>` tags or any
+width/height/coordinates. You write real HTML layout and real product
+content; the renderer styles and roughens it.
+**A wireframe block's data is an HTML screen plus a surface:**
+```json
+{
+  "surface": "browser",
+  "html": "<div style=\"display:flex;flex-direction:column;gap:10px;padding:16px;height:100%\"><h1>Sign in</h1><p class=\"wf-muted\">Use your work email to continue.</p><div class=\"wf-card\" style=\"display:flex;flex-direction:column;gap:10px\"><label>Email<input value=\"jane@acme.co\" /></label><label>Password<input value=\"••••••••\" /></label><label style=\"display:flex;align-items:center;gap:8px\"><input type=\"checkbox\" checked /> Remember me</label><button class=\"primary\">Sign in</button></div><a href=\"#\">Forgot password?</a></div>"
+}
+```
+**Write PLAIN semantic HTML and let the renderer style it.** Bare elements
+(`h1`/`h2`/`h3`, `p`, `button`, `input`, `<input type="checkbox">`, `a`, `hr`)
+are auto-themed — no classes needed. Helper classes carry the rest:
+- `.wf-card` / `.wf-box` — a bordered, padded container (a panel, a list item).
+- `.wf-pill` / `.wf-chip` — a rounded tag or filter; add `.accent`
+  (`<span class="wf-pill accent">`) for the accent-filled variant.
+- `.wf-muted` — secondary/muted text (or use `<small>`).
+- `button.primary` or any element with `[data-primary]` — the accent-filled
+  primary button.
+**No decorative shadows around mockups.** Do not put `box-shadow`, `filter:
+drop-shadow(...)`, Tailwind `shadow-*` classes, or other fake depth effects on a
+wireframe frame, root container, `.wf-card` / `.wf-box`, or canvas artboard.
+Mockups should read as flat, bordered surfaces; use spacing, borders, labels,
+and annotations for separation. Only show a shadow when the real product UI
+already has that shadow and it is essential to the change being reviewed.
+**Use renderer icons, not visible icon words.** For icon-only buttons or leading
+icons inside fields, chips, menu items, and toolbars, write an empty marker such
+as `<span data-icon="mail" aria-label="Email"></span>` or
+`<i data-icon="lock"></i>`. The renderer replaces it with a Tabler-style SVG and
+the `.wf-icon` class sizes it to the surrounding text. Supported names and
+aliases: `mail`/`email`, `lock`/`password`, `search`, `plus`/`add`, `x`/`close`,
+`check`, `chevronDown`, `chevronUp`, `chevronLeft`, `chevronRight`, `dots`/`more`,
+`chevron`/`caret`/`dropdown` (down chevron), `user`, `settings`, `calendar`,
+`bell`, `send`, `edit`, `arrowLeft`, and `arrowRight`. Do not put visible words
+like "email", "lock", "search", "chevron", or "more" where the product UI would
+show an icon; use text only when it is a real label a user would read.
+**Use the `--wf-*` tokens for any custom color, never hex.** The renderer flips
+these on light/dark, so reading them is what keeps a mockup correct in both
+themes. For any inline border, background, or text color, reference a token:
+`style="border:1.4px solid var(--wf-line)"`. The tokens are `--wf-ink` (text),
+`--wf-muted` (secondary text), `--wf-line` (borders/dividers), `--wf-paper`
+(page background), `--wf-card` (container surface), `--wf-accent` /
+`--wf-accent-fg` / `--wf-accent-soft` (brand action), `--wf-warn`, `--wf-ok`,
+and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
+renderer owns the sketch/clean font.
+**Lay out with inline `style` flex/grid.** You write the real layout —
+`display:flex; flex-direction:column; gap:10px; padding:16px` and so on — and the
+renderer never repositions anything. Compose the actual product: reproduce the
+current screen, then show the modification. Real labels, real counts, real dates,
+real button text grounded in the screen you read; not lorem or gray bars.
+**Surface presets — match the real footprint, never default to desktop+mobile.**
+Pick the `surface` that matches what the user will actually see:
+- `browser`: a web page that needs a browser chrome frame around it.
+- `desktop`: a full desktop app page or app shell.
+- `mobile`: a phone screen, only when the work is genuinely mobile.
+- `popover`: a small floating menu, dropdown, or inline popover.
+- `panel`: a side panel, inspector, or sidebar widget.
+A sidebar popover renders as a small surface, not a desktop page and a phone
+frame. Do not emit `desktop` + `mobile` variants unless responsive behavior
+actually changes the layout. For a component or widget, show one broader
+app-context frame only when placement affects understanding, then the focused
+component states.
+**Model the actual component shell for small surfaces.** A rendered UI change
+belongs in a wireframe; reserve `diagram` for architecture, dependency, state,
+or data-flow relationships. Popovers, dropdown menus, command palettes, and
+context menus use `surface: "popover"` unless the surrounding page placement is
+the point of the change. Dialogs, sheets, inspectors, sidebars, and long
+property panels use the matching `panel` / `desktop` surface as appropriate.
+Show the real chrome: trigger or anchor when it matters, title/header row,
+top-right actions, separators, fields, options, selected states, body content,
+and footer actions that are visible in the workflow.
+**Modify, don't redesign.** When the task changes an existing screen, reproduce
+the current screen's real layout and footprint FIRST, then change only the delta
+and call it out with a single annotation. Do not restack the page into a new
+layout. For net-new surfaces, compose from the real app shell. Inspect the
+actual app components before drawing an existing product: sidebar density,
+toolbar actions, overflow menus, property panels, and framework chrome should
+match the product unless the plan intentionally changes them.
+**Keep product screens pure.** A product wireframe shows the app state a user
+would actually see. Do not embed file contracts, architecture arrows, repo pills,
+mode explanations, or implementation callouts inside the screen just to explain
+the plan. Put those in canvas annotations, a separate diagram, or the document
+body. Secondary UI such as properties, history, sync, export, or agent controls
+should appear where the real product would put them: an overflow popover, sheet,
+panel, or separate framework sidebar state, not a generic permanent right
+inspector unless that inspector is the actual design.
+**Classify mockup scope before implementation.** Before turning a plan mockup
+into source code, decide whether each artboard represents the whole page/app
+shell, a route body inside an existing shell, or a component/sub-surface. If an
+artboard includes navigation, sidebars, auth banners, or a signup/login form,
+map those pieces to the real shared shell/auth components instead of nesting the
+entire mockup inside the current page. When a mockup references the product's
+standard signup/login page, find and reuse that existing implementation; do not
+approximate it from the wireframe.
+**Zoom in on sub-surfaces, don't redraw the page.** For a small sub-surface (a
+popover, menu, dialog, toast), show the full screen once, then add a small
+separate artboard whose `html` contains ONLY that sub-surface — do not re-draw
+the whole page around it, and do not scale a duplicate up. Pick the matching
+`surface` (e.g. `popover`) so the footprint is right; never widen a popover to
+page width.
+**Loading / skeleton states.** Set `data.skeleton: true` on the wireframe and
+fill the `html` with neutral, textless placeholder geometry — boxes and bars
+built as `<div>`s with `background:var(--wf-line)` and explicit heights/widths,
+no labels or copy. The renderer drops borders, sketch, and color into the
+skeleton register automatically. Never escape to a `custom-html` document block
+to fake a loader.
+**Editing an existing mockup.** In hosted mode, to change one element, text, or
+color in an existing html mockup, do not regenerate the frame — call
+`update-visual-plan` with
+`contentPatches: [{ op: "patch-wireframe-html", blockId, edits: [{ find,
+replace }] }]`. Each `find` is a unique snippet of the current html (read it
+first with `get-visual-plan`); set `all: true` on an edit to replace every
+occurrence. The result is re-sanitized. In local-files privacy mode, do not call
+hosted Plan tools; edit the local MDX source directly and rerun the local
+check/serve or verify command for `<plan-dir>`.
+**Treat the wireframe border as part of the visible design.** Always wrap HTML
+wireframe content in a root container with real inner padding before drawing
+cards, fields, pills, labels, or controls. Use at least 14-16px of padding,
+`box-sizing: border-box`, `height: 100%`, and `gap` between child rows so the
+first row never sits flush against the screen border. Keep text away from
+borders: every container, field, button, menu item, and annotation needs enough
+padding and line-height to read cleanly in the rendered Plan view.
+**Lay out children safely so they never collide.** Use HTML flex/grid with
+`gap`, `min-width: 0`, and sensible overflow. Avoid negative margins, absolute
+positioning, or fixed child widths that can collide when the renderer switches
+between light/dark, sketch/clean, or different zoom levels.
+**Do not wrap intentionally single-line labels.** For toolbars, tab rails,
+breadcrumbs, chip/filter rows, branch and file names, file chips, and code
+filenames — any deliberately single-line row — do not let long text wrap. Put
+`white-space: nowrap` on the row (and `overflow: hidden; text-overflow: ellipsis`
+on the individual labels that can grow), so the wireframe demonstrates the actual
+layout behavior instead of producing ugly stacked or vertical text. Use
+horizontally scrollable or clipped rails for overflow.
+**Fill the frame; keep labels short.** Each artboard is a fixed-size surface — compose enough realistic HTML to fill it top to bottom with even vertical rhythm; never leave a large empty band. On desktop/app-shell sidebars, let the nav stack flex to fill (`flex:1`) and add any persistent bottom action/status after it so the rail reads complete in taller frames. On mobile especially, flow real rows down the whole screen (status bar, header, then list/detail content) rather than a header floating above a gap. Keep every label short enough to sit on one line within its column — shorten the copy rather than relying on the frame to absorb it (long labels wrap or clip).
+**Persistent chrome bars span the full frame width.** Top bars, app headers,
+toolbars, and bottom tab/nav bars are full-width chrome, not centered content.
+Lay each one out as a single flex row that fills the frame
+(`style="display:flex;align-items:center;width:100%"`) and push trailing actions
+to the right edge with a flex spacer (`<div style="flex:1"></div>`) between the
+leading group and the trailing group — never center a bar inside a narrow,
+centered block, and never let it collapse to the width of its contents. In a
+Before/After pair the bar stays full-width in BOTH states even when one state has
+fewer controls; the spacer absorbs the difference so the remaining controls hold
+their edge alignment instead of sliding to the center.
+**Pin bottom bars to the bottom of the frame.** For mobile tab bars, footers, and
+any persistent bottom action row, make the frame itself a flex column at
+`height:100%` (`style="display:flex;flex-direction:column;height:100%"`), give the
+scrolling body `flex:1` so it absorbs the slack, and place the bar as the LAST
+child of the frame (or set `margin-top:auto` on it). The bar then sits flush at
+the bottom of the surface instead of floating directly under the content with an
+empty band beneath it.
+**Before / after must be comparable.** When showing a state change, preserve the
+unchanged controls in both states so the reviewer can see exactly what moved or
+appeared; do not show an added control as a generic box floating elsewhere in
+the surface. Place the new/changed affordance where the implementation puts it —
+for example, a new `Edit with AI` action in a popover header belongs in the
+top-right header slot, aligned with the title, not in the body or footer. Use
+the same frame size, scale, outer padding, border radius, and visual density on
+both sides unless the change itself alters those properties, and let the frame
+height fit the content rather than leaving a tall empty lower half.
+**Name the states with the column header, never inside the frame.** For
+document-body wireframes (recaps), put the two
+states in a `columns` block and set each column's `label` to `Before` and
+`After` — the renderer draws that label as an `h4` heading above each frame. Do
+NOT bake a `Before`/`After` pill, title, or heading into the wireframe `html`: a
+label placed inside reads as part of the product UI, lands in a random corner,
+and clutters the comparison. The column header is the one and only place the
+state name belongs. On a canvas, place the two state artboards as neighbors with
+frame labels — never encode Before/After inside the html.
+**Let the surface choose side-by-side vs. stacked.** For document-body
+wireframes (recaps), the `columns` renderer lays
+narrow surfaces (`mobile`, `popover`, `panel`) out side by side, and
+automatically stacks wide surfaces (`desktop`, `browser`) vertically at full
+document width so a large frame is never crushed into a half-width column and
+cropped. Author both wireframes with the real `surface` and the matching
+`Before`/`After` column labels; do not hand-stack the pair into separate
+top-level wireframes or duplicate the state name as body content.
+**Good example — a contacts list, surface `browser`.** A small, real screen
+composed from the helper classes and tokens, layout in inline flex, no fonts or
+hex colors:
+```html
+<div
+  style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"
+>
+  <div style="display:flex;align-items:center;justify-content:space-between">
+    <h1>Contacts</h1>
+    <button class="primary">New contact</button>
+  </div>
+  <div style="display:flex;gap:6px">
+    <span class="wf-pill accent">All 128</span>
+    <span class="wf-pill">Favorites</span>
+    <span class="wf-pill">Archived</span>
+  </div>
+  <div
+    class="wf-card"
+    style="display:flex;flex-direction:column;gap:0;padding:0"
+  >
+    <div
+      style="display:flex;align-items:center;gap:10px;padding:10px 12px;border-bottom:1.4px solid var(--wf-line)"
+    >
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Jane Cooper</strong><br /><small>jane@acme.co</small>
+      </div>
+      <span class="wf-pill">Lead</span>
+    </div>
+    <div style="display:flex;align-items:center;gap:10px;padding:10px 12px">
+      <div
+        style="width:32px;height:32px;border-radius:999px;background:var(--wf-accent-soft)"
+      ></div>
+      <div style="flex:1">
+        <strong>Marcus Lee</strong><br /><small>marcus@globex.io</small>
+      </div>
+      <span class="wf-pill">Customer</span>
+    </div>
+  </div>
+</div>
+```
+<!-- SHARED-CORE:wireframe-quality END -->

package/corpus/templates/tasks/.claude/commands/visual-plan.md ADDED Viewed

@@ -0,0 +1,9 @@
+---
+description: Create an interactive Agent-Native visual plan for the current task.
+argument-hint: [optional request or scope]
+---
+Use the visual-plan skill for this task. Treat any arguments as the user's
+requested plan scope or focus:
+$ARGUMENTS

package/corpus/templates/tasks/.claude/commands/visual-recap.md ADDED Viewed

@@ -0,0 +1,8 @@
+---
+description: Create an interactive Agent-Native visual recap for a PR, branch, commit, or diff.
+argument-hint: [PR, branch, commit, diff, or scope]
+---
+Use the visual-recap skill. Treat any arguments as the recap target or focus:
+$ARGUMENTS

package/corpus/templates/tasks/.env.example ADDED Viewed

@@ -0,0 +1,5 @@
+# Custom health check message
+PING_MESSAGE=pong
+# Skip login/signup (local dev / preview only)
+# AUTH_DISABLED=true

package/corpus/templates/tasks/.ignore ADDED Viewed

File without changes

package/corpus/templates/tasks/.prettierrc ADDED Viewed

@@ -0,0 +1,5 @@
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "all"
+}

package/corpus/templates/tasks/AGENTS.md ADDED Viewed

@@ -0,0 +1,158 @@
+# tasks — Agent Guide
+Tasks is a task-list-first agent-native app. The task list at `/tasks` is the default home; chat stays available for capture and agent operations. Actions are the contract shared by UI, chat, HTTP, MCP, A2A, and CLI.
+## Core Rules
+- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- Follow the root framework contract: data in SQL, actions first, application state for navigation/selection, and shared agent chat for AI work.
+- Use actions for app operations and keep frontend/API parity.
+- Prefer improving the action surface before adding new pages. The task list is the primary durable UI for MVP.
+- Keep the action surface small: task CRUD actions plus `reorder-tasks`, `view-screen`, and `navigate`.
+- Do not use `db-query` for normal task operations.
+- Call `view-screen` first when the user's visible task context matters (especially on `/tasks`).
+## Actions
+| Action                       | Method | Purpose                                                                                      |
+| ---------------------------- | ------ | -------------------------------------------------------------------------------------------- |
+| `list-tasks`                 | GET    | List current user's tasks; `includeDone` and `includeFields` default to false                |
+| `create-task`                | POST   | Create a task with `title`                                                                   |
+| `update-task`                | POST   | Patch `title`, `done`, and/or `fieldValues` by `taskId`                                      |
+| `delete-task`                | POST   | Delete a task by `taskId` (confirm with user first)                                          |
+| `bulk-update-tasks`          | POST   | Patch `title` and/or `done` on multiple tasks by id                                          |
+| `bulk-delete-tasks`          | POST   | Delete multiple tasks by id (confirm with user first)                                        |
+| `reorder-tasks`              | POST   | Reorder visible tasks by id list top-to-bottom                                               |
+| `list-inbox-items`           | GET    | List current user's inbox items                                                              |
+| `create-inbox-item`          | POST   | Create a not-ready inbox item with `title` (default chat capture)                            |
+| `update-inbox-item`          | POST   | Patch inbox item `title` by `inboxItemId`                                                    |
+| `delete-inbox-item`          | POST   | Delete an inbox item (confirm with user first)                                               |
+| `mark-inbox-item-ready`      | POST   | Promote inbox item to an incomplete task                                                     |
+| `reorder-inbox-items`        | POST   | Reorder inbox items by id list top-to-bottom                                                 |
+| `list-custom-fields`         | GET    | List custom field definitions                                                                |
+| `create-custom-field`        | POST   | Create a custom field definition with `title`, `type`, and optional `config`                 |
+| `update-custom-field`        | POST   | Patch a field definition `title` and/or type-compatible `config`; type is immutable          |
+| `delete-custom-field`        | POST   | Delete a field definition and its values on every task (confirm with user first)             |
+| `reorder-custom-fields`      | POST   | Reorder custom field definitions by id list top-to-bottom                                    |
+| `list-visible-task-fields`   | GET    | List custom field ids shown on task cards for the current user                               |
+| `update-visible-task-fields` | POST   | Replace which custom fields appear on task cards (max 3)                                     |
+| `view-screen`                | —      | Read navigation, UI bulk selection, visible tasks, and inbox snapshot                        |
+| `navigate`                   | —      | Move UI to a view: `tasks`, `inbox`, `fields`, `extensions`, `team` (`home`/`ask` → `tasks`) |
+## Store Functions And Transactions
+Every store in `server/**/store.ts` exposes full CRUD for its entity: `create`,
+`get` + `list`, `update`, `delete`. Naming follows three rules:
+- **Unsuffixed means "by ids."** `deleteCustomFieldValues({ ids })` deletes by
+  value id. Any other selector is explicit: `deleteCustomFieldValuesByTaskIds`,
+  `deleteCustomFieldValuesByFieldIds`, `updateCustomFieldValuesByTaskId`.
+- **The plural is the implementation; the singular delegates to it** with a
+  one-element id list. `deleteTask` calls `deleteTasks`, `updateCustomFieldValue`
+  calls `updateCustomFieldValues`. Never write the same query twice.
+- **`list` takes every selector as optional** rather than splitting into `ByX`
+  variants — `listStoredItems({ ids?, includeDone? })`,
+  `listCustomFieldValues({ ids?, taskIds?, fieldIds? })`.
+Where a patch is genuinely per-row (custom field title/config, a task's field
+values), the bulk form takes one entry per id instead of one patch across ids.
+Upsert counts as create; do not add a separate `create` for upserted rows.
+Action names are a separate public surface and do not follow this convention:
+the `bulk-delete-tasks` action still exists and calls `deleteTasks`.
+Every function takes the database handle as an **optional trailing argument**,
+so it runs standalone or joins a caller's transaction. The handle is defined
+once, in `server/db/transaction.ts`:
+```ts
+export type DbHandle = Pick<
+  ReturnType<typeof getDb>,
+  "select" | "insert" | "update" | "delete" | "transaction"
+>;
+```
+## Commit Message Conventions
+- Never include `Made-with: Cursor` in commit messages. Remove it if it appears
+  in a generated message.
+- Use one of these prefixes:
+  - `feature: ...` or `feature(PROJECT): ...`
+  - `fix: ...` or `fix(PROJECT): ...`
+  - `refactor: ...` or `refactor(PROJECT): ...`
+  - `technical: ...` or `technical(PROJECT): ...`
+  - `chore: ...` or `chore(PROJECT): ...`
+- `PROJECT` is optional. If provided, it must be one of `generator` or `web`.
+- Before creating any commit, always:
+  - ask for confirmation,
+  - show the proposed commit message first,
+  - commit only after explicit user approval.
+## Commit Message Conventions
+- Never include `Made-with: Cursor` in commit messages. Remove it if it appears
+  in a generated message.
+- Use one of these prefixes:
+  - `feature: ...` or `feature(PROJECT): ...`
+  - `fix: ...` or `fix(PROJECT): ...`
+  - `refactor: ...` or `refactor(PROJECT): ...`
+  - `technical: ...` or `technical(PROJECT): ...`
+  - `chore: ...` or `chore(PROJECT): ...`
+- `PROJECT` is optional. If provided, it must be one of `generator` or `web`.
+- Before creating any commit, always:
+  - ask for confirmation,
+  - show the proposed commit message first,
+  - commit only after explicit user approval.
+## Application State
+Default navigation shape on `/tasks`:
+```json
+{
+  "view": "tasks",
+  "path": "/tasks",
+  "includeDone": false,
+  "taskId": "optional-selected-id",
+  "fieldId": "optional-selected-field-id"
+}
+```
+- `includeDone` mirrors the task-list filter toggle (incomplete only vs show all).
+- `taskId` highlights a row when opened from a deep link; MVP has no detail page.
+- `fieldId` highlights a custom field when opened from a deep link; the Fields page manages definitions.
+- Chat lives at `/chat`. Root `/` redirects to `/tasks`.
+## Agent behavior (MVP)
+- Capture in chat → `create-inbox-item` by default; use `create-task` only when the user asks to add directly to the task list.
+- Call `view-screen` before ambiguous edits when the user says "this task", "these tasks", "this inbox item", or "the list".
+- On `/tasks` or `/inbox`, `view-screen` returns `list` (with `items`), optional `selectedItem` (`inListSnapshot`), and optional `selection` (`selectedItems`, `selectedIdsNotInVisibleList`) when bulk-select is active.
+- Prefer `selection.selectedItems` when the user has UI rows selected; fall back to `selectedItem` for a single deep-link highlight.
+- `delete-task`, `bulk-delete-tasks`, and `delete-inbox-item` only after explicit user confirmation in chat.
+- Use `navigation.includeDone` and `list` from `view-screen` to match what the user sees on `/tasks`.
+- Use `reorder-tasks` with the same `includeDone` flag when moving tasks in the visible list.
+- Use `list-custom-fields`, `create-custom-field`, `update-custom-field`, and `delete-custom-field` for field definitions.
+- Use `reorder-custom-fields` with every field id in the desired order when moving fields in the Fields list.
+- Use `list-visible-task-fields` and `update-visible-task-fields` to read or change which fields appear on task cards (max 3, persisted per user in SQL).
+- Use `list-tasks` with `includeFields` to read per-task custom values and `update-task` with `fieldValues` to set or clear them; empty values clear the stored row.
+- On `/tasks`, `view-screen` includes `visibleTaskFields` from stored prefs for the custom fields currently shown on task cards and `selectedTaskFields` for a highlighted task.
+- On `/fields`, `view-screen` returns the field-definition list and `selectedItem` when a field is highlighted.
+- Custom field types are `text`, `rich_text`, `number`, `percent`, `currency`, `single_select`, `multi_select`, and `date`.
+- Number, percent, and currency field `precision` limits decimal places; `precision: 0` means whole numbers only. Number fields also support optional `positiveOnly`.
+- Select option colors are named tokens: `red`, `orange`, `yellow`, `green`, `blue`, `purple`, `pink`, and `gray`.
+- `delete-custom-field` only after explicit user confirmation; warn that deleting the definition removes its values on every task.
+- After code changes, include the **Change summary** from the `change-summary` skill (Code / Tests / Config / Docs with line counts).
+## Skills
+Read the relevant root skill before implementation: `adding-a-feature`, `actions`, `agent-native-docs`, `change-summary`, `storing-data`, `real-time-sync`, `security`, `delegate-to-agent`, `frontend-design`, `shadcn-ui`, and `self-modifying-code`.
+<!-- BEGIN @agent-native/skills -->
+When operating as Claude Fable, use the /efficient-fable skill always.
+When using a high-cost frontier model for codebase-heavy work, use the /efficient-frontier skill always.
+When writing final response status indicators, use the /quick-recap skill always.
+When long-running or parallel work needs usage-limit checks, use the /stay-within-limits skill always.
+<!-- END @agent-native/skills -->

package/corpus/templates/tasks/DEVELOPING.md ADDED Viewed

@@ -0,0 +1,185 @@
+# tasks — Development Guide
+This guide is for development-mode agents editing this app's source code. For app operations and tools, see AGENTS.md.
+## Tech Stack
+- **Framework:** @agent-native/core + React Router v7 (framework mode)
+- **Frontend:** React 18, Vite, TailwindCSS, shadcn/ui
+- **Routing:** File-based via `flatRoutes()` — SSR shell + client rendering
+- **Backend:** Nitro (via @agent-native/core) — file-based API routing, server plugins, deploy-anywhere presets
+- **State:** SQL-backed (SSE for real-time updates)
+## Commands
+- **Dev:** `pnpm dev` (Vite dev server with both React Router + Nitro plugins)
+- **Build:** `pnpm build` (React Router build — client + SSR + Nitro server)
+- **Start:** `node .output/server/index.mjs` (production)
+## Directory Structure
+```
+app/                   # React frontend
+  root.tsx             # HTML shell + global providers
+  entry.client.tsx     # Client hydration entry
+  routes.ts            # Route config — flatRoutes()
+  routes/              # File-based page routes (auto-discovered)
+    _index.tsx         # / (chat page)
+  components/          # UI components
+  hooks/               # React hooks
+  lib/                 # Utilities (cn, etc)
+server/                # Nitro API server
+  routes/
+    api/               # Route-only endpoints (uploads, webhooks, OAuth, streaming)
+    [...page].get.ts   # SSR catch-all (delegates to React Router)
+  plugins/             # Server plugins (startup logic)
+  lib/                 # Shared server modules
+shared/                # Isomorphic code (imported by both client & server)
+actions/               # Shared app operations (defineAction; UI uses action hooks)
+  run.ts               # Script dispatcher
+  *.ts                 # Individual actions (pnpm action <name>)
+data/                  # Local development database fallback
+react-router.config.ts # React Router framework config
+.agents/skills/        # Agent skills — detailed guidance for each rule
+```
+## Framework Basics
+**SSR-first framework, CSR-by-default content:** This app uses React Router v7 framework mode with `ssr: true`. But virtually every route renders only an SSR shell (loading spinner + meta tags). Normal app data fetching happens on the client via action hooks. Server-side data fetching is the exception — only used for public pages that need SEO/OG tags.
+## Chat-First Shape
+The `/` route is the app's primary chat surface. Keep it on
+`AgentChatSurface` unless you are intentionally replacing the whole chat
+experience. The left sidebar owns the durable thread list through
+`useChatThreads`; app-specific screens can be added alongside it as nav items
+when they become useful.
+For a headless app that later needs UI, this template is the intended landing
+zone: bring the existing actions over, keep their names stable, and let the chat
+call them before adding extra screens. For a custom agent backend, keep the app
+shell and swap the chat runtime with an `AgentChatRuntime` connector instead of
+rewriting the composer/transcript UI.
+## Adding a Page
+Create a file in `app/routes/`. The filename determines the URL path:
+```
+app/routes/_index.tsx              → /
+app/routes/settings.tsx            → /settings
+app/routes/inbox.tsx               → /inbox
+app/routes/inbox.$threadId.tsx     → /inbox/:threadId
+app/routes/$id.tsx                 → /:id (dynamic param)
+```
+Each route file exports a default component, optional `meta()`, and optional `HydrateFallback()`:
+```tsx
+import MyPage from "@/pages/MyPage";
+export function meta() {
+  return [{ title: "My Page" }];
+}
+export function HydrateFallback() {
+  return (
+    <div className="flex items-center justify-center h-screen">
+      <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-foreground" />
+    </div>
+  );
+}
+export default function MyPageRoute() {
+  return <MyPage />;
+}
+```
+**Do NOT fetch data server-side** in route loaders unless the page genuinely needs SEO/OG content. The standard pattern is: SSR renders the shell, client hydrates, and React reads/writes normal app data through actions with `useActionQuery` / `useActionMutation`.
+## Adding App Data
+Normal app data starts as an action, not a custom route. Add `actions/<verb>-<resource>.ts` with `defineAction`, mark reads with `http: { method: "GET" }`, and call reads/writes from React with `useActionQuery` / `useActionMutation` from `@agent-native/core/client`. This keeps the UI and agent on one contract and lets mutating actions refresh action-backed queries automatically.
+## Adding a Route-Only Endpoint
+Use `server/routes/api/` only for protocols that cannot be modeled as JSON actions: multipart uploads, streaming/SSE/WebSocket, webhooks, OAuth callbacks/redirects, public SEO/OG endpoints, or binary/static asset serving. Do not add `/api/*` routes for normal CRUD, data queries, or pass-through wrappers around actions; the action endpoint already exists at `/_agent-native/actions/:name`.
+Each route-only endpoint still exports a default `defineEventHandler`, but keep shared app logic in actions or server libraries so agent and UI behavior do not fork.
+## Adding a Server Plugin
+Startup logic (auth, SSE, etc.) lives in `server/plugins/`. Use `defineNitroPlugin` from core:
+```ts
+import { defineNitroPlugin } from "@agent-native/core";
+export default defineNitroPlugin(async (nitroApp) => {
+  // Runs once at server startup
+});
+```
+## Key Imports from `@agent-native/core`
+| Import                                       | Purpose                                                                    |
+| -------------------------------------------- | -------------------------------------------------------------------------- |
+| `defineNitroPlugin`                          | Define a server plugin (re-exported from Nitro)                            |
+| `createDefaultSSEHandler`                    | Create SSE endpoint for DB change events (server)                          |
+| `readAppState`, `writeAppState`              | Read/write application state (from `@agent-native/core/application-state`) |
+| `readSetting`, `writeSetting`                | Read/write settings (from `@agent-native/core/settings`)                   |
+| `defineEventHandler`, `readBody`, `getQuery` | H3 route handler utilities (re-exported)                                   |
+| `sendToAgentChat`                            | Send messages to agent from UI (client-side)                               |
+| `agentChat`                                  | Send messages to agent from scripts (server-side)                          |
+## Adding an Action
+Create `actions/<verb>-<resource>.ts` with `defineAction`. Run with `pnpm action <name> --id value`; React callers should use `useActionQuery` for GET actions and `useActionMutation` for mutating actions, not a matching `/api/*` wrapper.
+**Sending to agent chat from UI:**
+```ts
+import { sendToAgentChat } from "@agent-native/core/client";
+sendToAgentChat({
+  message: "Generate something",
+  context: "...",
+  submit: true,
+});
+```
+**Sending to agent chat from scripts:**
+```ts
+import { agentChat } from "@agent-native/core";
+agentChat.submit("Generate something");
+```
+## Database & Environment Variables
+Local development defaults to a SQLite file at `data/app.db`. That local file is for development; containers, previews, and serverless deploys can reset their filesystem. For production/cloud deployment, set `DATABASE_URL` to point to a persistent SQL database. Turso is optional, not required; common choices include Neon, Supabase, Turso/libSQL, plain Postgres, durable SQLite, D1 bindings, and Builder.io-managed environments when available.
+Real credential values belong only in local `.env` files, deployment configuration, or registered secrets/settings UI. Never commit, document, log, return, paste, or include real keys, tokens, webhook URLs, signing secrets, or private data in examples; use empty values or obvious placeholders.
+When adding app data, define tables with `@agent-native/core/db/schema` helpers and use Drizzle's query builder for reads/writes. Do not import dialect-specific schema helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core`, and do not write raw SQL in normal actions or handlers when Drizzle can express the query. Raw SQL belongs in additive migrations, health checks, or carefully scoped maintenance.
+| Variable              | Required                        | Description                                                                |
+| --------------------- | ------------------------------- | -------------------------------------------------------------------------- |
+| `DATABASE_URL`        | Production yes, local dev no    | Persistent SQL connection string (local dev default: `file:./data/app.db`) |
+| `DATABASE_AUTH_TOKEN` | Only when the provider needs it | Auth token for providers such as Turso/libSQL                              |
+| `AUTH_DISABLED`       | Optional                        | Set to `true` or `1` to skip login/signup (local dev/preview only)         |
+## Extensions (Framework Feature)
+The framework provides **Extensions** — mini sandboxed Alpine.js apps that run inside iframes. Extensions let users (or the agent) create interactive widgets, dashboards, and utilities without modifying the app's source code. They appear in the sidebar under an "Extensions" section. (Distinct from LLM tools — the function-calling primitives the agent invokes.)
+- **Creating extensions**: Via the sidebar "+" button, agent chat, or `POST /_agent-native/extensions`
+- **API calls**: Extensions use `extensionFetch()` (legacy alias `toolFetch`) which proxies requests through the server with `${keys.NAME}` secret injection
+- **Styling**: Extensions inherit the main app's Tailwind v4 theme automatically
+- **Sharing**: Private by default, shareable with org or specific users (same model as other ownable resources)
+- **Security**: Iframe sandbox + CSP + SSRF protection on the proxy
+See the `extensions` skill in `.agents/skills/extensions/SKILL.md` for full implementation details.