@agent-native/core 0.14.8 → 0.15.1

package/src/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: adding-a-feature
+description: >-
+  The four-area checklist every new feature must complete. Use when adding any
+  feature, integration, or capability to ensure the agent and UI stay in parity.
+---
+
+# Adding a Feature — The Four-Area Checklist
+
+## Rule
+
+Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
+
+## Why
+
+Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.
+
+## The Checklist
+
+When you add a new feature, work through these four areas in order:
+
+### 1. UI Component
+
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations — you rarely need custom `/api/` routes.
+
+**Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
+
+- **`useActionQuery` / `useActionMutation`** — covered automatically. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches on agent activity. No extra wiring required. **Prefer this path.**
+- **Raw `useQuery` with custom keys** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `action` source is the reliable signal (the agent runner emits it after every successful tool call); the resource-specific source (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
+
+  ```tsx
+  import { useChangeVersions } from "@agent-native/core/client";
+  import { useQuery } from "@tanstack/react-query";
+
+  const v = useChangeVersions(["dashboards", "action"]);
+  useQuery({
+    queryKey: ["dashboard", id, v],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // no flicker on refetch
+  });
+  ```
+
+  See the `real-time-sync` skill for the full pattern and source catalog.
+
+### 2. Action
+
+Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the framework auto-exposes it as an HTTP endpoint at `/_agent-native/actions/:name` for the UI to call. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+### 3. Skills / Instructions
+
+Update `AGENTS.md` and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
+
+### 4. Application State Sync
+
+Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
+
+## Examples
+
+### Adding "compose email" to a mail app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Compose panel with tabs, to/cc/bcc fields, body editor. Use `useActionQuery`/`useActionMutation` for data. |
+| Action          | `manage-draft` action (create/update/delete drafts), `send-email` action                 |
+| Skills/AGENTS   | Document compose state shape, draft lifecycle, action args in AGENTS.md                  |
+| App-state sync  | `compose-{id}` keys for each draft tab, `navigation` includes compose state              |
+
+### Adding "create form" to a forms app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Form builder page with drag-and-drop fields, preview, settings. Use `useActionQuery` for lists. |
+| Action          | `create-form` action, `update-form` action, `list-forms` action (GET)                    |
+| Skills/AGENTS   | Document form schema shape, field types, validation rules in AGENTS.md                   |
+| App-state sync  | `navigation` includes `{ view: "form-builder", formId: "..." }`, `view-screen` fetches form data |
+
+### Adding "chart type" to an analytics app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | New chart component, chart type selector in dashboard                                    |
+| Action          | `create-chart` or `update-dashboard` action that sets chart type and config              |
+| Skills/AGENTS   | Document supported chart types, config options, data requirements                        |
+| App-state sync  | `navigation` includes selected chart/dashboard, `view-screen` returns chart config       |
+
+## Adding a new route
+
+Templates are single-page apps with client-side routing. The app shell (AgentSidebar + top-level nav) MUST persist across navigation — it is mounted once, either in `root.tsx` around `<Outlet />` or via a pathless `_app.tsx` layout route that all authed routes nest under.
+
+**Never wrap each new route in its own `<AppLayout>` / `<Layout>`.** That causes React to unmount the entire app shell on every navigation, reloading the agent sidebar and destroying in-progress work.
+
+- If the template has `<AppLayout>` in `root.tsx` — just render page content in your new route file, nothing else.
+- If the template has `app/routes/_app.tsx` (pathless layout) — name your new route `_app.<segment>.tsx` to inherit the shell, or bare `<segment>.tsx` for public routes that should NOT have the shell.
+- If a page needs per-route data (e.g. highlighting the active item in the sidebar), read it in the layout from `useParams()` / `useLocation()`. Don't pass it as a prop through every route file.
+
+See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
+
+## Anti-Patterns
+
+- **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
+- **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
+- **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
+- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle. Actions are auto-exposed as HTTP endpoints — use `useActionQuery`/`useActionMutation` instead.
+- **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
+- **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
+
+## Verification
+
+After completing all four areas, verify:
+
+1. Can the user perform the operation from the UI?
+2. Can the agent perform the same operation via actions?
+3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
+4. Can the agent navigate to the feature view via the `navigate` action?
+5. Is the feature documented in AGENTS.md with action names and args?
+
+## One more area — sharing
+
+If the feature stores **user-authored resources** (documents, dashboards, forms, decks, etc.), make them ownable so they get private-by-default semantics and a share dialog for free. See the `sharing` skill.
+
+TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
+
+## Related Skills
+
+- **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
+- **context-awareness** — How to expose UI state to the agent (area 4 in detail)
+- **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
+- **create-skill** — How to create skills for new patterns (area 3 in detail)
+- **storing-data** — Where to store the feature's data
+- **real-time-sync** — How the UI stays in sync when the agent writes data

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

@@ -0,0 +1,112 @@
+---
+name: address-feedback
+description: >-
+  Triage feedback docs or pasted feedback into bugs to fix, UX suggestions to
+  propose, unclear questions, and skipped noise; verify bugs, check Sentry when
+  relevant, and keep UI changes minimal.
+---
+
+# Address Feedback
+
+Use this skill when the user shares a feedback document, issue, thread, or pasted notes and asks you to address the feedback.
+
+The default posture is judgment plus action: fix clear, verified bugs you agree with; propose UX changes with rationale; skip or flag low-signal, unclear, or out-of-scope items.
+
+## Prerequisites
+
+- If no link or feedback text is provided, ask for it.
+- Read the repo `AGENTS.md` before touching code.
+- Use the relevant connector/plugin/skill for the source when available, instead of scraping authenticated pages.
+
+## Steps
+
+1. Read the feedback source.
+
+   | Source | Reader |
+   | --- | --- |
+   | Notion link | Notion connector or Notion skill |
+   | Google Docs/Drive link | Google Drive connector or Google Docs skill |
+   | Linear link | Linear connector if installed; otherwise ask for pasted content |
+   | GitHub issue or PR | GitHub connector or `gh issue view` / `gh pr view` |
+   | Slack thread | Slack connector |
+   | Public URL | Web browsing |
+   | Pasted text | Read directly |
+
+   Use web browsing only for public URLs. Auth-gated docs usually need their matching connector.
+
+2. Categorize every actionable item.
+
+   - **Bug**: Broken behavior, crash, wrong data, dead link, package/API mismatch, or captured exception. Verify and fix when you agree.
+   - **UX suggestion**: Design, discoverability, workflow, or feature feedback. Propose the cleanest version first unless the user explicitly asked you to implement UX changes.
+   - **Question or unclear**: Missing detail, contradictory feedback, or behavior you cannot inspect. Ask or flag it.
+   - **Out of scope**: Outside this repo, already shipped, intentionally unsupported, or too low-signal. Note briefly and skip.
+
+3. Check Sentry when the feedback smells like an error.
+
+   - Use the Sentry skill/plugin if available, or the repo's Sentry scripts if documented.
+   - Search by route, stack symbol, error text, and symptom keywords.
+   - Default org is `builder-io` unless the user specifies another.
+   - Cite issue IDs or links when you find a match.
+   - If nothing matches, say that plainly.
+
+4. Fix only the clear bugs you agree with.
+
+   - Verify before fixing: reproduce locally, read the relevant code, inspect logs, or confirm with a stack trace.
+   - Keep each fix narrow and mapped to a feedback item.
+   - Follow existing project conventions and nearby patterns.
+   - Do not switch branches, stash, reset, force-push, or open a PR unless the user asks.
+   - Add or update focused tests when the bug risk warrants it.
+
+5. Treat UX feedback with restraint.
+
+   Do not solve UX problems by adding more visible controls, helper text, banners, top-level nav, or always-open panels by default. Prefer cleaner interaction models:
+
+   - Make the existing primary action more discoverable.
+   - Remove competing elements so the right action stands out.
+   - Move secondary actions into `DropdownMenu`, `Popover`, `Sheet`, `Collapsible`, or tabs.
+   - Improve empty states around one clear action.
+   - Use progressive disclosure for optional or advanced controls.
+
+   When proposing a UX change, write it as: what to change, why it helps, and the tradeoff. Keep each proposal short.
+
+6. Verify changed behavior.
+
+   - Run the smallest relevant test or typecheck command.
+   - For UI fixes, verify in a browser when feasible and inspect the actual screen.
+   - If you cannot run a useful verification, say why.
+
+## Report Format
+
+Keep the final report short:
+
+```md
+## Bugs Fixed
+- [feedback item] - [what changed, file:line]
+
+## Bugs Flagged But Not Fixed
+- [feedback item] - [why]
+
+## UX Suggestions
+- [feedback item] -> [proposed change]
+
+## Skipped
+- [feedback item] - [reason]
+```
+
+Only include sections that have content. The user can read the diff; do not write a second feedback document.
+
+## Avoid
+
+- Do not agree with every suggestion by default.
+- Do not bundle unrelated cleanups.
+- Do not implement UX changes that make an important screen busier without explicit user approval.
+- Do not claim a UI change is done without browser verification when a local app can be run.
+- Do not invent Sentry matches, affected users, or reproduction steps.
+
+## Related Skills
+
+- `github:gh-address-comments` for GitHub PR review threads.
+- `github:gh-fix-ci` for failing GitHub checks.
+- `sentry:sentry` for production error investigation.
+- `frontend-design` for approved UI implementation work.
+- `qa` for broader browser verification.

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

@@ -0,0 +1,88 @@
+---
+name: authentication
+description: >-
+  How auth works in agent-native apps. Use when wiring login/signup,
+  configuring auth modes, setting up organizations, protecting routes, or
+  debugging session issues.
+---
+
+# Authentication
+
+## Rule
+
+Auth is powered by **Better Auth** with account-first design. Every new user creates an account on first visit. Use `getSession(event)` to authenticate custom routes; actions are auto-protected.
+
+## Auth Modes
+
+| Mode                      | Behavior                                                                                                                                 |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| **Development (default)** | Auth is automatically bypassed. `getSession()` falls back to `{ email: "local@localhost" }` when nothing else succeeds. No config.      |
+| **Production (default)**  | Better Auth with email/password + social providers (Google, GitHub). Organizations built in.                                             |
+| **`AUTH_MODE=local`**     | Explicit escape hatch. `getSession()` always returns `{ email: "local@localhost" }`. Set via `.env` or the onboarding page's "Use locally" button. |
+| **`AUTH_SKIP_EMAIL_VERIFICATION=1`** | QA/preview escape hatch for real email/password accounts. Signup skips email verification and does not send the signup verification email. Local dev/test skips verification by default; set `AUTH_SKIP_EMAIL_VERIFICATION=0` only when testing verification itself. Use `+qa` emails for test accounts. |
+| **`ACCESS_TOKEN` / `ACCESS_TOKENS`** | Simple token-based auth for production deployments.                                                                           |
+| **`AUTH_DISABLED=true`**  | Skip auth entirely (for apps behind infrastructure-level auth like Cloudflare Access).                                                   |
+| **Custom**                | Pass your own `getSession` to `autoMountAuth(app, { getSession })`.                                                                     |
+
+## Local → Real Account Migration
+
+Upgrading from `local@localhost` to a real account preserves SQL-backed workspace data. The built-in migration moves `application_state`, user-scoped `settings`, `oauth_tokens`, and any template table that uses `owner_email`.
+
+Templates with legacy global settings can provide `POST /api/local-migration` for one-time re-homing during the upgrade flow.
+
+## Organizations
+
+Better Auth's organization plugin is built in. Every app supports creating orgs, inviting members, and role-based access (owner/admin/member).
+
+The active org flows automatically: `session.orgId` → `AGENT_ORG_ID` → SQL scoping (see `security` skill).
+
+**If your template requires an org to function** (data is scoped by `organization_id`, core features can't run without one), set `AUTO_CREATE_DEFAULT_ORG=1` in your `.env`. The framework will auto-create a default org (named after the user) on first login when no memberships exist. This happens inside `getOrgContext` — no template integration needed.
+
+As a safety net, also wrap your app shell in `<RequireActiveOrg>` from `@agent-native/core/client/org`. It blocks the wrapped area with a "Create your organization" pane (and accept-invite CTAs for pending invitations) if auto-create failed or the account predates it. Place it **inside** the agent sidebar so the setup checklist, chat, and CLI stay usable during setup.
+
+## A2A Identity
+
+Set `A2A_SECRET` (same value) on all apps that must verify each other's identity.
+
+- Outbound A2A calls are signed with JWTs
+- Inbound calls are verified cryptographically
+- Without `A2A_SECRET`, A2A calls are unauthenticated (fine for local dev)
+
+## Builder Browser Access
+
+Apps can connect to Builder via the `cli-auth` flow and persist shared browser credentials in `.env`. Agents then use the built-in `get-browser-connection` tool to provision a real browser session via AI Services.
+
+## Protecting Custom Routes
+
+Actions are auto-protected. For custom `/api/` routes:
+
+```ts
+import { getSession } from "@agent-native/core/server";
+
+export default defineEventHandler(async (event) => {
+  const session = await getSession(event);
+  if (!session) throw createError({ statusCode: 401 });
+  // ...
+});
+```
+
+Never create unprotected routes that modify data.
+
+## Sign-In from a Public Page
+
+For public pages (share links, embeds, marketing pages) that need anonymous viewers to sign in and return to where they were, navigate them through the framework's sign-in entry point — never roll your own:
+
+```ts
+const ret = window.location.pathname + window.location.search;
+window.location.href =
+  "/_agent-native/sign-in?return=" + encodeURIComponent(ret);
+```
+
+After successful sign-in (token / email-password / Google OAuth), the framework 302s to `return`. The path is validated as same-origin via the URL parser — open-redirect / header-injection inputs fall back to `/`.
+
+Bookmarked private paths already work without any plumbing — the framework's login page is served at the requested URL, and post-login reload returns the user there.
+
+## Related Skills
+
+- `security` — Data scoping, SQL injection, secrets
+- `actions` — Auto-protected by the auth guard

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

@@ -0,0 +1,191 @@
+---
+name: automations
+description: >-
+  Event-triggered and schedule-triggered automations with natural-language
+  conditions. Use when creating automations, wiring events, or understanding
+  how triggers fire.
+---
+
+# Automations
+
+## Rule
+
+Automations are agent-executed tasks that fire in response to events or on a cron schedule. Each automation is a markdown resource under `jobs/` with YAML frontmatter describing when and how it fires, and a body containing natural-language instructions the agent follows. Automations extend the recurring-jobs system with event triggers, natural-language condition evaluation, and outbound HTTP via the `web-request` tool.
+
+## The Two Trigger Types
+
+| Type       | Fires when                                      | Key field           |
+| ---------- | ----------------------------------------------- | ------------------- |
+| `schedule` | Cron expression matches (same as recurring jobs) | `schedule` (cron)   |
+| `event`    | A matching event is emitted on the event bus     | `event` (event name) |
+
+Event triggers can optionally include a `condition` -- a natural-language string evaluated by Haiku against the event payload before dispatch. If the condition does not match, the automation is skipped.
+
+## How It Works
+
+1. User asks the agent to create an automation (or uses the settings UI).
+2. Agent calls `manage-automations` with `action=list-events` to discover available events.
+3. Agent calls `manage-automations` with `action=define` to write a `jobs/<name>.md` resource.
+4. The trigger dispatcher subscribes to the event on the bus.
+5. When the event fires, the dispatcher loads all matching triggers, evaluates conditions via Haiku, and dispatches matching ones.
+6. In `agentic` mode, the dispatcher runs a full `runAgentLoop` with the automation body as the prompt and the event payload as context.
+7. Status (`lastRun`, `lastStatus`, `lastError`) is written back to the resource frontmatter.
+
+## Markdown Format
+
+```yaml
+---
+schedule: "0 9 * * 1-5"
+enabled: true
+triggerType: event
+event: calendar.booking.created
+condition: "attendee email ends with @example.com"
+mode: agentic
+domain: calendar
+createdBy: owner@example.com
+runAs: creator
+---
+
+Send a Slack message to #sales with the booking details.
+Use the web-request tool with ${keys.SLACK_WEBHOOK}.
+```
+
+### Frontmatter Fields
+
+| Field         | Type                           | Purpose                                                |
+| ------------- | ------------------------------ | ------------------------------------------------------ |
+| `schedule`    | `string`                       | Cron expression (required for schedule triggers)       |
+| `enabled`     | `boolean`                      | Whether the automation is active                       |
+| `triggerType` | `"schedule" \| "event"`        | How the automation fires                               |
+| `event`       | `string?`                      | Event name to subscribe to (event triggers)            |
+| `condition`   | `string?`                      | Natural-language condition evaluated before dispatch   |
+| `mode`        | `"agentic" \| "deterministic"` | Full agent loop vs. fixed action set                   |
+| `model`       | `string?`                      | Override the model for this trigger's agent loop       |
+| `domain`      | `string?`                      | Grouping tag (mail, calendar, clips, etc.)             |
+| `createdBy`   | `string?`                      | Owner email                                            |
+| `orgId`       | `string?`                      | Org scope                                              |
+| `runAs`       | `"creator" \| "shared"`        | Whose API key and permissions to use                   |
+| `lastRun`     | `string?`                      | ISO timestamp of last execution                        |
+| `lastStatus`  | `string?`                      | `success`, `error`, `running`, or `skipped`            |
+| `lastError`   | `string?`                      | Error message from last failed run                     |
+
+## Agent Tools
+
+All automation operations are accessed through a single `manage-automations` tool with an `action` parameter:
+
+| Action        | Purpose                                                              |
+| ------------- | -------------------------------------------------------------------- |
+| `list-events` | Discover all registered events with descriptions and payload schemas |
+| `list`        | List all automations with status, filter by domain or enabled        |
+| `define`      | Create a new automation (name, trigger type, event, condition, body)  |
+| `update`      | Update an existing automation (enabled, condition, body)             |
+| `delete`      | Delete an automation (always confirm with user first)                |
+| `fire-test`   | Emit a `test.event.fired` event to validate automations              |
+
+Additional tool: `web-request` — outbound HTTP with `${keys.NAME}` substitution.
+
+## The Event Bus
+
+Integrations register events at module load time. The bus validates payloads against Standard Schema definitions and dispatches to subscribers.
+
+```ts
+import { registerEvent, emit } from "@agent-native/core/event-bus";
+import { z } from "zod";
+
+// Register an event type (typically in a server plugin)
+registerEvent({
+  name: "calendar.booking.created",
+  description: "A new calendar booking was created",
+  payloadSchema: z.object({
+    bookingId: z.string(),
+    attendeeEmail: z.string(),
+    startTime: z.string(),
+  }),
+  example: { bookingId: "abc", attendeeEmail: "jane@co.com", startTime: "2025-01-15T10:00:00Z" },
+});
+
+// Emit the event (from an action, webhook handler, etc.)
+emit("calendar.booking.created", {
+  bookingId: "abc",
+  attendeeEmail: "jane@co.com",
+  startTime: "2025-01-15T10:00:00Z",
+}, { owner: "owner@example.com" });
+```
+
+### Built-in Events
+
+| Event                     | Source              |
+| ------------------------- | ------------------- |
+| `test.event.fired`        | Manual / manage-automations action=fire-test |
+| `agent.turn.completed`    | Agent chat          |
+| `calendar.*`              | Calendar integration |
+| `clip.*`                  | Clips integration   |
+| `mail.*`                  | Mail integration    |
+
+### Event Bus API
+
+| Function         | Purpose                                     |
+| ---------------- | ------------------------------------------- |
+| `registerEvent`  | Declare an event type with schema           |
+| `emit`           | Fire an event (validates payload)           |
+| `subscribe`      | Listen for an event (returns subscription ID) |
+| `unsubscribe`    | Remove a subscription by ID                 |
+| `listEvents`     | List all registered event definitions       |
+
+## Condition Evaluator
+
+When an automation has a `condition`, the dispatcher calls Haiku (claude-haiku-4-5) to classify whether the event payload satisfies the condition. This is a yes/no classification, not a generation task.
+
+- Empty or missing condition = unconditional (always fires).
+- Results are memoized (SHA-256 of condition + payload) with a 5-minute TTL and 500-entry LRU cache.
+- Payload is truncated to 4000 characters before sending to Haiku.
+- On API failure, the condition evaluates to `false` (safe default -- skips the automation).
+
+## The `web-request` Tool and Keys
+
+Automations use the `web-request` tool for outbound HTTP. It supports `${keys.NAME}` placeholders in the URL, headers, and body. These are resolved server-side after the agent emits the tool call -- the raw secret value never enters the agent's context.
+
+- Keys are ad-hoc secrets created by the user via the settings UI or the `/_agent-native/secrets/adhoc` API.
+- Each key can have a URL allowlist that restricts which origins the key can be sent to.
+- `resolveKeyReferences()` resolves placeholders, falling back from user scope to workspace scope.
+- `validateUrlAllowlist()` checks the resolved URL against per-key allowlists (origin-level matching).
+
+## UI
+
+Automations appear in the settings panel under an "Automations" section. Users can view, enable/disable, and delete automations from there. Creation typically happens through the agent chat.
+
+## Example
+
+User: "When someone books a meeting with a @example.com email, message me in Slack."
+
+Agent flow:
+
+1. Calls `manage-automations` with `action=list-events` to find `calendar.booking.created`.
+2. Confirms the plan with the user.
+3. Calls `manage-automations` with `action=define`:
+   - `name`: `slack-on-builder-booking`
+   - `trigger_type`: `event`
+   - `event`: `calendar.booking.created`
+   - `condition`: `attendee email ends with @example.com`
+   - `mode`: `agentic`
+   - `domain`: `calendar`
+   - `body`: `Send a Slack message to #sales with the booking details. Use the web-request tool to POST to ${keys.SLACK_WEBHOOK}.`
+
+## Key Files
+
+| File                                           | Purpose                                          |
+| ---------------------------------------------- | ------------------------------------------------ |
+| `packages/core/src/triggers/types.ts`          | `TriggerFrontmatter` interface                   |
+| `packages/core/src/triggers/actions.ts`        | Agent tools (define, list, update, delete, test)  |
+| `packages/core/src/triggers/dispatcher.ts`     | Event subscription and agentic dispatch          |
+| `packages/core/src/triggers/condition-evaluator.ts` | Haiku condition classification with caching |
+| `packages/core/src/event-bus/`                 | Event bus (register, emit, subscribe)            |
+| `packages/core/src/tools/fetch-tool.ts`        | `web-request` tool with key substitution         |
+| `packages/core/src/secrets/substitution.ts`    | `resolveKeyReferences()` and `validateUrlAllowlist()` |
+
+## Related Skills
+
+- `recurring-jobs` -- schedule-triggered automations reuse the same scheduler
+- `secrets` -- ad-hoc keys and `${keys.NAME}` substitution
+- `actions` -- automations can call any registered action via the agent loop
+- `delegate-to-agent` -- agentic mode runs a full `runAgentLoop`

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

@@ -0,0 +1,74 @@
+---
+name: capture-learnings
+description: >-
+  Capture and apply accumulated knowledge via structured memory. Use when the
+  user gives feedback, shares preferences, corrects a mistake, or when you
+  discover something worth remembering for future conversations.
+user-invocable: false
+---
+
+# Capture Learnings
+
+This is background knowledge, not a slash command. **Your memory index is loaded at the start of every conversation.** Use `save-memory` proactively when you learn something worth remembering.
+
+## How to Read & Write Memories
+
+Memories are stored as **resources** in the SQL database (personal scope), not as files on disk.
+
+- **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
+- **Read a memory:** `resource-read --path memory/<name>.md`
+- **Delete a memory:** `delete-memory --name <name>`
+- **List all memories:** `resource-list --prefix memory/`
+
+## Memory Types
+
+| Type | Use for |
+|------|---------|
+| `user` | Preferences, role, personal context, contacts |
+| `feedback` | Corrections, confirmed approaches, things to avoid or repeat |
+| `project` | Ongoing work context, decisions, deadlines, status |
+| `reference` | Pointers to external systems, URLs, API details |
+
+## When to Capture
+
+### User Preferences & Memory (`user`)
+- **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
+- **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
+- **Workflow preferences** — "always CC my assistant", "I like to review before sending"
+- **Role and expertise** — "I'm a data scientist", "new to React"
+
+### Feedback & Corrections (`feedback`)
+- **Corrections** — user says "no, do it this way" → capture the right way
+- **Confirmed approaches** — user validates a non-obvious choice ("yes, that's perfect")
+- **Repeated friction** — you hit the same issue twice; save it
+
+### Project Context (`project`)
+- **Ongoing work** — who is doing what, why, by when
+- **Decisions** — why something is done a certain way
+- **Status** — current state of initiatives
+
+### References (`reference`)
+- **External systems** — "bugs are tracked in Linear project INGEST"
+- **URLs** — dashboards, documentation, tools
+- **API quirks** — undocumented behavior, version-specific gotchas
+
+### Don't Capture
+- Things obvious from reading the code
+- Standard language/framework behavior
+- Temporary debugging notes
+- Anything already in AGENTS.md or skills
+- Ephemeral task details (use tasks/plans instead)
+
+## Key Rules
+
+1. **Save proactively — don't ask permission.** When you learn something, save it immediately.
+2. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
+3. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
+4. **Keep descriptions concise** — the index is loaded every conversation
+5. **Memories are SQL-backed** — safe for personal info, persist across sessions, not in git
+
+## Graduation
+
+When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
+- Saving a memory is lightweight (auto-apply, personal scope)
+- Updating AGENTS.md or a skill is heavier (affects all users/agents)