@agent-native/core 0.14.8 → 0.15.0

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

@@ -0,0 +1,92 @@
+---
+name: frontend-design
+description: >-
+  Create distinctive, production-grade frontend interfaces with high design
+  quality. Use when building web components, pages, artifacts, posters, or
+  applications (websites, landing pages, dashboards, React components,
+  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
+  creative, polished UI that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+---
+
+# Frontend Design
+
+This skill guides creation of distinctive, production-grade frontend interfaces. Implement real working code with strong product judgment, excellent accessibility, and a clear visual point of view.
+
+The user may ask for a component, page, full app, dashboard, marketing surface, or restyle. Before coding, understand the audience and pick a direction that fits the product instead of defaulting to generic SaaS polish.
+
+## Design Thinking
+
+Before coding, decide:
+
+- **Purpose**: What workflow does this surface make easier? What is the primary action?
+- **Audience**: Who will use it repeatedly, and what should feel fast, calm, playful, premium, editorial, technical, or utilitarian?
+- **Tone**: Choose a concrete aesthetic direction: refined minimal, dense operations console, editorial, playful, industrial, warm handmade, high-contrast data tool, etc.
+- **Information hierarchy**: What must be visible in the first five seconds, and what should be progressively disclosed?
+- **Differentiation**: What makes this feel designed for this exact domain?
+
+Then implement working code that is cohesive, accessible, responsive, and polished in small details: typography, spacing, copy, motion, empty states, loading states, focus states, and error states.
+
+## Aesthetic Guidelines
+
+- **Typography**: Use the product's existing type system first. For net-new public pages, choose characterful but readable type and keep sizing appropriate to the surface.
+- **Color and theme**: Use semantic tokens and CSS variables. Avoid one-note palettes and default purple/blue gradients unless the brand demands them.
+- **Motion**: Prefer purposeful transitions and small state changes. Use CSS transitions/keyframes unless the app already uses a motion library.
+- **Composition**: Match the workflow. Operational apps should be dense and scannable; marketing or portfolio pages can be more immersive.
+- **Visual assets**: Websites, games, and object-focused pages need real or generated media when images help users understand the subject.
+- **Responsive fit**: Text must not overflow buttons, cards, tabs, sidebars, or fixed-format tools. Use stable dimensions for boards, grids, toolbars, and counters.
+
+## Agent-Native UI Rules
+
+- Agent-native apps use React, Vite, Tailwind CSS, shadcn/ui, and `@tabler/icons-react`.
+- **Use shadcn/ui primitives for standard UI**: `DropdownMenu`, `Popover`, `Dialog`, `AlertDialog`, `Sheet`, `Tabs`, `Tooltip`, `Select`, `Command`, `Sidebar`, `Table`, `Card`, `Badge`, `Skeleton`, and related primitives.
+- **When touching shadcn/ui components, also read `shadcn-ui` if it exists.** That skill covers `components.json`, CLI docs, component composition, theming, and registry workflows.
+- Check `app/components/ui/` before importing a shadcn component. If a primitive is missing, add it from the app root with `pnpm dlx shadcn@latest add <component>`, then review the generated file.
+- Do not build custom dropdowns, menus, popovers, modals, or confirmations with manual absolute positioning and click-outside effects.
+- Never use browser dialogs (`window.alert`, `window.confirm`, `window.prompt`). Use `AlertDialog`, `Dialog`, or app-specific confirmation UI.
+- Use Tabler icons for all first-party UI icons. Do not add Lucide, Heroicons, inline SVG icon sets, or emoji icons.
+- Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` for action-backed UI. Standard CRUD should go through actions, not custom `/api/` routes.
+- Keep UI optimistic where possible: update cache and navigation immediately, then reconcile or roll back on mutation result.
+- Custom styles belong in Tailwind classes, component CSS, or the existing global CSS theme file; avoid inline styles.
+
+## shadcn/ui Design Rules
+
+- Use built-in component variants first (`variant`, `size`) before overriding classes.
+- Use semantic tokens (`bg-background`, `text-muted-foreground`, `border-border`, `bg-primary`) instead of raw Tailwind colors for app chrome and reusable components.
+- Use `gap-*` in flex/grid layouts instead of `space-x-*` or `space-y-*`.
+- Use `size-*` when width and height are equal, and `truncate` instead of spelling out overflow/ellipsis/nowrap.
+- Use `cn()` from the local utils alias for conditional classes.
+- Dialog, Sheet, Drawer, and AlertDialog content must have an accessible title. Use `sr-only` only when the visible design already communicates the title.
+- Put menu/list items inside their group primitives: `SelectGroup`, `DropdownMenuGroup`, `CommandGroup`, and equivalents.
+- Use full `Card` composition when the content has a title, description, content, or actions. Do not dump complex cards into a single `CardContent`.
+- Use `ToggleGroup` for small option sets, `Switch` for binary settings, `Checkbox` for multi-select, `RadioGroup` for one-of-many, and `Slider`/inputs for numeric values.
+- For forms, prefer the app's existing shadcn form pattern. If newer `Field`, `FieldGroup`, or `InputGroup` primitives are installed or appropriate to add, use them instead of raw layout divs.
+- Loading states use `Skeleton`, `Progress`, `Spinner`, or the app's existing loading primitives. Empty states should have one clear next action.
+
+## Anti-Patterns
+
+Avoid:
+
+- Generic AI aesthetics: purple gradients, glassy cards everywhere, vague sparkle language, decorative blobs, and context-free hero sections.
+- Custom reimplementations of shadcn primitives.
+- Raw color overrides on shared components when semantic tokens or variants would work.
+- New always-visible controls for rare actions. Prefer menus, popovers, sheets, tabs, collapsibles, or advanced sections.
+- UI cards nested inside other cards.
+- Text or icons that resize or shift fixed-format UI on hover/loading.
+
+## Verification
+
+For substantial frontend work:
+
+1. Run the relevant formatter/checks.
+2. Start the dev server when the app needs one.
+3. Verify with browser screenshots at desktop and mobile widths.
+4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
+
+## Related Skills
+
+- **shadcn-ui** — shadcn CLI, component docs, composition rules, theming, and registries
+- **self-modifying-code** — The agent can edit source code to apply design changes
+- **storing-data** — All data lives in SQL; use actions for data access
+- **actions** — `useActionQuery`/`useActionMutation` hooks for frontend data fetching

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

@@ -0,0 +1,285 @@
+---
+name: integration-webhooks
+description: >-
+  Cross-platform pattern for handling messaging integration webhooks (Slack,
+  Telegram, WhatsApp, email, etc.) on serverless hosts. Use when adding a new
+  integration adapter, debugging dropped messages, or wiring long-running agent
+  work into a webhook handler.
+---
+
+# Integration Webhooks
+
+## Rule
+
+Integration webhooks (Slack, Telegram, WhatsApp, email, Google Docs, etc.) must
+**enqueue work to SQL and return 200 immediately**, then process the work in a
+**separate fresh function execution** kicked off by a self-fired HTTP POST. A
+recurring retry job sweeps anything that gets stuck. This pattern works on every
+serverless host (Netlify, Vercel, Cloudflare Workers, Fly, Render, Node) without
+relying on platform-specific background-execution features.
+
+Do not run agent loops inside the webhook handler itself. Do not rely on
+fire-and-forget `Promise`s after `return`ing from a serverless handler — they get
+killed when the function freezes.
+
+## Why
+
+Messaging platforms expect a 200 response within a tight window — Slack will
+retry after 3 seconds, and a retried event triggers duplicate agent runs. At the
+same time, an agent loop replying to the message can take 30–60+ seconds because
+it may make multiple LLM calls and tool calls.
+
+Past attempts that don't work cross-host:
+
+- **Fire-and-forget `Promise.then(...)` after returning** — Lambda/Vercel/CF
+  freeze the execution context the moment the response goes out. The promise
+  is silently killed, the user gets no reply, and there's no error in the
+  logs.
+- **Netlify Background Functions** — Netlify-only, requires a `-background`
+  filename suffix, breaks on every other host.
+- **Cloudflare `event.waitUntil()`** — CF Workers only, not portable.
+- **Vercel Fluid / `after()`** — Vercel-only, gated behind specific runtimes.
+- **A long-lived in-process queue** — fine on a single Node box, but on
+  serverless every cold start gets a fresh queue and any pending work is
+  lost.
+
+The only universal answer: **persist the work, then trigger a brand new
+function execution to do it.** SQL is the queue, a self-webhook is the trigger,
+and a recurring job is the safety net.
+
+## The Flow
+
+```
+┌──────────┐    1. POST /integrations/:platform/webhook
+│ Platform │────────────────────────────────────────────►┌──────────────────┐
+└──────────┘                                             │ Webhook handler  │
+                                                         │ (function exec 1)│
+                                                         └──────────────────┘
+                                                                  │
+                            2. INSERT INTO integration_pending_tasks
+                                 (status='pending', payload=...)
+                                                                  │
+                            3. fetch(POST /integrations/_process-task)
+                                 — fire-and-forget, NO await on body
+                                                                  │
+                            4. return 200 to platform ◄───────────┘
+
+                                                         ┌──────────────────┐
+                          5. POST arrives at processor   │ Processor        │
+                             (separate fresh function)   │ (function exec 2)│
+                                                         └──────────────────┘
+                                                                  │
+                            6. claimPendingTask(id) → status='processing'
+                            7. runAgentLoop(...) — full timeout budget here
+                            8. adapter.sendResponse(...) back to platform
+                            9. markTaskCompleted(id)
+
+
+                          ┌──────────────────────────────────────────────┐
+                          │  Recurring job (every 60s) — safety net      │
+                          │  Re-fires processor for tasks stuck in       │
+                          │  'pending' or 'processing' beyond timeout.   │
+                          │  Caps retries at 3 then marks 'failed'.      │
+                          └──────────────────────────────────────────────┘
+```
+
+The webhook handler does as little as possible. The fresh function execution
+that handles `_process-task` gets its own full timeout budget for the agent
+loop.
+
+## Key Files
+
+| File                                                                    | Purpose                                                                |
+| ----------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `packages/core/src/integrations/plugin.ts`                              | Mounts `/_agent-native/integrations/*` routes                          |
+| `packages/core/src/integrations/webhook-handler.ts`                     | Verifies signature, parses, enqueues task, fires processor             |
+| `packages/core/src/integrations/pending-tasks-store.ts`                 | SQL queue: `insertPendingTask`, `claimPendingTask`, `markTaskCompleted`, `markTaskFailed` |
+| `packages/core/src/integrations/pending-tasks-retry-job.ts`             | Recurring retry sweep (`startPendingTasksRetryJob`, `retryStuckPendingTasks`) |
+| `packages/core/src/integrations/types.ts`                               | `PlatformAdapter`, `IncomingMessage`, `OutgoingMessage`                |
+| `packages/core/src/integrations/adapters/{slack,telegram,whatsapp,email,google-docs}.ts` | One adapter per platform                                               |
+
+## Routes
+
+All under `/_agent-native/integrations/`:
+
+| Method | Path                       | Purpose                                                       |
+| ------ | -------------------------- | ------------------------------------------------------------- |
+| POST   | `/:platform/webhook`       | Platform pings this. Verifies, enqueues, returns 200 quickly. |
+| POST   | `/_process-task`           | Self-webhook target. Claims a task and runs the agent loop.   |
+| GET    | `/status`                  | All integrations status (settings UI).                        |
+| GET    | `/:platform/status`        | One platform's status.                                        |
+| POST   | `/:platform/enable`        | Enable an integration.                                        |
+| POST   | `/:platform/disable`       | Disable an integration.                                       |
+| POST   | `/:platform/setup`         | Platform-specific setup (e.g. Telegram webhook registration). |
+
+## SQL Schema
+
+The pending-task queue lives in `integration_pending_tasks`:
+
+```sql
+CREATE TABLE IF NOT EXISTS integration_pending_tasks (
+  id                 TEXT    PRIMARY KEY,
+  platform           TEXT    NOT NULL,
+  external_thread_id TEXT    NOT NULL,
+  payload            TEXT    NOT NULL,   -- JSON-serialized IncomingMessage
+  owner_email        TEXT    NOT NULL,
+  org_id             TEXT,
+  status             TEXT    NOT NULL,   -- pending | processing | completed | failed
+  attempts           INTEGER NOT NULL DEFAULT 0,
+  error_message      TEXT,
+  created_at         INTEGER NOT NULL,
+  updated_at         INTEGER NOT NULL,
+  completed_at       INTEGER
+);
+CREATE INDEX IF NOT EXISTS idx_pending_tasks_status_created
+  ON integration_pending_tasks(status, created_at);
+```
+
+The store layer creates this lazily on first use via `ensureTable()` and uses
+`intType()` from `db/client.ts` so it works on both SQLite and Postgres.
+
+`claimPendingTask` is the critical concurrency primitive: it atomically flips
+`pending` → `processing` and increments `attempts`, returning `null` if another
+worker beat us to it. Both the initial fire-and-forget call and the retry job
+funnel through the same processor endpoint, and `claimPendingTask` is what
+prevents the same task from being processed twice.
+
+## Adding a New Platform Adapter
+
+1. **Implement `PlatformAdapter`** in `packages/core/src/integrations/adapters/<platform>.ts`:
+
+   ```ts
+   export function myPlatformAdapter(): PlatformAdapter {
+     return {
+       platform: "myplatform",
+       label: "MyPlatform",
+       getRequiredEnvKeys: () => [
+         { name: "MYPLATFORM_TOKEN", label: "MyPlatform Bot Token", scope: "global" },
+       ],
+       async handleVerification(event) {
+         // Platform-specific challenge response, if any
+         return { handled: false };
+       },
+       async verifyWebhook(event) {
+         // HMAC / signing-secret check — return false on mismatch
+         return true;
+       },
+       async parseIncomingMessage(event) {
+         // Map raw payload → IncomingMessage, or null to ignore
+         return null;
+       },
+       async sendResponse(message, context) {
+         // POST back to the platform's API
+       },
+       formatAgentResponse(text) {
+         return { text, platformContext: {} };
+       },
+       async getStatus(baseUrl) {
+         return { platform: "myplatform", label: "MyPlatform", enabled: false, configured: false };
+       },
+     };
+   }
+   ```
+
+2. **Register it** in `getDefaultAdapters()` inside `plugin.ts`. The webhook,
+   queue, processor, and retry job are shared infrastructure — you do not
+   write any of that per-adapter.
+
+3. **Declare required env keys** so the secrets/onboarding UI surfaces them.
+   See `secrets` and `onboarding` skills.
+
+4. **Update the platform's webhook URL** to point at
+   `${baseUrl}/_agent-native/integrations/<platform>/webhook`. For platforms
+   with a registration API (Telegram), implement `POST /:platform/setup`.
+
+The adapter is **only** responsible for:
+
+- platform-specific verification (signatures, challenges)
+- payload → `IncomingMessage` mapping
+- agent text → platform format
+- delivering the response back to the platform
+
+It does **not** know about the queue, the processor, retries, or the agent
+loop. Those are handled by the shared webhook handler.
+
+## Long-Running Agent Work
+
+The processor endpoint runs in a fresh function execution with its own full
+timeout (typically 30–60s on Netlify/Vercel, longer on background-friendly
+hosts). That budget is dedicated entirely to the agent loop — there is no
+platform-side timer racing it.
+
+If a single agent run might exceed the function timeout (large multi-step
+plans, deep delegation chains), the agent should:
+
+1. Send an interim acknowledgement back to the platform so the user knows the
+   request landed (`adapter.sendResponse({ text: "Working on it..." })`).
+2. Persist intermediate state in chat-thread data, application state, or a
+   recurring job so the next invocation can pick up where this one left off.
+
+The retry job will only re-fire tasks stuck in `processing` for over 5 minutes,
+so a normal long-running reply is safe.
+
+## Cross-Platform Considerations
+
+- **No platform-specific background APIs.** No `waitUntil`, no
+  `-background.ts` filenames, no Vercel `after()`. The pattern works
+  identically on every host because it only uses `fetch()` and SQL.
+- **No assumed runtime.** The processor endpoint is a normal H3 handler under
+  `/_agent-native/`. It runs wherever the rest of the framework runs.
+- **No persistent in-memory state.** The dedup map in the webhook handler is
+  best-effort only; the SQL queue is the source of truth. Any cold start
+  loses the dedup map but the queue stays consistent.
+- **Postgres + SQLite both supported.** `claimPendingTask` uses `RETURNING` on
+  Postgres and a re-read on SQLite. No platform-specific SQL.
+- **Self-webhook URL resolution.** The processor URL is built from
+  `WEBHOOK_BASE_URL`, `APP_URL`, or `URL` env vars (with `localhost:3000` as
+  the dev fallback). Templates that change their public URL must keep one of
+  these set.
+
+## Why Fire-and-Forget on Serverless Is Unreliable
+
+Even though the webhook handler does `fetch(processorUrl, ...)` without
+awaiting the response body, that initial dispatch is **not** guaranteed to
+complete before the function freezes. In practice it usually does — the TCP
+connect + write happens quickly — but the recurring retry job is the safety
+net for the cases where:
+
+- The serverless platform froze the handler before the outbound `fetch`
+  flushed its bytes.
+- The processor function 502'd or cold-started slow enough to time out.
+- The processor itself was killed mid-agent-loop (function timeout, container
+  shutdown, deploy mid-run).
+
+Tasks stuck in `pending` for >90s or `processing` for >5min get re-fired up to
+3 times. After 3 attempts they're marked `failed` permanently so we stop
+spamming the processor.
+
+**Never assume the initial fire-and-forget succeeded.** Always rely on the
+queue + retry job for at-least-once delivery.
+
+## Debugging Checklist
+
+1. **Platform sent the webhook?** Check the platform's delivery logs (Slack
+   admin, Telegram `getWebhookInfo`).
+2. **Webhook handler returned 200?** If not, the platform retries — look for
+   duplicate task rows. Signature failures return 401.
+3. **Task in the queue?** `SELECT * FROM integration_pending_tasks WHERE
+   external_thread_id = '...' ORDER BY created_at DESC LIMIT 5`.
+4. **Status?** `pending` means the processor never picked it up — check that
+   `_process-task` is reachable from the box itself (the self-fetch must work
+   over the public URL). `processing` for over 5 minutes means the processor
+   died mid-run — the retry job will pick it up.
+5. **Failed?** Check `error_message` and `attempts`. After 3 attempts the row
+   is parked at `failed` and won't be retried.
+6. **Reply not delivered?** The processor likely succeeded but
+   `adapter.sendResponse` failed — check the adapter's outbound logs.
+
+## Related Skills
+
+- `server-plugins` — How `/_agent-native/` routes get mounted
+- `recurring-jobs` — Pattern the retry job follows
+- `actions` — When to use an action vs a webhook
+- `secrets` — Registering platform tokens
+- `onboarding` — Surfacing setup steps for each platform
+- `delegate-to-agent` — How the processor invokes the agent loop

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

@@ -0,0 +1,192 @@
+---
+name: observability
+description: >-
+  Agent observability, evals, feedback, and experiments. Use when adding
+  observability dashboards, configuring trace capture, setting up evals,
+  creating A/B experiments, or collecting user feedback on agent responses.
+---
+
+# Agent Observability
+
+## Rule
+
+The observability system auto-instruments every agent run with zero configuration. Traces, automated evals, and feedback collection work out of the box. All data lives in the app's own SQL database — no external services required. Templates can optionally export to Langfuse, Datadog, or any OTel-compatible platform.
+
+## Five Pillars
+
+### 1. Traces
+
+Every `runAgentLoop()` call is automatically instrumented via `instrumentAgentLoop()` in `packages/core/src/observability/traces.ts`. It captures:
+
+- **agent_run** span — top-level parent with total duration and cost
+- **llm_call** span — model name, token counts (input, output, cache read/write), cost
+- **tool_call** spans — one per action invocation, with duration and success/error
+
+Content (prompts, tool args, tool results) is **redacted by default**. Opt in via the `observability-config` settings key:
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  capturePrompts: false,
+  captureToolArgs: true,    // capture action input args
+  captureToolResults: false,
+  evalSampleRate: 0.05,     // 5% of runs get LLM-as-judge eval
+});
+```
+
+### 2. Feedback
+
+**Explicit** — `ThumbsFeedback` component renders inline thumbs up/down on every agent message in the chat UI. Thumbs down opens a category popover (Inaccurate, Not helpful, Wrong tool, Too slow). Already wired into `AssistantChat.tsx` via `React.lazy`.
+
+**Implicit** — `computeSatisfactionScore(threadId)` computes a Frustration Index (0-100) from conversation signals:
+- Rephrasing detection (weight 30): consecutive similar user messages
+- Abandonment (weight 20): session ends shortly after agent response
+- Sentiment (weight 15): negative language patterns
+- Length trend (weight 15): declining message lengths
+- Retry patterns (weight 20): "try again", "no that's wrong"
+
+Score interpretation: 0-20 healthy, 20-40 friction, 40-60 dissatisfied, 60+ broken.
+
+Satisfaction scoring fires automatically after each feedback POST with a threadId.
+
+### 3. Evals
+
+Three layers, configured via `evalSampleRate` in the observability config:
+
+**Automated (every run):** Deterministic scorers that run after every traced run:
+- `tool_success_rate` — % of tool calls without errors
+- `step_efficiency` — 1.0 for no-tool runs; penalizes excessive LLM iterations for tool-using runs
+- `latency_score` — normalized against 10s/tool baseline
+- `cost_efficiency` — normalized against 50 centicents/tool baseline
+- `error_recovery` — 1.0 if the run recovered from tool errors or had none
+
+**LLM-as-judge (sampled):** Runs on `evalSampleRate` fraction of runs. Calls the configured engine with a judge prompt that scores against custom criteria.
+
+**Dataset evaluation:** `runDatasetEval(datasetId)` runs a golden dataset through the agent and scores each case.
+
+Custom criteria use natural language rubrics:
+```ts
+const criteria: EvalCriteria = {
+  name: "helpfulness",
+  description: "Was the response helpful and complete?",
+  rubric: "0.0 = completely unhelpful, 0.5 = partially helpful, 1.0 = fully resolved the user's need",
+};
+```
+
+### 4. Experiments
+
+A/B testing with sticky user-level assignment:
+
+```ts
+import { createExperiment, startExperiment } from "@agent-native/core/observability";
+
+const exp = await createExperiment({
+  name: "sonnet-vs-haiku",
+  variants: [
+    { id: "control", weight: 50, config: { model: "claude-sonnet-4-6" } },
+    { id: "treatment", weight: 50, config: { model: "claude-haiku-4-5-20251001" } },
+  ],
+  metrics: ["cost", "latency", "satisfaction"],
+});
+await startExperiment(exp.id);
+```
+
+The agent loop reads active experiments via `resolveActiveExperimentConfig()` and applies the variant's `model` override automatically. Assignment uses consistent hashing — same user always gets the same variant.
+
+Compute results with `POST /_agent-native/observability/experiments/:id/results`.
+
+### 5. Dashboard
+
+`ObservabilityDashboard` is a React component with 5 tabs:
+- **Overview** — metric cards (runs, cost, latency, tool success, thumbs up rate, eval score)
+- **Conversations** — trace list with drill-down to span detail
+- **Evals** — eval stats and criteria breakdown bars
+- **Experiments** — experiment list with status badges, drill-down to results
+- **Feedback** — feedback stream, thumbs ratio, category badges
+
+Add a dashboard route to any template:
+```tsx
+// app/routes/observability.tsx
+import { ObservabilityDashboard } from "@agent-native/core/client";
+
+export default function ObservabilityPage() {
+  return (
+    <div className="min-h-screen bg-background p-6">
+      <ObservabilityDashboard />
+    </div>
+  );
+}
+```
+
+## API Endpoints
+
+All auto-mounted at `/_agent-native/observability/*`:
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/` | Overview stats |
+| GET | `/traces` | List trace summaries |
+| GET | `/traces/:runId` | Trace detail (summary + spans) |
+| GET | `/traces/:runId/evals` | Evals for a run |
+| POST | `/feedback` | Submit feedback |
+| GET | `/feedback` | List feedback entries |
+| GET | `/feedback/stats` | Feedback aggregation |
+| GET | `/satisfaction` | Satisfaction scores |
+| GET | `/evals/stats` | Eval statistics |
+| POST | `/experiments` | Create experiment |
+| GET | `/experiments` | List experiments |
+| GET | `/experiments/:id` | Experiment detail |
+| PUT | `/experiments/:id` | Update experiment status |
+| POST | `/experiments/:id/results` | Compute experiment results |
+| GET | `/experiments/:id/results` | Get experiment results |
+
+All endpoints support `?since=N` (ms timestamp) and `?limit=N` query params.
+
+## SQL Tables
+
+9 tables created automatically via `ensureObservabilityTables()`:
+- `agent_trace_spans` — individual trace spans
+- `agent_trace_summaries` — aggregated run summaries
+- `agent_feedback` — explicit user feedback
+- `agent_satisfaction_scores` — computed frustration index
+- `agent_evals` — evaluation results
+- `agent_eval_datasets` — golden test datasets
+- `agent_experiments` — experiment definitions
+- `agent_experiment_assignments` — user → variant assignments
+- `agent_experiment_results` — computed metric results
+
+All tables are dialect-agnostic (SQLite + Postgres) and strictly additive.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `packages/core/src/observability/types.ts` | Shared type definitions |
+| `packages/core/src/observability/store.ts` | SQL tables + CRUD |
+| `packages/core/src/observability/traces.ts` | Auto-instrumentation |
+| `packages/core/src/observability/feedback.ts` | Feedback + Frustration Index |
+| `packages/core/src/observability/evals.ts` | Eval engine (3 layers) |
+| `packages/core/src/observability/experiments.ts` | A/B testing system |
+| `packages/core/src/observability/routes.ts` | HTTP API handlers |
+| `packages/core/src/client/observability/ObservabilityDashboard.tsx` | Admin dashboard |
+| `packages/core/src/client/observability/ThumbsFeedback.tsx` | Inline feedback buttons |
+| `packages/core/src/client/observability/useObservability.ts` | React Query hooks |
+
+## Export to External Platforms
+
+Configure OTLP export in the observability settings:
+
+```ts
+await putSetting("observability-config", {
+  enabled: true,
+  exporters: [
+    {
+      type: "otlp",
+      endpoint: "https://cloud.langfuse.com/api/public/otel",
+      headers: { Authorization: "Bearer ..." },
+    },
+  ],
+});
+```
+
+The framework emits `gen_ai.*` semantic convention spans compatible with Langfuse, Datadog, Grafana, New Relic, and any OTel-compatible backend.

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

@@ -0,0 +1,43 @@
+---
+name: onboarding
+description: >-
+  How to register user-facing setup steps (API keys, OAuth, connecting
+  third-party services) for the sidebar setup checklist. Use when adding a
+  feature that needs initial user configuration.
+---
+
+# Onboarding Steps
+
+## Rule
+
+If a feature requires user-facing setup (API keys, OAuth, connecting a third-party service), register an onboarding step so it appears in the agent sidebar's setup checklist.
+
+## Registering a Step
+
+```ts
+import { registerOnboardingStep } from "@agent-native/core/onboarding";
+
+registerOnboardingStep({
+  id: "gmail",
+  order: 100,
+  title: "Connect Gmail",
+  description: "Grant read/send access.",
+  methods: [
+    {
+      id: "oauth",
+      kind: "link",
+      primary: true,
+      label: "Sign in with Google",
+      payload: { url: "/_agent-native/google/auth-url" },
+    },
+  ],
+  isComplete: () => !!process.env.GMAIL_REFRESH_TOKEN,
+});
+```
+
+See `packages/core/docs/content/onboarding.md` for method kinds and built-in steps.
+
+## Related Skills
+
+- `adding-a-feature` — The four-area checklist; onboarding is often part of a new integration
+- `authentication` — Most onboarding steps involve OAuth or credentials