@agent-native/core 0.152.1 → 0.153.1

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

@@ -1,299 +0,0 @@
----
-name: performance
-description: >-
-  Keep apps and templates loading fast. Read when adding a data model, a
-  list/read action, a page or sidebar that loads data, or when something loads
-  slowly, or when adding a dependency to the deployed server bundle. Covers
-  column projection, indexing hot-path queries, avoiding N+1 and round-trip
-  waterfalls, cheap polling, not recomputing on every read, and cold-start
-  artifact size.
-scope: dev
-metadata:
-  internal: true
----
-
-# Performance — Keep Loads Fast
-
-## Rule
-
-Treat every list, every read, and every page load as a latency budget. Two
-things dominate it: **how much data crosses the wire**, and **how many
-round-trips and table scans it takes**. On a hosted/serverless SQL backend each
-query is a network round-trip, and an unindexed filter scans the whole — often
-shared and growing — table. So default to **projected columns**, **indexed
-hot-path queries**, and **parallel/batched** fetches. These rules are
-provider-agnostic: they hold on SQLite, Postgres, or any managed SQL backend.
-
-This skill is about the data and load path. See the `storing-data` skill for the schema
-and migration mechanics it references, and the `real-time-sync` skill for how updates
-already reach the UI without polling.
-
-## 1. Project columns — never `SELECT *` on a list
-
-A list/index query should select only the columns the list actually renders.
-
-- **Never return heavy columns in a list**: large JSON/text blobs such as
-  document bodies, rendered HTML, `config`/`layout`/`spec`/`data`/`tracks`,
-  tool results, or base64 attachments. Pulling them for every row is the single
-  most common cause of a slow list.
-- Heavy/full columns belong on the **single-item GET/detail** path only.
-- Need a preview from a big column? Select a **truncated substring at the DB**,
-  not the whole column — and it stays portable:
-
-  ```ts
-  // Drizzle — project, and truncate the heavy column for the preview
-  const rows = await db
-    .select({
-      id: docs.id,
-      title: docs.title,
-      updatedAt: docs.updatedAt,
-      // substr/length work on both SQLite and Postgres
-      preview: sql<string>`substr(${docs.content}, 1, 400)`,
-    })
-    .from(docs)
-    .where(accessFilter(docs, docShares))
-    .orderBy(desc(docs.updatedAt));
-  ```
-
-- After narrowing the projection, update the row mapper and its return type so a
-  dropped column is provably unused on the list path. If the list genuinely
-  renders a heavy column (a thumbnail, an inline preview the UI shows), keep it —
-  don't break behavior to chase a payload win.
-
-## 2. Index the hot paths
-
-Indexes are added through the **versioned migration array** in
-`server/plugins/db.ts` as `CREATE INDEX IF NOT EXISTS …` — not through a
-schema-level `index()` helper (the framework applies indexes via migrations; see
-the `storing-data` skill). Add an index for any column a hot query **filters or sorts**
-on. The recurring ones:
-
-- **Ownable tables** → `(owner_email, org_id, <the list's ORDER BY column>)`.
-  Access scoping filters by owner/org and lists sort by `updated_at`/`created_at`.
-- **Shares tables** (`{resource}_shares`) → `(resource_id, principal_type, principal_id)`.
-  Access checks run correlated `EXISTS` subqueries against these on every list.
-- **Child / foreign-key columns** used to load children (e.g. `responses.form_id`,
-  `comments.parent_id`, an events log's `*_id`) → index the FK, plus its sort
-  column when the children are ordered. An unindexed FK means a full scan of the
-  child table on every parent open. **A foreign-key reference does not create an
-  index automatically** — add it explicitly.
-- **Status-filtered lists** → match the real `WHERE`, e.g. `(owner_email, status)`
-  or `(status, <sort>)`.
-
-Keep index DDL **dialect-agnostic and idempotent**:
-
-```sql
-CREATE INDEX IF NOT EXISTS forms_owner_org_updated_idx ON forms (owner_email, org_id, updated_at)
-```
-
-No `DESC`, no partial `WHERE`, no provider-specific syntax — it then runs on
-SQLite and Postgres alike, is safe to re-run, and applies on next startup.
-Indexes mostly bite **as data grows** and on **unbounded child tables** (a
-seq-scan of 10 rows is instant; of a shared, ever-growing log it is not), so
-index the growing tables first.
-
-## 3. Don't fan out queries — batch and parallelize
-
-- **No N+1.** Never loop issuing one query per item. Load children for many
-  parents in one `inArray(child.parentId, ids)` query, then group in memory.
-- **Count in SQL** (`count()`), never "select all rows then `.length`".
-- **Parallelize independent queries** with `Promise.all` rather than sequential
-  `await`s — each `await` is another round-trip.
-- Prefer **one composed endpoint** over several dependent calls.
-
-For provider wrappers, inspect the upstream API before building a list-then-
-enrich flow. Prefer the richest endpoint that can apply the real filters and
-return the needed associations or participants in one paginated operation.
-Cursor pagination is already serial; adding a serial detail/enrichment request
-to every page doubles its critical path. Exhaustive records belong in corpus
-recipes or data programs with explicit coverage, not one agent tool call per
-page or item.
-
-First-class provider actions should represent one stable conceptual operation.
-Keep arbitrary endpoint, filter, and pagination access in the provider API
-substrate; do not turn a convenience action into a capability ceiling or
-duplicate the provider transport, auth, quota, and cache implementation.
-
-## 4. Avoid client-side waterfalls
-
-- Don't gate query B on query A's result unless B truly needs it. Fire
-  independent `useActionQuery` / `useQuery` hooks **in parallel**; never make the
-  loading skeleton wait on a serial chain.
-- Load the visible page from one read where possible, and **lazy-load**
-  secondary / below-the-fold data after first paint.
-
-## 5. Poll cheaply; compute once
-
-- Updates already reach the UI through the `real-time-sync` skill (`useDbSync` / SSE).
-  Don't add an aggressive `refetchInterval` that re-runs a heavy list/read every
-  couple of seconds. If you must poll, use a **wide interval** and a **cheap**
-  endpoint.
-- **Never do expensive per-request work on a read that runs on every load/poll**:
-  re-rendering HTML/markdown, pretty-printing, re-parsing / migrating /
-  normalizing / sanitizing stored JSON. Do that work at **write time** (store the
-  result) or compute it **lazily only for the caller that needs it**. Reads on
-  the hot path must be cheap.
-- Data the UI doesn't display (export formats, alternate renderings) belongs in a
-  separate on-demand action, not baked into the hot read.
-
-## 6. SSR shell caching — load-bearing, do not undo
-
-Every SSR HTML page and React Router `.data` response is one impersonal,
-public shell, hard-cached at the CDN and served identically to every visitor —
-logged in or not. This is the single biggest lever on first-response latency:
-one shared cache entry serves the whole site instead of a per-user render on
-every request. Adding `private`, `no-store`, `Vary: Cookie`, a session read, or
-an auth branch to the SSR path defeats the cache for **every visitor**, not
-just one.
-
-If you're debugging a slow first response, check whether something
-re-personalized the shell before concluding the render itself is slow — the
-fix is client-side data loading after the shell paints, never per-user SSR. If
-the shell is clean and a cold miss is still seconds long, the cost is upstream
-of the render: see §9.
-See the `authentication` skill for the full model and `guard:ssr-cache-shell`
-plus `ssr-handler.spec.ts` (`packages/core/src/server/ssr-handler.ts`) for the
-enforced contract.
-
-**Never route mutation-fresh reads through SSR loader data.** Data that changes
-when a user acts belongs in an action, read from the client with
-`useActionQuery` / `useActionMutation` and kept live by `useDbSync()` polling —
-that path never touches the SSR shell cache. A `useRevalidator()` after a
-mutation re-fetches `.data` with a plain GET and can legitimately be served the
-cached copy. SSR loaders render the public shell; the client resolves anything
-that must be fresh.
-
-The one supported knob is the deployment-wide `AGENT_NATIVE_SSR_CACHE` env var:
-unset/`on` keeps the default, `off` sends `no-store`, and a duration such as
-`30s` / `5m` shortens freshness. It is for deployments whose host does not purge
-its CDN on deploy, or whose loaders genuinely serve mutable public data. It
-changes cache duration only — cookies are still stripped before render, so
-turning it off does not make SSR personalized. There is deliberately no
-per-route or per-request override; that is how one visitor's payload lands in
-another visitor's shared CDN entry.
-
-## 7. Big payloads and long lists
-
-- **Paginate or window** unbounded lists (messages, responses, events, activity).
-  Don't load the entire history on open; load a recent window and fetch older on
-  demand.
-- Don't store **unbounded blobs inline** in a row that a list/load pulls.
-  Reference large content separately so opening the parent stays cheap.
-- Never inline binary payloads in columns a list, poll, or `view-screen` summary
-  reads. Images, PDFs, audio/video, archives, screenshots, and base64
-  attachments belong in file/blob storage; SQL rows should hold URLs, asset ids,
-  storage keys, or opaque blob refs.
-- **Virtualize** very long rendered lists on the client so off-screen rows aren't
-  parsed/rendered every update.
-
-## 8. Don't do data work at startup
-
-A server plugin's body is not "once per deploy." These apps run as serverless
-functions, so it runs **once per cold start** — on the critical path of whichever
-user's request woke the process, and again on the next cold start. An in-process
-`let done = false` memo does not help: the new isolate starts with `false`.
-
-This has already cost real outages and sustained slowness here, not hypothetical
-ones — Slides startup slowness, Analytics paying startup cost on API calls, and a
-production incident. The shape that did it:
-
-```ts
-// templates/<app>/server/plugins/db.ts — every cold start pays all of this
-export default async (nitroApp) => {
-  await migrations(nitroApp);
-  await retypeBooleanColumnsOnPostgres();   // rewrites tables on Postgres
-  await backfillLegacyTables();
-  await syncWorkspacesToOrganizations();
-  await backfillRecordingOrgId();
-};
-```
-
-Schema DDL is **not** exempt, though it reads like it should be. Measured on a
-180-table production database: the migration "fast path" (`SELECT MAX(version)`)
-took **5.5s** and the `information_schema` probe **8.3s** — paid on every cold
-start, until health checks timed out and the app was down. Bounded is not the
-same as fast, and "it short-circuits cheaply" is an assumption until someone
-measures it on the largest database you have.
-
-The same applies doubly to **work whose cost grows with the data** — backfills, retypes, aggregations, recomputes, re-syncs,
-sweeps, cache warming, index rebuilds. Those have three better homes, all of
-which already exist:
-
-- a **scheduled job** (`recurring-jobs`, `automations` skills),
-- a **one-off CLI or release-time script**, run deliberately, once,
-- **lazily behind the first caller that needs it**, memoized — accepting that
-  the memo is per-isolate, so the work must be small enough to repeat.
-
-If it truly must complete before the app can serve a correct response, it is a
-migration, not a backfill — say so on the line and keep it bounded:
-
-```ts
-await backfillOneRow(); // guard:allow-boot-data-work — single row, bounded
-```
-
-`guard:no-boot-data-work` fails on new boot-time data work, scoped to lines this
-branch adds. It cannot see everything — a helper that hides the work one call
-deeper reads as innocent — so the rule matters more than the check.
-
-## 9. Cold start is the artifact, not just the work it does
-
-§8 covers what the process does at boot. This covers how much there is to boot.
-Measured in production: a cold cache miss on `www.agent-native.com` returned in
-**4.5–6.0s** while the in-handler `server-timing: app;dur` was only **~2100ms** —
-the other ~2900ms is platform init, spent before any of our code evaluates. A
-different app with a healthy database measured **13.4s** TTFB on its first cold
-request with `app;dur=1338`, so ~12s of init. Platform init scales with the size
-of the deployed artifact. Every app pays it, and no query tuning can reach it.
-
-- **The `/*` page function is the one every visitor's cache miss wakes.** Nothing
-  belongs in it that a page render cannot call. Headless browsers, ffmpeg, image
-  rasterizers, and other heavy runtimes belong in the function that actually
-  invokes them, or behind a job — not in the default handler. PR #2684, titled
-  "Harden auth and cold-start data paths", put 78MB of headless Chromium into
-  every page function; nothing in the diff looked like a performance change.
-- **Each extra emitted function is a full second copy of the bundle.** Netlify
-  copies the whole server directory per function, so splitting out a
-  `-background` or per-route function multiplies existing weight rather than
-  dividing it. Trim the artifact before you split it.
-- **Already-compressed binaries do not shrink again in the deploy zip.** A
-  Brotli-packed browser or a static ffmpeg build costs close to its full size in
-  upload and in cold-start extraction. Budget from bytes on disk, never from an
-  assumption that compression will absorb it.
-- **Never resolve a copied dependency by walking ancestor `node_modules`.** In a
-  monorepo that walk does not fail — it finds a sibling app's copy and ships
-  that. Resolve from the app's own dependency root and throw when it is missing;
-  a silently-found wrong package is precisely the indistinguishable-from-success
-  failure this repo bans.
-
-`packages/core/src/deploy/build.ts` is what decides all of this: the
-platform/arch filter at `:2384-2410` and the per-preset copy list at
-`:4499-4504`. Adding a package there adds it to every page function.
-
-**Measure a built bundle by timing the import and forcing exit.** Never measure
-by waiting for the process to exit — module scope starts timers and opens
-handles, so process lifetime measures those, not boot cost. That exact mistake
-produced a wrong number during the investigation behind this section.
-
-```sh
-node -e 'const t=Date.now();import(process.argv[1]).then(()=>{console.log(`${Date.now()-t}ms`);process.exit(0)})' \
-  ./.netlify/functions-internal/server/main.mjs
-```
-
-## Checklist — run before shipping a list/read or a new table
-
-- [ ] List selects only displayed columns; heavy blobs excluded or `substr`-truncated.
-- [ ] Every hot-path `WHERE` / `ORDER BY` column is indexed (owner/org/sort,
-      shares `resource_id`, child FKs, status filters) via a `db.ts` migration.
-- [ ] No N+1; independent queries parallelized; counts via SQL `count()`.
-- [ ] Client fires independent queries in parallel, not a waterfall.
-- [ ] No heavy recompute on every read; no aggressive polling of heavy endpoints.
-- [ ] Unbounded lists are paginated/windowed; large blobs aren't inlined on the hot path.
-- [ ] SSR HTML/`.data` path stays session-blind and cacheable — no `private`,
-      `no-store`, `Vary: Cookie`, or auth branch added to it.
-- [ ] No data work added to a server plugin body / module scope — backfills,
-      aggregations and re-syncs run on every cold start there (see §8).
-- [ ] Mutation-fresh reads go through actions + `useActionQuery`, not SSR loader
-      data.
-- [ ] No heavy runtime (browser, ffmpeg, rasterizer) added to what the `/*` page
-      function ships, and no new copied dependency resolved by walking ancestor
-      `node_modules` (see §9).

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

@@ -1,333 +0,0 @@
----
-name: qa
-description: >-
-  Autonomous multi-app QA sweep that drives template apps with Playwright MCP.
-  Use only when the user explicitly runs /qa or asks for an end-to-end QA sweep.
-  Do not load it for ordinary feature work, single-page checks, or one-off bug
-  fixes.
-user-invocable: true
-scope: dev
-metadata:
-  internal: true
----
-
-# QA Testing
-
-Autonomous QA testing that spins up template apps, tests them with Playwright in parallel, fixes issues, retests, and reports findings. Only alerts the user when blocked.
-
-This is an explicitly requested sweep, not a default verification step. Do not run any part of it — dev servers, browser automation, tester agents — as follow-up to a normal code change.
-
-## Usage
-
-```
-/qa                                            # test mail, calendar, content, forms
-/qa --apps mail,forms                          # test specific apps
-/qa --focus "test form submission and compose"  # prioritize specific flows
-```
-
-## Browser MCP Readiness
-
-QA can use the framework's built-in browser MCP capabilities instead of a hand-written `mcp.config.json`. The built-ins are off by default and are toggled through `/_agent-native/mcp/builtin`.
-
-- Prefer `browser-playwright` for automated QA sweeps: it runs `npx -y @playwright/mcp@0.0.75`.
-- Use `browser-chrome-devtools` only when the test specifically needs to attach to a live Chrome session. It runs `npx -y chrome-devtools-mcp@0.26.0 --autoConnect --no-usage-statistics` and requires Chrome 144+ with remote debugging enabled. Do not assume it signs into the user's Chrome profile.
-- Browser built-ins are exclusive per scope: enabling Chrome disables Playwright and enabling Playwright disables Chrome.
-- `computer-use` runs `npx -y computer-use-mcp@1.8.0` and is macOS-only.
-
-**Args:**
-
-- `--apps` — comma-separated app names (default: `mail,calendar,content,forms`)
-- `--focus` — natural language guidance for what to prioritize
-
-## Orchestrator Steps
-
-You (the agent running this skill) are the orchestrator. Follow these steps in order.
-
-### Step 1: Parse Args
-
-Parse the user's invocation to determine:
-
-- **apps**: which apps to test (default: mail, calendar, content, forms)
-- **focus**: optional test priority guidance
-
-### Step 2: Check Credential Readiness
-
-For each app, check if required credentials exist:
-
-| App      | Check                                                    | Can test without? |
-| -------- | -------------------------------------------------------- | ----------------- |
-| forms    | No credentials needed                                    | Yes               |
-| content  | No credentials needed (Notion is opt-in)                 | Yes               |
-| calendar | `templates/calendar/.env` has `GOOGLE_CLIENT_ID` present | Partially — local events work, Google sync won't |
-| mail     | `templates/mail/.env` has `GOOGLE_CLIENT_ID` present     | Partially — UI renders, Gmail features won't |
-
-Read each app's `.env` file (if it exists) only to check whether required names
-are present. Never print, copy, summarize, paste, or pass `.env` values into
-tester prompts, reports, screenshots, logs, or chat. If credentials are missing:
-
-- Still test the app — many features work without external APIs
-- Include in the tester's instructions: "No Google credentials found. Test local features. Flag any feature that crashes without credentials as 'needs credentials' rather than a bug."
-- Only alert the user (via SendMessage to team lead or AskUserQuestion) if the app **cannot start at all**
-
-### Step 3: Start Dev Servers
-
-Start each app's dev server on a dedicated port using `run_in_background`:
-
-| App      | Port | Command |
-|----------|------|---------|
-| mail     | 9201 | `cd templates/mail && PORT=9201 pnpm dev` |
-| calendar | 9202 | `cd templates/calendar && PORT=9202 pnpm dev` |
-| content  | 9203 | `cd templates/content && PORT=9203 pnpm dev` |
-| forms    | 9204 | `cd templates/forms && PORT=9204 pnpm dev` |
-
-Start all servers in parallel (multiple Bash calls with `run_in_background: true`).
-
-Then verify each server is ready by polling with curl:
-
-```bash
-for i in {1..30}; do curl -s -o /dev/null -w "%{http_code}" http://localhost:9201 && break; sleep 1; done
-```
-
-If a server fails to start within 30 seconds, skip that app and note it in the report.
-
-### Step 4: Generate Test Plans
-
-For each app, read these files to understand what to test:
-
-1. `templates/<app>/app/routes/` or `templates/<app>/app/routes.ts` — discover all pages
-2. `templates/<app>/CLAUDE.md` — features, API routes, data model
-3. `templates/<app>/actions/` — domain operations the UI and agent share
-4. `templates/<app>/server/routes/api/` — route-only endpoints such as uploads, streaming, webhooks, and OAuth callbacks
-
-Combine with any `--focus` guidance to produce a test plan. The test plan is a numbered list of user-facing flows to verify. Example:
-
-```
-1. Home page loads without errors
-2. Create a new item via the UI
-3. Edit an existing item
-4. Delete an item
-5. Check all navigation links work
-6. Verify no console errors on any page
-7. Verify no failed network requests
-```
-
-### Step 5: Create Team and Spawn Testers
-
-Create a team and spawn one tester agent per app, all in parallel:
-
-```
-TeamCreate: name="qa", description="QA testing sweep"
-```
-
-Create one task per app:
-
-```
-TaskCreate: subject="QA test <app> on port <port>", description="<test plan>"
-```
-
-Then spawn tester agents in parallel using the Agent tool. Each agent gets:
-
-- `name`: `qa-<app>` (e.g., `qa-mail`)
-- `team_name`: `qa`
-- `mode`: `auto`
-- The full tester prompt (see Tester Agent Prompt below)
-
-### Step 6: Monitor and Alert
-
-After spawning testers, wait for their idle notifications and task updates.
-
-- When a tester completes its task, note its findings
-- When a tester reports being blocked (missing credentials, app won't start, needs user input), relay that to the user via AskUserQuestion
-- When all testers are done, proceed to Step 7
-
-### Step 7: Compile Report and Shutdown
-
-Gather all tester reports from their task updates. Print a compiled summary:
-
-```markdown
-# QA Summary — <date>
-
-## Apps Tested: N
-## Total Issues Found: N
-## Fixed: N
-## Needs Review: N
-
-### Mail App
-[tester report]
-
-### Forms App
-[tester report]
-
-...
-```
-
-Then shut down all teammates:
-
-```
-SendMessage to each tester: { type: "shutdown_request" }
-```
-
----
-
-## Tester Agent Prompt
-
-Use this as the prompt when spawning each tester agent via the Agent tool. Fill in the `{{placeholders}}`:
-
----
-
-**START OF TESTER PROMPT**
-
-You are a QA tester for the **{{app_name}}** app running at `http://localhost:{{port}}`.
-
-## Your Mission
-
-Test the app thoroughly using Playwright MCP tools. Find bugs, fix them, retest. Report your findings.
-
-## Team Context
-
-You are on team "qa". Your name is "qa-{{app_name}}".
-
-- Use TaskUpdate to mark your task as `in_progress` when you start
-- Use TaskUpdate to mark your task as `completed` when done, with your report in the description
-- If you are blocked and need user input, send a message to the team lead explaining what you need
-
-## Credential Status
-
-{{credential_status}}
-
-## Test Plan
-
-{{test_plan}}
-
-## How to Test
-
-Use these Playwright MCP tools:
-
-1. **Navigate**: `browser_navigate` to `http://localhost:{{port}}<path>`
-2. **See the page**: `browser_snapshot` — returns an accessibility tree showing all visible elements with `ref` attributes
-3. **Click**: `browser_click` with `ref` from the snapshot
-4. **Type**: `browser_type` with `ref` and `text`
-5. **Fill forms**: `browser_fill_form` with `ref` and `values`
-6. **Check console**: `browser_console_messages` — look for errors
-7. **Check network**: `browser_network_requests` — look for failed requests (4xx, 5xx)
-8. **Wait**: `browser_wait_for` when you need to wait for content to appear
-9. **Screenshot**: `browser_take_screenshot` when you want to capture the visual state
-
-### Testing Loop
-
-For each test in your plan:
-
-1. Navigate to the relevant page
-2. Take a snapshot to see what's on screen
-3. Check console messages for errors
-4. Check network requests for failures
-5. Interact with the page — click buttons, fill forms, navigate flows
-6. If something is broken:
-   a. Document: what page, what's wrong
-   b. Read the relevant source files to understand the issue
-   c. Fix the code
-   d. Wait 2-3 seconds for Vite HMR to hot-reload
-   e. Retest by taking a new snapshot
-   f. If still broken after 3 attempts, mark as "needs human review" and move on
-7. Move to the next test
-
-After completing all tests, do **one more pass** on any pages where you found issues to verify fixes didn't break other things.
-
-**Maximum 2 full passes.** Don't loop forever.
-
-### Start by navigating to the home page
-
-Always start by navigating to `http://localhost:{{port}}/` and taking a snapshot to verify the app is running.
-
-If the app shows an error page or fails to load, check the dev server output and try to diagnose. If it's a missing dependency or config issue, report it and stop — don't spend time debugging infrastructure.
-
-## Isolation Rules
-
-**CRITICAL:** You may ONLY modify files within `templates/{{app_name}}/`. If a bug requires changes to `packages/core/` or any other template, report it as a finding but do NOT fix it.
-
-After modifying any source file, run:
-```bash
-npx prettier --write <file>
-```
-
-## What Counts as a Bug
-
-- Page crashes or shows error overlay
-- Console errors (not warnings — errors only)
-- Network requests returning 4xx or 5xx
-- Buttons/links that don't work
-- Forms that don't submit
-- Data that doesn't save or display
-- Layout severely broken (overlapping text, invisible elements)
-- Features described in CLAUDE.md that don't work
-
-What is NOT a bug:
-- Minor styling preferences
-- Missing features that aren't described in CLAUDE.md
-- Warnings in console
-- Slow loading (unless > 10 seconds)
-
-## Report Format
-
-When you're done, update your task (via TaskUpdate) with status `completed` and set the description to your report:
-
-```markdown
-## QA Report: {{app_name}}
-
-### Summary: N found, N fixed, N needs review
-
-#### Fixed
-1. **Short description** — What file you changed and why
-
-#### Needs Review
-1. **Short description** — Why you couldn't fix it
-
-#### Skipped (needs credentials)
-1. **Feature name** — What credential is needed
-
-#### Pages Tested
-- /path (page name) — status (OK, N issues fixed, N needs review)
-```
-
-**END OF TESTER PROMPT**
-
----
-
-## Troubleshooting
-
-### Port already in use
-
-Kill the process on the port before starting:
-
-```bash
-lsof -ti :9201 | xargs kill -9 2>/dev/null; true
-```
-
-### Dev server won't start
-
-Common causes:
-
-- Missing `node_modules` — run `pnpm install` from root first
-- Missing `.env` file — some apps need one even if empty. Check `.env.example`
-- Port conflict — kill stale processes (see above)
-- Build error in core — run `pnpm --filter @agent-native/core build` first
-
-### Playwright MCP not responding
-
-The Playwright MCP server must be configured in Claude Code's MCP settings. If browser tools aren't available, the tester agent should report "Playwright MCP tools not available" and stop.
-
-### HMR not picking up changes
-
-After editing a file, wait 2-3 seconds. If the page doesn't update, try a hard refresh by navigating away and back. Vite HMR sometimes misses changes in server-side files — restart the dev server if needed.
-
-### App shows "credentials not configured" when they are
-
-This is a known issue. The tester should:
-
-1. Check the `.env` file exists and has the right variable names
-2. Check if the app reads from `.env` or `data/.env`
-3. Check the server plugin that loads credentials
-4. Try to fix the credential detection logic
-5. If unfixable, report as "needs review" with details about what the app expects vs. what's configured
-
-Only report variable names and presence/absence. Do not include secret values.