@agent-native/core 0.14.8 → 0.15.0

package/dist/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/dist/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/dist/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/dist/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)

package/dist/templates/workspace-core/.agents/skills/client-side-routing/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: client-side-routing
+description: >-
+  How to add routes without remounting the app shell. Use when adding a new
+  route, fixing agent sidebar reloads on navigation, or choosing between
+  `root.tsx` layout and pathless `_app.tsx` layout patterns.
+---
+
+# Client-Side Routing
+
+## Rule
+
+All templates are single-page apps using React Router. **Navigation must not remount the app shell.** The agent sidebar, document tree, and any other persistent chrome must survive route changes.
+
+## Why
+
+If the shell unmounts on every navigation, the agent chat reconnects/reloads, destroying in-progress work and hammering the backend.
+
+## Hard Rule
+
+**The app shell (AgentSidebar + any top-level navigation) must be mounted ONCE, above the `<Outlet />`.** Never wrap each page in its own `<AppLayout>` / `<Layout>`. React sees a different component at the outlet position on each nav and unmounts the entire subtree.
+
+## Two Correct Patterns
+
+### 1. All routes need the shell
+
+Mount `<AppLayout>` in `root.tsx` around `<Outlet />`:
+
+```tsx
+// app/root.tsx
+<AppLayout>
+  <Outlet />
+</AppLayout>
+```
+
+### 2. Mix of protected and public routes
+
+Use a React Router **pathless layout route**:
+
+```
+app/routes/
+  _app.tsx                  # renders <AppLayout><Outlet /></AppLayout>
+  _app._index.tsx           # / → under AppLayout
+  _app.settings.tsx         # /settings → under AppLayout
+  _app.team.tsx             # /team → under AppLayout
+  book.$slug.tsx            # /book/:slug → no layout (public)
+  f.$.tsx                   # /f/* → no layout (public form filler)
+```
+
+The `_` prefix on `_app.tsx` makes it a **pathless** parent — it contributes the layout but no URL segment. Route files prefixed with `_app.` nest under it and share the layout instance across navigations.
+
+## Anti-Pattern
+
+```tsx
+// ❌ BAD — each route wraps its own Layout, causing full remount on every nav
+export default function Settings() {
+  return (
+    <AppLayout>
+      <SettingsContent />
+    </AppLayout>
+  );
+}
+```
+
+If a page needs per-route data (e.g. sidebar highlighting the active document), derive it inside the layout from `useParams()` / `useLocation()` — don't pass it as a prop through every route file.
+
+## Adding a New Route
+
+- **Pattern #1** (AppLayout in `root.tsx`): just render page content — nothing else.
+- **Pattern #2** (pathless `_app.tsx`): name the file `_app.<segment>.tsx` for authed routes, or bare `<segment>.tsx` for public routes.
+
+## Related Skills
+
+- `adding-a-feature` — The four-area checklist referencing route layout patterns
+- `context-awareness` — Navigation state written on every route change