agentful 0.2.5 → 0.2.7

package/README.md

@@ -22,7 +22,7 @@ agentful open               # open the preview
 
 | Command | Purpose |
 | --- | --- |
-| `login` / `logout` / `whoami` | Browser-based sign-in; the token is kept in the macOS Keychain |
+| `login` / `logout` / `whoami` | Browser-based sign-in; the token is kept in the macOS Keychain (on Linux: a `0600` file under `~/.config/agentful/`) |
 | `init [--link <id>] [--title <t>]` | Create a cloud project or link an existing one (`.agentful/project.json`) |
 | `push [--prebuilt [--dir <path>]]` | Upload the source and build in the cloud; `--prebuilt` uploads a local build |
 | `open` | Open the live preview |
@@ -42,9 +42,10 @@ build output and every `.env` file. Uploads are capped at 6 MB.
 
 ## Platform support
 
-v1.0 is **macOS only** (arm64 and x64). Linux and Windows engine artifacts are
-already mirrored and the code paths exist, but we do not advertise platforms we
-cannot test — enabling Linux is one line in `platformKey()` plus a test run.
+**macOS and Linux** (arm64 and x64 each). The device-flow login works headless:
+the CLI prints a URL plus a code, opening a browser is best-effort (`xdg-open`).
+Windows is not supported yet — win32 engine artifacts are not mirrored and the
+credential/spawn/extract assumptions are untested there.
 
 ## Engine distribution
 

package/dist/index.cjs

@@ -3044,7 +3044,7 @@ var VERSION, brand, useColor, wrap, paint, sym, ui;
 var init_branding = __esm({
   "src/branding.ts"() {
     "use strict";
-    VERSION = "0.2.5" ? "0.2.5" : null.version;
+    VERSION = "0.2.7" ? "0.2.7" : null.version;
     brand = {
       name: "agentful",
       // the command users type
@@ -5638,6 +5638,63 @@ function describeBackendDeclaration(decl) {
 function backendTabUrl(userId, projectId) {
   return `${APP_URL}/workspace/${userId}/${projectId}?view=backend`;
 }
+var ACTIONS_DIR = (0, import_node_path8.join)(".server", "actions");
+var ACTION_NAME = /^[a-z][a-z0-9_-]{0,62}$/;
+function checkBackendDeclaration(rootDir = process.cwd()) {
+  const issues = [];
+  const warnings = [];
+  const actionsDir = (0, import_node_path8.join)(rootDir, ACTIONS_DIR);
+  const presentFiles = /* @__PURE__ */ new Set();
+  if ((0, import_node_fs6.existsSync)(actionsDir)) {
+    for (const entry of (0, import_node_fs6.readdirSync)(actionsDir)) {
+      const abs = (0, import_node_path8.join)(actionsDir, entry);
+      let isDir = false;
+      try {
+        isDir = (0, import_node_fs6.statSync)(abs).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDir) {
+        issues.push(
+          `.server/actions/${entry}/ is a directory \u2014 action files must live directly under .server/actions/ (the platform rejects subdirectories).`
+        );
+        continue;
+      }
+      presentFiles.add(entry);
+      const name = entry.endsWith(".js") ? entry.slice(0, -3) : null;
+      if (name === null || !ACTION_NAME.test(name)) {
+        issues.push(
+          `.server/actions/${entry}: invalid action filename \u2014 must match [a-z][a-z0-9_-]{0,62}.js (names starting with _ are reserved). The platform rejects the whole push otherwise.`
+        );
+      }
+    }
+  }
+  const decl = readBackendDeclaration(rootDir);
+  const declared = decl?.actions ?? [];
+  for (const name of declared) {
+    if (!ACTION_NAME.test(name)) {
+      issues.push(
+        `.agentful/backend.json declares action "${name}" \u2014 names must match [a-z][a-z0-9_-]{0,62} (the filename without .js).`
+      );
+      continue;
+    }
+    if (!presentFiles.has(`${name}.js`)) {
+      issues.push(
+        `.agentful/backend.json declares action "${name}" but .server/actions/${name}.js does not exist \u2014 create the file or remove the declaration entry.`
+      );
+    }
+  }
+  const declaredSet = new Set(declared);
+  for (const file of presentFiles) {
+    const name = file.endsWith(".js") ? file.slice(0, -3) : file;
+    if (ACTION_NAME.test(name) && !declaredSet.has(name)) {
+      warnings.push(
+        `.server/actions/${file} is not declared in .agentful/backend.json \u2014 it will deploy, but \`agentful backend\` and the Backend tab won't know about it. Add "${name}" to the actions list.`
+      );
+    }
+  }
+  return { issues, warnings };
+}
 
 // src/lib/buildStatus.ts
 init_branding();
@@ -5686,16 +5743,18 @@ async function pushCommand(opts) {
   const rootDir = opts.prebuilt ? detectDistDir(process.cwd(), opts.dir) : process.cwd();
   if (mode === "source") {
     const pre = runPreflight(process.cwd());
-    for (const warning of pre.warnings) ui.warn(warning);
-    if (pre.issues.length > 0) {
+    const backendCheck = checkBackendDeclaration(process.cwd());
+    const issues = [...pre.issues, ...backendCheck.issues];
+    for (const warning of [...pre.warnings, ...backendCheck.warnings]) ui.warn(warning);
+    if (issues.length > 0) {
       if (opts.force) {
-        ui.warn(`Preflight found ${pre.issues.length} blocking issue(s) \u2014 continuing because of --force:`);
-        for (const issue of pre.issues) ui.info(issue);
+        ui.warn(`Preflight found ${issues.length} blocking issue(s) \u2014 continuing because of --force:`);
+        for (const issue of issues) ui.info(issue);
       } else {
         throw new ApiError(
           0,
           "preflight_failed",
-          "This project cannot run on the platform as pushed:\n" + pre.issues.map((issue) => `\u2022 ${issue}`).join("\n") + "\nPush with --force to attempt the cloud build anyway."
+          "This project cannot run on the platform as pushed:\n" + issues.map((issue) => `\u2022 ${issue}`).join("\n") + "\nPush with --force to attempt the cloud build anyway."
         );
       }
     }
@@ -5727,9 +5786,19 @@ async function pushCommand(opts) {
     );
   }
   ui.step("Uploading to your workspace\u2026");
+  const declaration = mode === "source" ? readBackendDeclaration() : null;
   const upload = await request(
     `${API_URL}/api/workspaces/${userId}/${projectId}/source-zip`,
-    { token: auth.pb_token, body: { zip_base64: zip.base64, mode, clean: true }, timeoutMs: 12e4 }
+    {
+      token: auth.pb_token,
+      body: {
+        zip_base64: zip.base64,
+        mode,
+        clean: true,
+        ...declaration ? { backend_declaration: declaration } : {}
+      },
+      timeoutMs: 12e4
+    }
   );
   ui.info(`${upload.files_written} files written`);
   if (mode === "source") {
@@ -5964,10 +6033,11 @@ function platformKey() {
   const { platform, arch } = process;
   const key = `${platform}-${arch}`;
   if (platform === "darwin" && (arch === "arm64" || arch === "x64")) return key;
+  if (platform === "linux" && (arch === "arm64" || arch === "x64")) return key;
   throw new ApiError(
     0,
     "unsupported_platform",
-    `The ${brand.displayName} TUI supports macOS for now (got ${platform}/${arch}). Linux and Windows follow once they are properly tested.`
+    `The ${brand.displayName} TUI supports macOS and Linux (got ${platform}/${arch}). Windows follows once it is properly tested.`
   );
 }
 function cacheDir(version) {
@@ -6307,6 +6377,24 @@ statically evaluable; prefer client-side fetch or Managed Server Actions.
 (b) an external backend called from the client. Never a bundled server
 process, and never a script the user must run locally to produce the result.
 
+## Managed backend API convention (hard rules)
+
+When the project uses the platform's managed backend, its ONLY API surface is:
+
+- Base: \`/api/p/{projectId}/\` \u2014 projectId comes from \`.agentful/project.json\`.
+- End-user auth: \`\u2026/auth/*\` (\`register\`, \`login\`, \`me\`, \`verify\`, \u2026).
+- Data CRUD: \`\u2026/data/{collection}\` and \`\u2026/data/{collection}/{docId}\`.
+- Managed Server Actions: \`POST \u2026/actions/{action-name}\` \u2014 and NOTHING else.
+
+Never invent your own REST paths (there is no \`/api/actions/\u2026\`), your own SQL
+schema, RLS model, or key handling \u2014 the platform defines all of that. Plain
+CRUD belongs in \`/data/*\` and auth in \`/auth/*\`; Actions are only for logic
+that needs secrets or a trust boundary. Actions are plain files at
+\`.server/actions/<name>.js\` in the source tree \u2014 \`agentful push\` deploys them
+with the rest of the project, no extra command. The full protocol (request/
+response shapes, error codes, client patterns) is the \`agentful-managed-db\`
+section of AGENTFUL_SKILLS.md \u2014 design against it, not from memory.
+
 When you design a managed backend (DB schema, server actions), also write the
 machine-readable declaration \`.agentful/backend.json\`:
 \`{"schema_version": 1, "managed_db": true, "actions": ["<action-name>", \u2026], "contract_doc": "docs/backend-contract.md"}\`
@@ -6488,6 +6576,7 @@ var skills_default = {
   schema_version: 1,
   skills: {
     "agentful-template-contract": "---\nname: agentful-template-contract\ndescription: Agentful generated-project and template contract for static preview/publish compatibility, scaffold-safe file structure, host-agnostic assets, backend honesty, and no unsupported dependencies. Use when creating a new project, customizing a scaffold/template, editing generated app structure, or fixing preview/publish issues.\n---\n\n# Agentful Template Contract\n\n## Contract\n\nGenerate and edit projects for Agentful's existing platform:\n\n- Static preview and publish serve built files from S3/CloudFront/Cloudflare.\n- Package projects must build to `dist/`, `out/`, or `build/`.\n- Vanilla projects must work without a package install or build step.\n- Managed database and managed actions are configured in the Backend tab, not invented in code.\n\nDo not add server-first framework runtime dependencies (for example Remix / `@remix-run/*`, or a Next.js server). A referenced example repo may inform structure or styling, but this platform serves static builds and does not run those servers.\n\n## File Shape\n\n- Preserve the current stack and file layout unless the user explicitly asks for a migration.\n- For empty workspaces, follow the loaded scaffold skill exactly.\n- Put route- or feature-local UI near the feature. Create shared folders only after real reuse exists.\n- Avoid dumping grounds such as `helpers`, `misc`, or broad `lib` folders when ownership is clear.\n- Keep generated documentation short and accurate; do not describe features that do not exist.\n\n## Hosting Rules\n\n- Asset paths for project-owned files: SPAs with a client-side (history-mode)\n  router use root-absolute paths (`base: '/'`, `/assets/...`); router-less or\n  multi-page projects use relative paths.\n- Use `/api/...` only for platform runtime APIs.\n- Do not hardcode `mainmvp.com`, `agentful.dev`, preview domains, or user subdomains into app code.\n- Do not add a `<base>` tag.\n- For canonical, Open Graph, sitemap, and manifest URLs, use relative URLs or omit the origin.\n- For SPAs on static hosting, use history-mode routing with `base: '/'` (never\n  hash routing) \u2014 the platform falls unknown deep-links back to `index.html`, so\n  routes resolve on hard refresh with clean URLs (no `#`).\n\n## Backend Honesty\n\n- When a backend is configured (`status: active`), use it for real data, auth, and actions.\n- When no backend is configured, still build the requested UI from clearly-labeled sample/demo data (one replaceable module). Do not refuse or stop \u2014 surface the Backend-tab note in your final response instead.\n- Sample data must read as sample. Do NOT fake auth that \"logs in\", saves that claim to persist across reloads, or payment/webhook flows that pretend to fire \u2014 those mislead the user. Presentation data (example metrics, sample listings) is fine; a fake real-backend contract is not.\n- Never store secret keys in frontend code, templates, `.env`, or committed files.\n- Public client keys may be placeholders only when the target integration actually uses public keys.\n\n## Content Honesty\n\nDo not invent:\n\n- customer logos, testimonials, reviews, awards, revenue, user counts, certifications, compliance claims, or legal assurances\n- real prices, policies, medical/financial claims, or guarantees unless the user supplies them\n\nUse neutral placeholder copy or proof-ready sections instead.\n\n## Before Finishing\n\n- Verify imports, references, asset paths, and routes are defined.\n- Run the relevant build when a build script exists.\n- Confirm the expected output folder contains an `index.html`.\n- For UI work, include responsive behavior and basic loading, empty, error, and success states where the feature implies them.\n",
+    "agentful-managed-db": "---\nname: agentful-managed-db\ndescription: Managed Database protocol for `database.mode == managed`. Covers schema upsert, CRUD against `/api/p/{PROJECT_ID}/data/*` and `/api/p/{PROJECT_ID}/auth/*`, error-code remediation, and per-framework client patterns (Vue, React, Svelte, SvelteKit, Astro, Vanilla). Load when the backend preamble shows `Database: managed`.\n---\n\n## When To Use\n\nLoad this skill **only** when `agentful-backend-state` reports `database.mode: \"managed\"` with `status: \"active\"`. Do not load it for `byo` (Supabase / custom server) or when the database is not configured.\n\n## Hard Rules\n\n1. **Collections do not auto-create.** Writes to a non-existent collection return 404 with `error.code: not_found`. For every collection your code reads or writes, if it is not listed in the backend preamble's `Managed collections` block, you MUST run `agentful-managed-collections upsert <project_id> '<json>'` BEFORE writing the code that touches it.\n2. **Never wrap data-API calls in a swallow-all `try/catch`.** Swallowing masks 4xx errors and produces apps that look-fine-but-write-nothing.\n3. **Never set a `seeded` flag unless every write returned 201.** Partial-success seeds drift state silently.\n4. **Do not call this a \"server\".** It is a managed database behind a gateway. Use \"the database\" when talking to the user.\n5. **Do not target `/data/_collections`** from generated code. That's the owner-only schema endpoint; use the `agentful-managed-collections` CLI for schema work.\n6. **On 5xx, do not speculate.** Surface `error.correlation_id` to the user verbatim and stop. Do not invent internal causes (DynamoDB, operators, system collections, etc.).\n\n## Authoring Protocol \u2014 for every collection touch\n\nRun, in order:\n\n1. **Read the preamble.** The `[BACKEND STATUS]` block lists existing `Managed collections` with their fields and access rules. If your target collection is there with the right shape, skip to step 3.\n2. **Upsert if missing or schema mismatch:**\n   ```\n   agentful-managed-collections upsert <project_id> '{\"name\":\"todos\",\"access_rule\":\"owner\",\"schema\":{\"fields\":[{\"name\":\"title\",\"type\":\"string\",\"required\":true},{\"name\":\"done\",\"type\":\"boolean\"}]}}'\n   ```\n   Field types: `string`, `text`, `number`, `boolean`, `select` (with `options`), `datetime` (ISO 8601 string), `json` (object or array).\n   Access rules: `public` (anyone), `authenticated` (any logged-in end-user), `owner` (only `created_by` user).\n3. **Write the client code** using the patterns below. Use the EXACT field names from the schema. Do not invent fields.\n4. **Test the happy path** by inspecting the response. Real 201 / 200, not a swallowed error.\n\n## Choosing An Access Rule\n\n`access_rule` is set per collection at upsert time and enforced on every end-user\n(`/data/*`) request. There are exactly three rules \u2014 pick by use case:\n\n| Use case | Rule | Why |\n|---|---|---|\n| Content anyone may read/write without login (public poll, guestbook) | `public` | No JWT required. |\n| Public content the app seeds once and the UI only reads | `public` | Seed at build time; clients read only. |\n| Shared data **every** logged-in user may read AND edit (team wiki, shared catalog) | `authenticated` | Any valid end-user JWT passes. **No per-row owner check.** |\n| Per-user private data (todos, drafts, a user's own orders) | `owner` | Only the `created_by` end-user can read/update/delete each doc. |\n| Per-user data an **admin must also access** (invoices, tickets, client records) | `owner` + admin via Action | `owner` protects the client; admin reads/writes through a Managed Action. See RBAC below. |\n| A field only the server may set (`role`, `plan`, `verified`, `balance`) | `owner`, with that field written **only** via an Action | No field-level rules exist \u2014 gate the whole mutation behind an Action. |\n\n**Two traps to design around:**\n\n1. **`authenticated` is NOT per-user isolation.** It means *every* logged-in\n   user can read and write *all* documents in the collection. For \"each user\n   sees only their own\", use `owner`.\n2. **There is no combined `owner_or_admin` rule and no role concept in the data\n   layer.** A multi-role portal (admin / member / client) cannot be expressed by\n   `access_rule` alone. The supported pattern is `owner` + a Managed Action that\n   verifies the caller \u2014 see **RBAC & Secure Role Assignment** under Managed\n   Actions. (Requires `server.mode == managed`.)\n\n## API Surface\n\nBase: `/api/p/{PROJECT_ID}/`\n\n**Auth (end-user):**\n- `POST auth/register` \u2014 `{email, password, display_name?}`. Two response shapes:\n  - Verification pipeline ACTIVE (project has `config.auth`, default): `201 {verification_required:true, user:{...}}` \u2014 **NO token yet**; the user must confirm their email first (mail is sent automatically).\n  - Legacy project (no `config.auth`) or `require_verified_login:false`: `201 {token, verification_required:false, user:{...}}`.\n- `POST auth/login` \u2014 `{email, password}` \u2192 `{token, user:{...}}`. Blocks with `403 email_unverified` when the project requires verified logins and the account is not verified yet \u2192 show a \"check your inbox\" state with a resend button.\n- `GET auth/me` \u2014 Bearer token \u2192 `{user:{...}}`\n- `POST auth/verify` \u2014 `{uid, token}` (from the mail link) \u2192 `{token, user}` (auto-login after verification).\n- `POST auth/resend-verification` \u2014 `{email}` \u2192 always `200 {sent:true}` (no user enumeration).\n- `POST auth/request-password-reset` \u2014 `{email}` \u2192 always `200 {sent:true}` (no user enumeration).\n- `POST auth/reset-password` \u2014 `{uid, token, password}` \u2192 `200 {reset:true}`. Also marks the mailbox verified.\n\n`user` shape: `{id, email, display_name, role, verified, provider, created_at}`.\n\n**Auth mail links:** verification/reset mails link to the deployed app as\n`{app_url}/?ta_action=verify&uid=\u2026&token=\u2026` and `{app_url}/?ta_action=reset&uid=\u2026&token=\u2026`.\n**Every generated app with auth MUST handle these two query params on load**\n(see Client Patterns).\n\n**Login methods governance:** offer ONLY the login methods the project's\n`config.auth.methods` allows (check with `agentful-auth-config get`;\ndefault `[\"email\"]`). Do NOT generate \"Sign in with Google\"/SSO buttons unless\n`google`/`oidc` is listed \u2014 the platform refuses unlisted methods server-side.\n\n**Google login (when `google` IS listed):** a \"Continue with Google\" button\ncalls `googleAuth.start()` (see Client Patterns) \u2192 central broker\n`api.agentful.dev/auth/oauth/google/start` \u2192 Google \u2192 back to the app with the\nJWT in the URL fragment; call `handleGoogleReturn()` at startup to complete\nthe login. Google users arrive `verified: true` (Google verified the mailbox),\nexisting email accounts with the same address are linked automatically, and\nthe `admin_email` bootstrap applies. Show `auth_error` codes as a friendly\nmessage (`auth_method_not_allowed` \u2192 \"Google login is not available for this\napp\"); never retry in a loop.\n\n**Data:**\n- `GET data/{collection}` \u2014 list (paginated; `?limit=`, `?cursor=`)\n- `GET data/{collection}/{docId}` \u2014 single doc\n- `POST data/{collection}` \u2014 body `{data: {...}}` \u2192 `{ok:true, data:{doc_id, collection, data, created_at}}`\n- `PUT data/{collection}/{docId}` \u2014 body `{data: {...}}` \u2192 updated doc\n- `DELETE data/{collection}/{docId}` \u2192 `{ok:true, data:{deleted, collection}}`\n\nEnd-user routes (above) require `Authorization: Bearer <token>` from `auth/register` or `auth/login`. The collection's `access_rule` enforces what each token may read/write.\n\n## Response Shapes\n\n**Success:** `{ \"ok\": true, \"data\": {...} }` \u2014 `data` for lists has `{documents:[...], count, cursor}`.\n\n**Error:** `{ \"ok\": false, \"error\": { \"code\": \"...\", \"message\": \"...\", \"correlation_id\"?: \"...\" } }`\n\nStatus codes are HTTP-conventional (201 on create, 200 on read/update/delete, 4xx for client errors, 5xx for platform).\n\n## Error Code \u2192 Remediation\n\n| `error.code` | HTTP | What it means | What to do |\n|---|---|---|---|\n| `not_found` | 404 | Collection doesn't exist, OR doc id doesn't exist | If collection: run `agentful-managed-collections upsert` then retry. If doc: surface to user. |\n| `email_unverified` | 403 | Login blocked until the user confirms their email | Show \"confirm your email\" state + resend button (`auth/resend-verification`). |\n| `invalid_token` | 400 | Verification/reset link invalid, expired, or already used | Offer resend (`resend-verification`) or a new reset request. |\n| `too_many_attempts` | 429 | Auth rate limit hit (failed logins / mail requests) | Tell the user to wait a few minutes; do not auto-retry. |\n| `email_infra_unconfigured` | 409 | Project has no email infrastructure selected | Tell the BUILDER (not the end-user): choose \"Agentful Email\" or BYO in project settings \u2192 Email infrastructure. |\n| `email_send_failed` | 502 | Mail transport failed transiently | Tell the user to try again later. |\n| `schema_validation_failed` | 400 | Payload doesn't match the collection's schema | Re-read the schema in the preamble; fix field names/types/required-ness; do not retry blindly. |\n| `readonly_collection` | 403 | Collection or doc is system-protected (e.g. `_users` via end-user route) | Use the correct route (e.g. `auth/register` for `_users`); do not retry. |\n| `forbidden` | 403 | Access rule denied this end-user | Tell the user they need to log in / lack permission. |\n| `already_exists` | 409 | `doc_id` collision or conditional check failed | Let `doc_id` auto-generate (omit it). |\n| `too_large` | 413 | Document > 256 KB | Split or trim payload. |\n| `quota_exceeded` | 429 | DDB throttling / request-limit spillover (transient) | The doctor returns `action: retry_with_backoff`. Sleep + retry up to 3 times per `details.backoff_ms`. **Surface `correlation_id` to the user ONLY after all attempts exhaust.** |\n| `transient_storage_error` | 503 | DDB internal / service-unavailable (transient) | Same as `quota_exceeded`: doctor returns `retry_with_backoff`; engine handles silently until budget exhausts. |\n| `internal_storage_error` / `write_failed` / `delete_failed` | 500 | Platform-side error, NOT classified retryable | Delegate to `@agentful-managed-db-doctor` with `correlation_id`. Surface its `user_message` verbatim. Do NOT retry in a loop. Do NOT invent a root cause. |\n\n## Client Patterns\n\nA tiny client used everywhere. Define once per project; reuse for all collections.\n\n### Vanilla / shared base\n\n```js\n// src/lib/data.js\nconst BASE = `/api/p/${PROJECT_ID}`; // set PROJECT_ID at build time\nconst tokenKey = 'mm_auth_token';\n\nfunction authHeader() {\n  const t = localStorage.getItem(tokenKey);\n  return t ? { Authorization: `Bearer ${t}` } : {};\n}\n\nasync function jsonOrThrow(res) {\n  const body = await res.json().catch(() => ({}));\n  if (!res.ok || !body.ok) {\n    const err = new Error(body.error?.message || `HTTP ${res.status}`);\n    err.code = body.error?.code;\n    err.correlation_id = body.error?.correlation_id;\n    err.status = res.status;\n    throw err;\n  }\n  return body.data;\n}\n\nexport const auth = {\n  async register(email, password, display_name) {\n    const data = await jsonOrThrow(await fetch(`${BASE}/auth/register`, {\n      method: 'POST', headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email, password, display_name }),\n    }));\n    // verification_required \u2192 NO token yet; caller must show \"check your inbox\".\n    if (data.token) localStorage.setItem(tokenKey, data.token);\n    return data; // {verification_required, user, token?}\n  },\n  async login(email, password) {\n    const data = await jsonOrThrow(await fetch(`${BASE}/auth/login`, {\n      method: 'POST', headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email, password }),\n    }));\n    localStorage.setItem(tokenKey, data.token);\n    return data.user;\n  },\n  async verify(uid, token) {\n    const data = await jsonOrThrow(await fetch(`${BASE}/auth/verify`, {\n      method: 'POST', headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ uid, token }),\n    }));\n    localStorage.setItem(tokenKey, data.token); // auto-login after verify\n    return data.user;\n  },\n  async resendVerification(email) {\n    return jsonOrThrow(await fetch(`${BASE}/auth/resend-verification`, {\n      method: 'POST', headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email }),\n    }));\n  },\n  async requestPasswordReset(email) {\n    return jsonOrThrow(await fetch(`${BASE}/auth/request-password-reset`, {\n      method: 'POST', headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ email }),\n    }));\n  },\n  async resetPassword(uid, token, password) {\n    return jsonOrThrow(await fetch(`${BASE}/auth/reset-password`, {\n      method: 'POST', headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify({ uid, token, password }),\n    }));\n  },\n  logout() { localStorage.removeItem(tokenKey); },\n  token() { return localStorage.getItem(tokenKey); },\n};\n\n// Google login (ONLY when 'google' \u2208 config.auth.methods \u2014 never generate\n// this button otherwise; the platform refuses unlisted methods server-side).\n// Redirects to the central Agentful OAuth broker; after Google consent the\n// broker 302s back to `redirect` with the app JWT in the URL FRAGMENT:\n//   https://<your-app>/#token=<jwt>&provider=google   (or #auth_error=<code>)\nexport const googleAuth = {\n  start(redirect = location.origin + '/') {\n    const url = new URL('https://api.agentful.dev/auth/oauth/google/start');\n    url.searchParams.set('project_id', PROJECT_ID);\n    url.searchParams.set('redirect', redirect); // must be THIS app's https origin\n    location.href = url.toString();\n  },\n};\n\n// REQUIRED whenever the Google button is generated: pick up the broker return\n// on app load (fragment token \u2192 login; auth_error \u2192 user-visible message).\nexport function handleGoogleReturn() {\n  const h = new URLSearchParams(location.hash.slice(1));\n  const token = h.get('token'), err = h.get('auth_error');\n  if (!token && !err) return null;\n  history.replaceState(null, '', location.pathname + location.search); // strip token from URL\n  if (err) return { ok: false, error: err }; // e.g. auth_method_not_allowed, oauth_failed\n  localStorage.setItem(tokenKey, token);\n  return { ok: true, provider: h.get('provider') || 'google' };\n}\n\n// REQUIRED in every app with auth: handle the mail links on app load.\n// Call once at startup (before router init is fine).\nexport async function handleAuthMailAction() {\n  const p = new URLSearchParams(location.search);\n  const action = p.get('ta_action'), uid = p.get('uid'), token = p.get('token');\n  if (!action || !uid || !token) return null;\n  history.replaceState(null, '', location.pathname); // strip token from URL\n  if (action === 'verify') {\n    try { const user = await auth.verify(uid, token); return { action, ok: true, user }; }\n    catch (e) { return { action, ok: false, error: e.code || 'invalid_token' }; }\n  }\n  if (action === 'reset') return { action, ok: true, uid, token }; // show new-password form, then auth.resetPassword(uid, token, pw)\n  return null;\n}\n\nexport const data = {\n  async list(collection, opts = {}) {\n    const qs = new URLSearchParams(opts).toString();\n    return jsonOrThrow(await fetch(`${BASE}/data/${collection}${qs ? '?' + qs : ''}`, {\n      headers: { ...authHeader() },\n    }));\n  },\n  async get(collection, docId) {\n    return jsonOrThrow(await fetch(`${BASE}/data/${collection}/${docId}`, {\n      headers: { ...authHeader() },\n    }));\n  },\n  async create(collection, data) {\n    return jsonOrThrow(await fetch(`${BASE}/data/${collection}`, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json', ...authHeader() },\n      body: JSON.stringify({ data }),\n    }));\n  },\n  async update(collection, docId, data) {\n    return jsonOrThrow(await fetch(`${BASE}/data/${collection}/${docId}`, {\n      method: 'PUT',\n      headers: { 'Content-Type': 'application/json', ...authHeader() },\n      body: JSON.stringify({ data }),\n    }));\n  },\n  async remove(collection, docId) {\n    return jsonOrThrow(await fetch(`${BASE}/data/${collection}/${docId}`, {\n      method: 'DELETE',\n      headers: { ...authHeader() },\n    }));\n  },\n};\n```\n\n### React / Vue / Svelte\n\nUse the same `data.js` / `data.ts` module above; wrap in framework-native state primitives.\n\n- **React:** call from `useEffect` for reads, `useState` for results; surface `err.code`/`err.correlation_id` to the user when caught. Do not put data calls in render bodies.\n- **Vue:** use `onMounted` for reads and a `ref()` for results; same error surfacing.\n- **Svelte / SvelteKit:** call from `onMount` (or a `load` function in SvelteKit); SvelteKit static-adapter projects must NOT use server `load` (no Node runtime in static deploy).\n- **Astro:** call only from client-side islands; no server fetch (static-only build).\n\n### TypeScript types\n\nGenerate the per-collection type from the preamble's field list:\n\n```ts\n// Example for a collection with fields: title:string*, done:boolean\ntype Todo = { title: string; done?: boolean };\n\n// And response wrappers:\ntype DataDoc<T> = { doc_id: string; collection: string; data: T; created_at: string };\ntype DataList<T> = { documents: DataDoc<T>[]; count: number; cursor?: string };\n```\n\n## Anti-patterns\n\n- \u274C `try { await data.create(...) } catch { /* ignore */ }` \u2014 masks failures.\n- \u274C Hardcoding `doc_id` for \"convenience\" \u2014 causes `already_exists` 409 on retry.\n- \u274C Writing to a collection name that doesn't appear in the preamble \u2014 `not_found` 404.\n- \u274C Using the schema endpoint `/data/_collections` from client code \u2014 owner-only, end-users get 403.\n- \u274C Storing the JWT anywhere other than `localStorage` under a project-scoped key; do not put it in cookies (CORS) or in `sessionStorage` (lost on tab close).\n- \u274C Telling the user \"the database is down\" because of a 5xx. Surface the `correlation_id` and stop.\n- \u274C Surfacing `correlation_id` on transient errors (`quota_exceeded`, `transient_storage_error`) before the doctor's `retry_with_backoff` budget is exhausted. The whole point is the user sees nothing while the retry loop is in play; only escalate after all `max_attempts` fail.\n\n## Diagnostic delegation\n\nIf you hit a 5xx that doesn't map to a retry-able 4xx in the table above, do not diagnose yourself. Delegate to `@agentful-managed-db-doctor` (added in PR 1.3) with the `correlation_id` from the response. The doctor has constrained tools and cannot fabricate platform internals.\n\n---\n\n## Managed Actions (only when `server.mode == managed`)\n\nManaged Actions are small Node.js functions the platform runs for the project at `/api/p/{PROJECT_ID}/actions/{name}`. Use them when a frontend operation needs (a) a secret API key, (b) a non-public/secured external API, or (c) server-enforced trust (price computation, signature verification, admin actions). For pure CRUD against the managed DB, use the data API directly; do NOT route everything through an action.\n\n### Hard rules (Managed Actions)\n\n1. **Upsert FIRST, fetch SECOND.** If your generated code calls `fetch('/api/p/.../actions/{name}')`, you MUST upsert the action via the CLI BEFORE writing the fetch call. An undeployed action returns `404 action_not_found`; the preamble's `Managed actions` list is the ground truth for what exists.\n2. **Only `ctx.fetch`, `ctx.data`, `ctx.secrets`, `ctx.user`, `ctx.body` and approved npm packages.** No `require('fs')`, `require('child_process')`, `require('http')`, `require('https')`, `require('net')`, `require('os')`, `require('path')`, `require('process')`, `require('vm')`, `require('cluster')`, `require('worker_threads')`. The validator rejects these at upload time with `{code: 'action_validation_failed', reason: 'disallowed_require'}`.\n3. **Secrets are read with `await ctx.secrets.get('<name>')` \u2014 never property access.** `ctx.secrets` has exactly one method, `get(key)`. `ctx.secrets.SOME_KEY` is silently `undefined`. Secret names must match `^(database|server)\\.[a-z][a-z0-9_]{0,126}$` \u2014 use `server.stripe_secret_key`, not `STRIPE_SECRET_KEY` (uppercase, unprefixed names cannot even be stored in Backend \u2192 Secrets).\n4. **Actions are publicly invokable \u2014 authorize the caller yourself.** `ctx.user` is the JWT-verified end-user (`{ id, email, pid }`) or `null`. Any action that touches a secret, writes data, or returns non-public information must start with a `ctx.user` check; nothing else gates who can call it.\n5. **Outbound calls from inside an action must use `ctx.fetch`**, not a bare `fetch`. `ctx.fetch` injects `X-Action-Depth` on self-action URLs so the platform's loop detector can break runaway recursion. External URLs are passed through unchanged.\n6. **Cost shape.** 5 s timeout, 256 MB RAM, 1 MB request body, per-project concurrent invocations capped at 10. Plan for `429 concurrency_exceeded` under load and surface it to the user gracefully (e.g. retry with backoff or \"try again in a moment\").\n\n### Action shape\n\n```js\n// .server/actions/checkout.js\nmodule.exports = async function (ctx) {\n  // ctx.body    \u2014 parsed JSON request body\n  // ctx.user    \u2014 JWT-verified end-user { id, email, pid }, or null if not logged in\n  // ctx.data    \u2014 same CRUD surface as the public data API, scoped to this project\n  // ctx.secrets \u2014 async accessor for Backend \u2192 Secrets: await ctx.secrets.get('server.stripe_secret_key')\n  // ctx.fetch   \u2014 depth-aware fetch wrapper\n  if (!ctx.user) return { error: 'auth_required' };\n  const apiKey = await ctx.secrets.get('server.stripe_secret_key');\n  if (!apiKey) return { error: 'missing_server_secret' };\n  const stripeRes = await ctx.fetch('https://api.stripe.com/v1/checkout/sessions', {\n    method: 'POST',\n    headers: {\n      Authorization: `Bearer ${apiKey}`,\n      'Content-Type': 'application/x-www-form-urlencoded',\n    },\n    body: new URLSearchParams({ /* \u2026 */ }).toString(),\n  });\n  const session = await stripeRes.json();\n  return { url: session.url };\n};\n```\n\n### Authoring protocol (engine flow)\n\n1. Read the preamble's `Managed actions` block. If your target name is already deployed with the right shape, skip to step 3.\n2. **Upsert:** write the action source to a local temp file, then `agentful-managed-actions upsert <project_id> <name> <file_path>`. The validator runs on both the public PUT-files path and this CLI; same rejection rules.\n3. Write the frontend `fetch('/api/p/<project_id>/actions/<name>', { method: 'POST', body: JSON.stringify(payload) })`. Include `Content-Type: application/json` on POSTs.\n4. Test once with `agentful-managed-actions invoke <project_id> <name> --body '{\"\u2026\":\"\u2026\"}'` to confirm the deployment landed.\n\n### Action-invocation error codes (response body)\n\n| `error.code` | HTTP | What it means | What to do |\n|---|---|---|---|\n| `action_not_found` | 404 | The action with that name doesn't exist | Upsert it first. |\n| `action_validation_failed` | 400 | Validator rejected the source (size, filename, disallowed require) | Fix per `reason` field; do not retry. |\n| `concurrency_exceeded` | 429 | Per-project cap reached | Backoff + retry, or surface to user. |\n| `action_loop_detected` | 508 | `X-Action-Depth >= 5` \u2014 too many self-calls in a chain | Refactor; you cannot self-recurse beyond depth 5. |\n| `timeout` | 408 | Action exceeded 5 s | Move heavy work out of the action or break into smaller calls. |\n| `body_too_large` | 413 | Request body > 1 MB | Trim the payload. |\n| `action_too_large` | 413 | Action source file > 256 KB | Split into multiple actions. |\n| `runtime_error` | 500 | Action threw at runtime | Read the message; common causes are unhandled rejections, missing `await`, or accessing undefined ctx fields. |\n\n### Anti-patterns\n\n- \u274C Putting a Stripe / OpenAI / Resend API key in frontend code. It must live in `ctx.secrets`.\n- \u274C `ctx.secrets.STRIPE_SECRET_KEY` (property access). The secrets API is `await ctx.secrets.get('server.stripe_secret_key')`; property access is silently `undefined`, and uppercase/unprefixed names cannot be stored at all.\n- \u274C `ctx.user.sub`. The verified user object is `{ id, email, pid }` \u2014 the JWT `sub` claim arrives as `ctx.user.id`.\n- \u274C An action that reads secrets or writes data without checking `ctx.user` first. Actions are publicly invokable; your check is the only authorization.\n- \u274C Calling `fetch('/api/p/.../actions/foo')` without first running `agentful-managed-actions upsert`. Will return 404.\n- \u274C Recursive actions calling themselves to \"spread work\". Will trip the depth guard at 5.\n- \u274C Using bare `fetch` instead of `ctx.fetch` from inside an action. The depth header won't propagate; you bypass the loop guard.\n- \u274C Naming actions `Hello.js`, `_internal.js`, or `actions/sub/foo.js`. The validator rejects (uppercase, leading underscore, subdirectory).\n- \u274C Hardcoding the API base URL into the action's `ctx.fetch` calls to other actions. Use a relative path or the project's own API origin.\n\n### `ctx.data` Is Privileged \u2014 It Bypasses `access_rule`\n\n`ctx.data` inside an action talks to the database **directly, with no\n`access_rule` enforcement**. It is a project-scoped, owner-level surface \u2014 the\nopposite of the `/data/*` end-user route:\n\n- It reads and writes **every** document in **every** collection, regardless of\n  whether that collection is `owner`, `authenticated`, or `public`.\n- It does **not** check `created_by`. An action can read one user's `owner`\n  docs and write into another user's.\n- Documents created via `ctx.data.create` are attributed `created_by: \"action\"`,\n  never to an end-user. If you need owner attribution, store the owner's id in\n  the document `data` yourself (e.g. `{ user_id: ctx.user.id, ... }`) and\n  filter on it.\n- `ctx.data.list(collection, { limit })` returns a **plain array** of docs\n  (`[{ doc_id, data, created_by, created_at }]`, NOT `{ documents: [...] }`),\n  caps at 100, and does **no server-side filtering** \u2014 you filter in JS. For\n  data sets that can exceed 100 rows, store an explicit owner/lookup field and\n  design around the cap; do not assume `list` returns everything.\n\nThis is the intended mechanism for trusted/admin work. The trade-off: an action\nis only as safe as its own checks. **Always verify `ctx.user` before any\ncross-user read or write.**\n\n### RBAC & Secure Role Assignment (`owner` + Action)\n\nThe managed DB has **no role concept and no field-level validation**. On the\nend-user `/data/*` route the client controls the entire document body \u2014\nincluding any `role` field. Design around two facts:\n\n1. **Privilege escalation is possible by default.** If a `profiles` collection\n   is `authenticated` or `owner`, a client can register and POST\n   `{ role: \"admin\" }` for themselves. `owner` does NOT stop this \u2014 the user\n   owns their own profile.\n2. **`owner` blocks admins too.** An `owner` collection correctly hides a\n   client's data from other clients, but an admin also cannot read it over\n   `/data/*`. Admin access must go through an action using `ctx.data`.\n\nSecure pattern \u2014 keep `role` server-owned and gate every change behind an\naction that verifies the **caller** is already an admin:\n\n```js\n// .server/actions/set-role.js  \u2014 upsert BEFORE calling it from the client\nmodule.exports = async function (ctx) {\n  if (!ctx.user) return { error: 'auth_required' };\n  // 1. Verify the CALLER is an admin (ctx.data ignores access_rule, so this\n  //    works even though `profiles` is `owner`).\n  const all = await ctx.data.list('profiles', { limit: 100 });\n  const me = all.find(d => d.data.user_id === ctx.user.id);\n  if (!me || me.data.role !== 'admin') return { error: 'forbidden' };\n  // 2. Validate input, then apply to the target.\n  const { target_user_id, role } = ctx.body || {};\n  if (!['admin', 'member', 'client'].includes(role)) return { error: 'bad_role' };\n  const target = all.find(d => d.data.user_id === target_user_id);\n  if (!target) return { error: 'not_found' };\n  await ctx.data.update('profiles', target.doc_id, { ...target.data, role });\n  return { ok: true };\n};\n```\n\nRules for this pattern:\n\n- The client UI must **never** write the `role` field over `/data/*`. On\n  self-registration, create the profile without `role` (or force a non-privileged\n  default in the action) \u2014 never trust a client-sent role.\n- \"Owner OR admin\" **reads** (an admin viewing any client's invoices) use the\n  same shape: keep the collection `owner`, expose admin access through an action\n  that verifies `ctx.user` is an admin, then uses `ctx.data` to fetch across users.\n- **Bootstrapping the first admin:** see **First Admin \u2014 mode-correct\n  protocol** below. Never invent a client-reachable route for it.\n- The 100-row `ctx.data.list` cap applies: if `profiles` can exceed 100 rows,\n  this scan-in-JS lookup is unreliable. Until server-side filtering exists,\n  store role lookups in a bounded collection or key admins by a known id set.\n\n## First Admin \u2014 mode-correct protocol\n\nWhen the app needs an admin (dashboard, moderation, `admin`-ruled collections),\nask the builder **\"How should the first admin account be created?\"** and offer\nONLY these options \u2014 they map to the platform's `_users.role` system\n(`user`/`admin`), which is what the `admin` access rule checks:\n\n1. **Fixed admin email (recommended).** Ask the builder for the address, then\n   run:\n   ```\n   agentful-auth-config set $PROJECT_ID '{\"admin_email\":\"chef@firma.de\"}'\n   ```\n   Whoever registers (or later logs in) with exactly that address is promoted\n   to `role: admin` **server-side, only after email verification** \u2014 no code\n   needed in the app.\n2. **Manual via Data Manager.** The builder opens **Backend \u2192 Data Manager \u2192\n   `_users` tab**, selects the registered user and sets the `role` dropdown to\n   `admin` (the `verified` flag can also be set there if a mail never arrived).\n\n### `agentful-auth-config` CLI\n\n- `agentful-auth-config get $PROJECT_ID` \u2014 current `config.auth` state\n  (`auth: null` = hardened pipeline not activated yet \u2192 registering works\n  legacy-style without verification) plus `email_infrastructure`\n  (`\"\"` = builder has not chosen one; verification mails will fail with\n  `email_infra_unconfigured` until they pick one in project settings).\n- `agentful-auth-config set $PROJECT_ID '<json>'` \u2014 merge into `config.auth`.\n  Keys: `methods` (subset of `email|google|oidc`; the server clamps against\n  the org allowlist \u2014 verify the result in the response), `require_verified_login`\n  (bool; default true once auth is configured), `admin_email`, `language`\n  (`de`|`en`, auth-mail language).\n- Setting ANY key activates the hardened pipeline (verification mails +\n  verified-login gate). Before activating it, run `get` and make sure\n  `email_infrastructure` is not empty \u2014 otherwise tell the builder to choose\n  Agentful Email or BYO in project settings first.\n- Email infrastructure is NOT settable via this CLI by design (audited\n  builder decision, DE-data-region notice).\n\n**NEVER offer \"run SQL\" / \"insert into the database manually\" for\n`database.mode == managed` \u2014 there is no SQL surface; the managed DB is not a\nSQL database.** SQL-based instructions apply only to BYO-Supabase projects\n(different skill, different mode).\n\nPrefer the platform `_users.role` + `admin` access rule over inventing an\napp-level `profiles.role` system when the requirement is just \"one admin can\nsee/manage everything\" \u2014 the profiles-RBAC pattern above is for MULTI-role\napps (admin/member/client) that need roles beyond `user`/`admin`.\n",
     "nextjs-scaffold": '---\nname: nextjs-scaffold\ndescription: Next.js 15 static export scaffold with React 19, TypeScript, and Tailwind CSS v4 generated manually without create-next-app. Use only for explicit Next.js requests or justified static export app needs.\n---\n\n# Next.js Scaffold\n\n## Stack Briefing\n\nNext.js 15 **static export** (`output: \'export\'`) + React 19 + TypeScript +\nTailwind v4, written manually (never `create-next-app`). Static export only \u2014\nno server actions, API routes, dynamic server rendering, or image optimization\ndependency. Build produces `out/` (not `dist/`). Use only for explicit Next or\njustified static multi-page React needs.\n\n## When To Use\n\nUse this skill when `selected_stack` is Next.js. Prefer Next.js only when the user explicitly asks for Next.js, asks for Next-specific features, or needs a React app architecture with static export and file-based routing.\n\nDo not use Next.js for a simple landing page or portfolio unless requested.\n\n## When Not To Use\n\n- Simple landing pages/portfolios \u2192 `vanilla-scaffold`.\n- General React app UI without Next-specific needs \u2192 `react-scaffold`.\n- Anything needing server actions, API routes, or SSR \u2014 unsupported here.\n\n## HARD STOP: Never Re-Scaffold An Existing App\n\nBefore writing ANY scaffold file, check the workspace. If `package.json` (or\nan existing `index.html` app shell for vanilla projects) and source files\nalready exist, this project already has an app \u2014 scaffolding is DONE and this\nskill must not overwrite it. Read the existing entry points and source tree\nfirst, then build ON TOP of the existing files: keep the entry points,\nrouting, and dependency choices already in place. Overwriting the scaffold\nfiles on an existing project destroys the user\'s app (this happened in\nproduction). If the existing code seems inconsistent with the request, ask\nthe user \u2014 never replace silently.\n\n## Required File Shape\n\nThis is the shape a Next.js project has here. Depending on how the project\nstarted, these files may already exist in the workspace \u2014 check first:\n\n```text\npackage.json        build = `next build`; `npm run verify` runs the full gate\nnext.config.ts      output: \'export\', trailingSlash, images.unoptimized\ntsconfig.json       paths "@/*" -> ./src/*\neslint.config.mjs   the only ESLint config in the project\npostcss.config.mjs\nnext-env.d.ts\npublic/\n  favicon.svg       keep it \u2014 without a favicon every page logs a 404\nsrc/\n  app/\n    layout.tsx      owns <html>/<body> and the metadata\n    page.tsx        the root route: this IS the landing page\n    globals.css     THE global stylesheet \u2014 Tailwind by default\n.gitignore\n```\n\n**Empty workspace** \u2014 create exactly this shape.\n\n**Files already present** \u2014 **edit them, do not recreate them.** A project\nfrom `create-next-app` is close to this already; the usual gaps are the\n`Create Next App` metadata in `layout.tsx`, the demo SVGs in `public/`, and\nan `app/` directory at the root instead of under `src/`.\n\nThe build output is `out/`, not `dist/` \u2014 that is expected and the platform\naccepts it. Do not rename it.\n\nDo not use `next/font/google` by default because it can add build-time network dependency. Use system fonts unless the user explicitly requests custom fonts.\n\n## package.json\n\n```json\n{\n  "name": "project-name",\n  "private": true,\n  "version": "0.1.0",\n  "scripts": {\n    "dev": "next dev",\n    "build": "next build",\n    "start": "next start",\n    "verify": "tsc --noEmit && eslint . --max-warnings 0 && next build"\n  },\n  "dependencies": {\n    "next": "16.2.9",\n    "react": "19.2.4",\n    "react-dom": "19.2.4"\n  },\n  "devDependencies": {\n    "@tailwindcss/postcss": "^4",\n    "@types/node": "^20",\n    "@types/react": "^19",\n    "@types/react-dom": "^19",\n    "eslint": "^9",\n    "eslint-config-next": "16.2.9",\n    "tailwindcss": "^4",\n    "typescript": "^5"\n  }\n}\n```\n\n## next.config.ts\n\n```ts\nimport type { NextConfig } from \'next\'\n\nconst nextConfig: NextConfig = {\n  // Static export \u2014 the platform serves files, there is no Next.js server.\n  output: \'export\',\n  // Emits `about/index.html` instead of `about.html`, which a plain static\n  // host can resolve without rewrite rules.\n  trailingSlash: true,\n  // next/image needs a server to optimise; without this the export fails.\n  images: {\n    unoptimized: true,\n  },\n}\n\nexport default nextConfig\n```\n\n## postcss.config.mjs\n\n```js\nconst config = {\n  plugins: {\n    \'@tailwindcss/postcss\': {},\n  },\n}\n\nexport default config\n```\n\n## App Files\n\n`src/app/layout.tsx`:\n\n```tsx\nimport type { Metadata } from \'next\'\nimport \'./globals.css\'\n\nexport const metadata: Metadata = {\n  title: \'Replace this title\',\n  description: \'Replace this with a one-sentence description of the site.\',\n  icons: { icon: \'/favicon.svg\' },\n}\n\nexport default function RootLayout({\n  children,\n}: Readonly<{\n  children: React.ReactNode\n}>) {\n  return (\n    <html lang="en" className="h-full antialiased">\n      <body className="min-h-full flex flex-col">{children}</body>\n    </html>\n  )\n}\n```\n\n`src/app/globals.css`:\n\n```css\n@import "tailwindcss";\n\n/* Design tokens. Tailwind v4 turns every entry here into a utility\n   (--color-brand -> bg-brand/text-brand), so restyle the project by editing\n   these values rather than sprinkling hex codes through the components. */\n@theme {\n  --color-brand: #0070f3;\n  --color-brand-contrast: #ffffff;\n  --color-surface: #ffffff;\n  --color-surface-muted: #f5f5f7;\n  --color-ink: #111827;\n  --color-ink-muted: #6b7280;\n  --radius-card: 0.75rem;\n}\n\n:root {\n  color-scheme: light;\n  font-family: Inter, ui-sans-serif, system-ui, sans-serif;\n  --app-bg: #ffffff;\n  --app-fg: #111827;\n}\n\n/* An opaque background on html, body is mandatory \u2014 the page is never\n   transparent. Keep this rule when you restyle. */\nhtml, body {\n  margin: 0;\n  min-height: 100%;\n  min-width: 320px;\n  background: var(--app-bg);\n  color: var(--app-fg);\n}\n\n/* Keyboard focus baseline. Components may override it, but never remove it:\n   the platform appends a generic fallback to any project whose CSS contains\n   no `:focus` rule at all, and a real one belongs here. */\n:focus-visible {\n  outline: 2px solid var(--color-brand, currentColor);\n  outline-offset: 2px;\n}\n```\n\n## TypeScript Config\n\n`tsconfig.json`:\n\n```json\n{\n  "compilerOptions": {\n    "target": "ES2017",\n    "lib": ["dom", "dom.iterable", "esnext"],\n    "allowJs": true,\n    "skipLibCheck": true,\n    "strict": true,\n    "noEmit": true,\n    "esModuleInterop": true,\n    "module": "esnext",\n    "moduleResolution": "bundler",\n    "resolveJsonModule": true,\n    "isolatedModules": true,\n    "jsx": "react-jsx",\n    "incremental": true,\n    "plugins": [{ "name": "next" }],\n    "paths": { "@/*": ["./src/*"] }\n  },\n  "include": [\n    "next-env.d.ts",\n    "**/*.ts",\n    "**/*.tsx",\n    "**/*.mts",\n    ".next/types/**/*.ts",\n    ".next/dev/types/**/*.ts"\n  ],\n  "exclude": ["node_modules"]\n}\n```\n\n`next-env.d.ts`:\n\n```ts\n/// <reference types="next" />\n/// <reference types="next/image-types/global" />\n```\n\n## Routing Rules\n\nUse file-based routing under `src/app/` with static export. Do not add\n`middleware`, dynamic server routes, or `generateStaticParams` that depend on a\nserver. All routes must be statically renderable.\n\n## Data And Backend Rules\n\n- No API routes or server actions (static export forbids them). For data/auth,\n  use the platform backend via client `fetch()` \u2014 respect the STOP gate.\n- `images.unoptimized: true` is required; do not add the image optimization\n  server dependency.\n\n## Asset Path Rules\n\n- Keep output host-agnostic; reference the project\'s own assets/routes\n  relatively. Do not set an absolute `assetPrefix`/`basePath`. No `<base>` tag.\n\n## Common Failure Modes\n\n- Adding server actions/API routes \u2192 static export build fails.\n- Using `next/font/google` \u2192 build-time network dependency.\n- Renaming `out/` to `dist/` or adding postbuild move scripts.\n- Optimized `<Image>` without `unoptimized: true`.\n\n## ESLint Config\n\nEvery scaffold ships `eslint.config.mjs` (flat config) so the platform lint\ngate and the live ESLint diagnostics work from the very first turn. Next uses\n`eslint-config-next` rather than the hand-rolled rule set of `react-scaffold`\n\u2014 measured 2026-08-04, it covers strictly more:\n\n| canary | `eslint-config-next` |\n| --- | --- |\n| `useEffect(() => setV(item), [item])` | error \u2014 *"Calling setState synchronously within an effect"* (the react-scaffold class) |\n| `<img src="/x.png">` | error \u2014 `@next/next/no-img-element` (which the hand-rolled config never sees) |\n\n`eslint.config.mjs`:\n\n```js\nimport { defineConfig, globalIgnores } from "eslint/config";\nimport nextVitals from "eslint-config-next/core-web-vitals";\nimport nextTs from "eslint-config-next/typescript";\n\nconst eslintConfig = defineConfig([\n  ...nextVitals,\n  ...nextTs,\n  // Override default ignores of eslint-config-next.\n  globalIgnores([\n    // Default ignores of eslint-config-next:\n    ".next/**",\n    "out/**",\n    "build/**",\n    "next-env.d.ts",\n  ]),\n]);\n\nexport default eslintConfig;\n```\n\nThe platform runs `npx eslint . --max-warnings 0` before every build, so any\nviolation blocks the build. Do not add or remove rules, and never "fix" a\nviolation with `eslint-disable` or config edits \u2014 fix the code.\n\n## Verification\n\nRun install, then the full platform verification contract (see the build\nagent\'s "Build And Preview Rules"): typecheck, `npx eslint . --max-warnings 0`\n(the scaffold ships `eslint.config.mjs`, so this check ALWAYS applies and\ndecides acceptance), `npm run\nbuild`, and finally verify that `out/index.html` exists. Do not rename `out/`\nto `dist/`. `npm run build` alone is not what the platform gate checks \u2014 and\nNext\'s own build only surfaces lint when configured to. Never make the lint\nstep pass by disabling rules.\n',
     "react-scaffold": '---\nname: react-scaffold\ndescription: React 19 with Vite, TypeScript, and Tailwind CSS v4 scaffold generated manually without npm create. Use for app UIs, dashboards, auth flows, CRUD interfaces, or explicit React requests.\n---\n\n# React Scaffold\n\n## Stack Briefing\n\nReact 19 + Vite + TypeScript, written manually (never `npm create`), with\nTailwind v4 as the default styling layer. Use it for app-like UIs where\ncomponent state and interaction justify a framework. Output must stay\nstatic-hostable: `base: \'/\'`, history routing (clean URLs, no `#`), build to\n`dist/`. Do not over-split into dozens of trivial components \u2014 keep the tree\npragmatic and typed.\n\n## When To Use\n\nUse this skill when `selected_stack` is React. React is appropriate for app-like interfaces, dashboard/admin UIs, authenticated user flows, complex client state, CRUD screens, and explicit React requests.\n\nDo not use React just because the workspace is empty. Static marketing/content sites should usually use `vanilla-scaffold`.\n\n## When Not To Use\n\n- Static marketing/content/portfolio sites \u2192 `vanilla-scaffold`.\n- Content-heavy multi-page sites better served by Astro \u2192 `astro-scaffold`.\n- Anything requiring SSR/server rendering \u2014 output here is static export only.\n\n## HARD STOP: Never Re-Scaffold An Existing App\n\nBefore writing ANY scaffold file, check the workspace. If `package.json` and\n`src/` already exist, this project already has an app \u2014 scaffolding is DONE\nand this skill must not overwrite it. Read the existing `package.json`,\n`src/App.tsx` and the `src/` tree first, then build ON TOP of the existing\nfiles: keep the entry points, routing, and dependency choices already in\nplace. Overwriting `package.json`/`App.tsx`/`main.tsx` on an existing project\ndestroys the user\'s app (this happened in production). If the existing code\nseems inconsistent with the request, ask the user \u2014 never replace silently.\n\n**Rewriting a file must never drop an `import "./x.css"` it carried.** Nothing\ncatches it: tsc/eslint do not read CSS, an unimported stylesheet is legal so\nthe bundler is silent, and the page renders unstyled (prod 2026-08-01: 38 of\n85 class names left the bundle, all gates green). Prefer `edit` over a full\n`write`; if you rewrite, carry the original import block over.\n\n## Required File Shape\n\nThis is the shape a React project has here. Depending on how the project\nstarted, these files may already exist in the workspace \u2014 check first:\n\n```text\nindex.html          entry: favicon link, #root, module script\npackage.json        build = `vite build`; `npm run verify` runs the full gate\nvite.config.ts      base: \'/\', tailwindcss() + react()\ntsconfig.json       ONE flat config, include: ["src"]\neslint.config.mjs   the only ESLint config in the project\npublic/\n  favicon.svg       keep it \u2014 without a favicon every page logs a 404\nsrc/\n  App.tsx           placeholder shell: header/nav, hero, cards, footer\n  main.tsx          entry, imports ./index.css\n  index.css         THE stylesheet \u2014 Tailwind by default, see Styling\n  vite-env.d.ts\n.gitignore\n```\n\n**Empty workspace** \u2014 create exactly this shape.\n\n**Files already present** \u2014 **edit them, do not recreate them.** Rewrite the\ncopy, restyle the `@theme` tokens, add components and routes, but keep the\nshape. Each part of it prevents a defect that has shipped to real users.\n\n**A project that came from an older `create-vite` starter** carries config\nthat silently disables checks the platform believes it ran. Repair config\nonly \u2014 never a full-file `write` of `App.tsx`, `main.tsx` or `package.json`,\nand never as a pretext to re-scaffold:\n\n| found | do |\n| --- | --- |\n| `tsconfig.json` with `"files": []` + `references` | always replace with the one flat config below and delete `tsconfig.app.json`/`tsconfig.node.json` \u2014 otherwise nothing is type-checked at all |\n| `eslint.config.js` | leave it alone if it is the only config. If you need the rule set below, move its contents into `eslint.config.mjs` and **delete the `.js`** \u2014 never let both exist |\n| `src/App.css` | leave a working import alone. If you rewrite `App.tsx`, carry `import \'./App.css\'` over, or fold the rules into `index.css` in the same edit \u2014 never drop it silently |\n\nSay in your summary which of these you changed and why.\n\n### One Stylesheet, Not Two\n\n`src/index.css` is the only stylesheet. Do **not** add `src/App.css`.\n\nA second stylesheet has to be imported from a component, and that import is\nthe single most fragile line in the project: one full-file `write` of\n`App.tsx` drops it, and nothing notices (prod `0njsblk0lye2vsx`, 2026-08-01 \u2014\nthe layout stylesheet left the bundle, every gate stayed green). With one\nstylesheet imported once from `main.tsx`, the failure has nowhere to happen.\n\nPut component styles wherever the chosen approach puts them \u2014 Tailwind\nclasses by default \u2014 and shared values in `index.css`.\n\n## package.json\n\n```json\n{\n  "name": "project-name",\n  "private": true,\n  "version": "0.1.0",\n  "type": "module",\n  "scripts": {\n    "dev": "vite",\n    "build": "vite build",\n    "preview": "vite preview",\n    "verify": "tsc --noEmit && eslint . --max-warnings 0 && vite build"\n  },\n  "dependencies": {\n    "react": "^19.0.0",\n    "react-dom": "^19.0.0"\n  },\n  "devDependencies": {\n    "@tailwindcss/vite": "^4.0.0",\n    "@types/react": "^19.0.0",\n    "@types/react-dom": "^19.0.0",\n    "@vitejs/plugin-react": "^4.3.4",\n    "eslint": "^9.0.0",\n    "eslint-plugin-react-hooks": "^6.0.0",\n    "tailwindcss": "^4.0.0",\n    "typescript": "^5.0.0",\n    "typescript-eslint": "^8.0.0",\n    "vite": "^6.0.0"\n  }\n}\n```\n\n`build` is `vite build` alone \u2014 no `tsc` in front of it. The platform runs the\ntype check itself before the build, and a `tsc` inside the build script also\nblocks the one-time build that runs when a starter is imported. `verify` is\nthe gate in one command; run it, not just `npm run build`.\n\n## vite.config.ts\n\n```ts\nimport { defineConfig } from \'vite\'\nimport react from \'@vitejs/plugin-react\'\nimport tailwindcss from \'@tailwindcss/vite\'\n\nexport default defineConfig({\n  base: \'/\',\n  plugins: [tailwindcss(), react()],\n})\n```\n\n## Entry Files\n\n`index.html`:\n\n```html\n<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="UTF-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1.0" />\n    <meta name="description" content="Replace this with a one-sentence description of the app." />\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />\n    <title>Replace this title</title>\n  </head>\n  <body>\n    <div id="root"></div>\n    <script type="module" src="./src/main.tsx"></script>\n  </body>\n</html>\n```\n\nKeep the favicon link and keep `public/favicon.svg`. Without them the browser\nrequests `/favicon.ico` on every page load and the render check records a\nfailed request on an otherwise healthy project.\n\n`src/main.tsx`:\n\n```tsx\nimport React from \'react\'\nimport ReactDOM from \'react-dom/client\'\nimport App from \'./App\'\nimport \'./index.css\'\n\nReactDOM.createRoot(document.getElementById(\'root\')!).render(\n  <React.StrictMode>\n    <App />\n  </React.StrictMode>,\n)\n```\n\n`src/index.css` as the starter ships it \u2014 Tailwind first, then tokens, then\nthe opaque page baseline:\n\n```css\n@import "tailwindcss";\n\n/* Design tokens. Tailwind v4 turns every entry here into a utility\n   (--color-brand -> bg-brand/text-brand), so restyle the project by editing\n   these values rather than sprinkling hex codes through the components. */\n@theme {\n  --color-brand: #4f46e5;\n  --color-brand-contrast: #ffffff;\n  --color-surface: #ffffff;\n  --color-surface-muted: #f5f5f7;\n  --color-ink: #111827;\n  --color-ink-muted: #6b7280;\n  --radius-card: 0.75rem;\n}\n\n:root {\n  color-scheme: light;\n  font-family: Inter, ui-sans-serif, system-ui, sans-serif;\n  --app-bg: #ffffff;\n  --app-fg: #111827;\n}\n\n/* An opaque background on html, body is mandatory \u2014 the page is never\n   transparent. Keep this rule when you restyle. */\nhtml, body {\n  margin: 0;\n  min-height: 100%;\n  min-width: 320px;\n  background: var(--app-bg);\n  color: var(--app-fg);\n}\n\n/* Keyboard focus baseline. Components may override it, but never remove it:\n   the platform appends a generic fallback to any project whose CSS contains\n   no `:focus` rule at all, and a real one belongs here. */\n:focus-visible {\n  outline: 2px solid var(--color-brand, currentColor);\n  outline-offset: 2px;\n}\n```\n\nEvery `@theme` entry becomes a utility (`--color-brand` \u2192 `bg-brand`), so\nrestyle by editing tokens instead of scattering hex codes through components.\nIf the user chose a non-Tailwind approach, keep `:root` and the `html, body`\nrule and replace the rest \u2014 the opaque background is not optional.\n\n`src/vite-env.d.ts`:\n\n```ts\n/// <reference types="vite/client" />\n```\n\n## TypeScript Config\n\nOne flat `tsconfig.json` with `include`, no project references and no\n`tsconfig.app.json`/`tsconfig.node.json`.\n\nThis is not a style preference. The platform gate runs `tsc --noEmit` against\nthe root `tsconfig.json`. A `create-vite`-style root \u2014 `"files": []` plus\n`references` \u2014 makes that command compile **zero files**: it exits 0 on a\nproject full of type errors, and the gate reports a pass it never performed.\nMeasured 2026-08-04: a deliberate type error passes the referenced shape and\nfails the flat one. `vite.config.ts` is deliberately not type-checked.\n\n`tsconfig.json`:\n\n```json\n{\n  "compilerOptions": {\n    "target": "ES2020",\n    "useDefineForClassFields": true,\n    "lib": ["ES2020", "DOM", "DOM.Iterable"],\n    "module": "ESNext",\n    "skipLibCheck": true,\n    "moduleResolution": "bundler",\n    "allowImportingTsExtensions": true,\n    "resolveJsonModule": true,\n    "isolatedModules": true,\n    "noEmit": true,\n    "jsx": "react-jsx",\n    "strict": true\n  },\n  "include": ["src"]\n}\n```\n\n## ESLint Config\n\nEvery scaffold ships **exactly one** ESLint config, `eslint.config.mjs` (flat\nconfig), so the platform lint gate and the live ESLint diagnostics work from\nthe first turn. Keep it exactly this minimal \u2014 correctness rules only, no\nstylistic rules, nothing that fights Prettier:\n\n`eslint.config.mjs`:\n\n```js\nimport tseslint from \'typescript-eslint\'\nimport reactHooks from \'eslint-plugin-react-hooks\'\n\nexport default tseslint.config(\n  { ignores: [\'dist\'] },\n  {\n    files: [\'**/*.{ts,tsx}\'],\n    extends: [tseslint.configs.base],\n    plugins: { \'react-hooks\': reactHooks },\n    rules: {\n      \'react-hooks/rules-of-hooks\': \'error\',\n      \'react-hooks/exhaustive-deps\': \'error\',\n      \'react-hooks/set-state-in-effect\': \'error\',\n      \'react-hooks/no-deriving-state-in-effects\': \'error\',\n      \'@typescript-eslint/no-unused-vars\': [\n        \'error\',\n        { argsIgnorePattern: \'^_\', varsIgnorePattern: \'^_\' },\n      ],\n    },\n  },\n)\n```\n\n**Never add a second config file.** ESLint resolves `eslint.config.js` before\n`eslint.config.mjs` and uses only the first one it finds, silently. A stray\n`.js` next to the `.mjs` therefore disables every rule above without a\nwarning \u2014 measured on ESLint 9: a violation that fails with the `.mjs` alone\npasses when both files exist. So in an existing project, either keep its\n`eslint.config.js` as the single config, or migrate it into\n`eslint.config.mjs` and delete the `.js` \u2014 never leave both behind.\n\nThe platform runs `npx eslint . --max-warnings 0` before every build, so any\nviolation blocks the build. Do not add rules, do not remove rules, and never\n"fix" a violation with `eslint-disable` or config edits \u2014 fix the code (see\nthe hooks patterns below).\n\n## Allowed Complexity\n\n- Add `src/components/`, `src/pages/`, `src/lib/`, `src/hooks/` only when a\n  feature needs them \u2014 do not scaffold empty folders.\n- Introduce state libraries or data-fetching only when real shared state or\n  server data exists; local `useState`/`useReducer` covers most cases.\n- Keep components typed (props/return types); avoid `any`.\n\n## CSS And Styling Expectations\n\nThe starter ships Tailwind v4 via `@tailwindcss/vite`, and that is the\ndefault: keep it and tokenize theme values in `@theme`.\n\n**The user\'s request wins.** If they ask for a different styling approach,\nfollow them and adjust the setup in the same turn:\n\n- **shadcn/ui** \u2014 is built ON Tailwind. Keep Tailwind, add the components.\n  Never remove Tailwind to "make room" for it.\n- **A CSS-in-JS library** (Chakra, MUI, styled-components, Emotion) \u2014 add it\n  and build with it. Leaving Tailwind installed is harmless (v4 emits only\n  the classes you use), so remove it only if the user asks.\n- **Plain CSS / CSS Modules** \u2014 drop `@tailwindcss/vite` and `tailwindcss`\n  from `package.json`, remove the plugin from `vite.config.ts`, and replace\n  `@import "tailwindcss"` in `index.css` with your own base styles. Keep the\n  `:root` tokens and the opaque `html, body` rule.\n\nWhatever the approach, these hold:\n\n- **One stylesheet** \u2014 the rule below is about losing an import, not about\n  Tailwind. It applies to plain CSS just as much.\n- Mobile-first, responsive layouts; visible focus states; WCAG AA contrast.\n- The loaded `style-*` skill governs the visual language \u2014 apply its recipe.\n  It is written to be independent of the styling technology.\n\n## Routing Rules\n\nIf adding React Router, use `BrowserRouter` (history mode) with `base: \'/\'` in\n`vite.config.ts`. The platform serves at the domain root and falls unknown\ndeep-links back to `index.html`, so routes resolve on hard refresh with clean\nURLs (no `#`). Never use `HashRouter`. Add `react-router-dom` only when routing\nis actually needed.\n\n## Data And Backend Rules\n\n- No database/server calls unless a backend is configured (respect the build\n  agent\'s STOP gate). Do not invent mock backends or fake data arrays.\n- Keep secrets out of client code; only public keys via `.env.local`.\n\n## Asset Path Rules\n\n- Set `base: \'/\'` in `vite.config.ts`. The platform serves the project at the\n  domain root, and history-mode routes need root-absolute assets.\n- Reference the project\'s own assets/routes with root-absolute paths (`/assets/...`);\n  no `<base>` tag, no hardcoded platform URLs.\n\n## Verification\n\nRun install, then the full platform verification contract (see the build\nagent\'s "Build And Preview Rules"), not just `npm run build`:\n\n1. `npx tsc --noEmit`\n2. `npx eslint . --max-warnings 0` \u2014 a project scaffolded from this skill\n   ships `eslint.config.mjs`, so this check ALWAYS applies and decides\n   acceptance.\n3. `npm run build`\n4. `dist/index.html` exists\n\n`npm run verify` runs 1\u20133 in order. Never make step 2 pass by disabling rules\nor adding `eslint-disable`.\n\n## React Hooks Rules That Fail The Gate\n\nThe scaffold\'s `eslint.config.mjs` enables `eslint-plugin-react-hooks` rules\nthat reject patterns which compile and build fine. These are the ones that\nactually show up \u2014 avoid them while writing, not after:\n\n- **Never sync props into state inside an effect**\n  (`useEffect(() => setForm(props.item), [props.item])` \u2192 `set-state-in-effect`).\n  Derive the value during render, lift the state up, or remount the subtree\n  with a `key` when the edited record changes \u2014 that is usually the intended\n  "reset the form" semantic anyway.\n- **Do not open dialogs/editors from an effect that watches the URL.** Derive\n  the open state from the route during render, or set it in the event handler\n  that triggered the navigation.\n- **Do not bootstrap an external store from a render-time side effect.** Read\n  it with `useSyncExternalStore`, or initialize it in the store module itself.\n- **Async loads:** only update state after an await when the effect has not\n  been cleaned up (cancellation flag or `AbortController`).\n- **No impure render calls** \u2014 no `Math.random()`, `Date.now()`, or mutation\n  during render. Move them into a lazy initializer or an event handler.\n- **Fast Refresh:** a module that exports a component must not also export\n  unrelated non-component values (`react-refresh/only-export-components`).\n\nA `setTimeout`/microtask wrapper that only hides the violation from the linter\nis not a fix \u2014 it hides the same bug behind a race.\n\n## Common Failure Modes\n\n- Recreating the starter\'s files instead of editing them.\n- Adding `src/App.css` (or any second stylesheet) \u2014 see "One Stylesheet".\n- Adding `eslint.config.js` beside `eslint.config.mjs`, which silently\n  disables the rule set.\n- Restoring the `create-vite` tsconfig trio, which makes the type check inert.\n- Putting `tsc` back into the `build` script.\n- Deleting `public/favicon.svg` or its `<link rel="icon">`.\n- Using `HashRouter` \u2192 ugly `#` URLs; use `BrowserRouter` (history mode).\n- Keeping relative `base: \'./\'` with history routing \u2192 assets 404 on a deep-link\n  hard refresh; use `base: \'/\'`.\n- Leaving the starter\'s placeholder copy ("Replace this headline", "Brand",\n  "First point") in the shipped page.\n- Over-splitting into trivial components; untyped `any` props.\n- Treating pre-install JSX type errors as source bugs (install deps first).\n',
     "vue-scaffold": '---\nname: vue-scaffold\ndescription: Vue 3.5 with Vite, TypeScript, and Tailwind CSS v4 scaffold generated manually without npm create. Use for explicit Vue requests or existing Vue projects.\n---\n\n# Vue Scaffold\n\n## Stack Briefing\n\nVue 3.5 + Vite + TypeScript + Tailwind v4, written manually (never `npm create`).\nUse it for app-like Vue UIs. Output must stay static-hostable: `base: \'/\'`,\nhistory mode (clean URLs, no `#`), build to `dist/`. Use the Composition API; add Pinia or Vue Router\nonly when real shared state or routing actually exists.\n\n## When To Use\n\nUse this skill when `selected_stack` is Vue. Prefer Vue only when requested, when the existing project uses Vue, or when the user clearly wants a Vue-style app.\n\n## When Not To Use\n\n- Static marketing/content/portfolio sites \u2192 `vanilla-scaffold`.\n- Content-heavy multi-page sites \u2192 `astro-scaffold`.\n- Anything needing SSR \u2014 output here is static only.\n\n## HARD STOP: Never Re-Scaffold An Existing App\n\nBefore writing ANY scaffold file, check the workspace. If `package.json` (or\nan existing `index.html` app shell for vanilla projects) and source files\nalready exist, this project already has an app \u2014 scaffolding is DONE and this\nskill must not overwrite it. Read the existing entry points and source tree\nfirst, then build ON TOP of the existing files: keep the entry points,\nrouting, and dependency choices already in place. Overwriting the scaffold\nfiles on an existing project destroys the user\'s app (this happened in\nproduction). If the existing code seems inconsistent with the request, ask\nthe user \u2014 never replace silently.\n\n## Required File Shape\n\nThis is the shape a Vue project has here. Depending on how the project\nstarted, these files may already exist in the workspace \u2014 check first:\n\n```text\nindex.html          entry: favicon link, #app, module script\npackage.json        build = `vite build`; `npm run verify` runs the full gate\nvite.config.ts      base: \'/\', tailwindcss() + vue()\ntsconfig.json       ONE flat config, no references\neslint.config.mjs   the only ESLint config in the project\npublic/\n  favicon.svg       keep it \u2014 without a favicon every page logs a 404\nsrc/\n  App.vue           placeholder shell: header/nav, hero, cards, footer\n  main.ts           entry, imports ./style.css\n  style.css         THE stylesheet \u2014 Tailwind by default\n  env.d.ts          vite/client types (inside src/, so the include glob covers it)\n  shims-vue.d.ts    lets plain `tsc` resolve *.vue \u2014 see below, load-bearing\n.gitignore\n```\n\n**Empty workspace** \u2014 create exactly this shape.\n\n**Files already present** \u2014 **edit them, do not recreate them.** Rewrite the\ncopy, restyle the `@theme` tokens, add components and routes, but keep the\nshape.\n\n**A project from an older `create-vue` starter** ships config that silently\ndisables checks the platform believes it ran. Repair config only \u2014 never a\nfull-file `write` of `App.vue`, `main.ts` or `package.json`:\n\n| found | do |\n| --- | --- |\n| `tsconfig.json` with `"files": []` + `references` | replace with the flat config below, delete `tsconfig.app.json`/`tsconfig.node.json`, and add `src/shims-vue.d.ts` \u2014 the trio makes the type check inert, but removing it without the shim makes it fail |\n| no ESLint config at all | add `eslint.config.mjs` below \u2014 without it the lint gate is inert and never sees a template bug |\n| `src/router/index.ts` with `routes: []`, an unused store | delete them, or give them real routes/state |\n\nCreate `src/components/`, `src/views/`, `src/router/`, or `src/stores/` only when needed.\n\n## package.json\n\n```json\n{\n  "name": "project-name",\n  "private": true,\n  "version": "0.1.0",\n  "type": "module",\n  "scripts": {\n    "dev": "vite",\n    "build": "vite build",\n    "preview": "vite preview",\n    "verify": "vue-tsc --noEmit && eslint . --max-warnings 0 && vite build"\n  },\n  "dependencies": {\n    "vue": "^3.5.0"\n  },\n  "devDependencies": {\n    "@tailwindcss/vite": "^4.0.0",\n    "@vitejs/plugin-vue": "^6.0.0",\n    "eslint": "^9.0.0",\n    "eslint-plugin-vue": "^10.0.0",\n    "tailwindcss": "^4.0.0",\n    "typescript": "^5.0.0",\n    "typescript-eslint": "^8.0.0",\n    "vite": "^6.0.0",\n    "vue-tsc": "^2.2.0"\n  }\n}\n```\n\n## vite.config.ts\n\n```ts\nimport { defineConfig } from \'vite\'\nimport vue from \'@vitejs/plugin-vue\'\nimport tailwindcss from \'@tailwindcss/vite\'\n\nexport default defineConfig({\n  base: \'/\',\n  plugins: [tailwindcss(), vue()],\n})\n```\n\n## Entry Files\n\n`index.html`:\n\n```html\n<!doctype html>\n<html lang="en">\n  <head>\n    <meta charset="UTF-8" />\n    <meta name="viewport" content="width=device-width, initial-scale=1.0" />\n    <meta name="description" content="Replace this with a one-sentence description of the app." />\n    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />\n    <title>Replace this title</title>\n  </head>\n  <body>\n    <div id="app"></div>\n    <script type="module" src="./src/main.ts"></script>\n  </body>\n</html>\n```\n\n`src/main.ts`:\n\n```ts\nimport { createApp } from \'vue\'\nimport App from \'./App.vue\'\nimport \'./style.css\'\n\ncreateApp(App).mount(\'#app\')\n```\n\n`src/style.css`:\n\n```css\n@import "tailwindcss";\n\n/* Design tokens. Tailwind v4 turns every entry here into a utility\n   (--color-brand -> bg-brand/text-brand), so restyle the project by editing\n   these values rather than sprinkling hex codes through the components. */\n@theme {\n  --color-brand: #41b883;\n  --color-brand-contrast: #ffffff;\n  --color-surface: #ffffff;\n  --color-surface-muted: #f5f5f7;\n  --color-ink: #111827;\n  --color-ink-muted: #6b7280;\n  --radius-card: 0.75rem;\n}\n\n:root {\n  color-scheme: light;\n  font-family: Inter, ui-sans-serif, system-ui, sans-serif;\n  --app-bg: #ffffff;\n  --app-fg: #111827;\n}\n\n/* An opaque background on html, body is mandatory \u2014 the page is never\n   transparent. Keep this rule when you restyle. */\nhtml, body {\n  margin: 0;\n  min-height: 100%;\n  min-width: 320px;\n  background: var(--app-bg);\n  color: var(--app-fg);\n}\n\n/* Keyboard focus baseline. Components may override it, but never remove it:\n   the platform appends a generic fallback to any project whose CSS contains\n   no `:focus` rule at all, and a real one belongs here. */\n:focus-visible {\n  outline: 2px solid var(--color-brand, currentColor);\n  outline-offset: 2px;\n}\n```\n\nTailwind is the **default**, not a mandate \u2014 the same rule as elsewhere: if\nthe user asks for a different styling approach, follow them and adjust the\nsetup in the same turn. Vue SFC `<style scoped>` blocks are idiomatic and fine\nalongside it; the thing to avoid is a second global stylesheet imported from a\ncomponent, because one full-file rewrite drops that import silently.\n\n## TypeScript Config\n\nOne flat `tsconfig.json` with `include`, no project references and no\n`tsconfig.app.json`/`tsconfig.node.json`.\n\nThis is not a style preference. The platform gate runs `tsc --noEmit` against\nthe root `tsconfig.json`. A `create-vue`-style root \u2014 `"files": []` plus\n`references` \u2014 makes that command compile **zero files**: it exits 0 on a\nproject full of type errors and the gate reports a pass it never performed.\n\n`vite.config.ts` is deliberately not type-checked.\n\n### `src/shims-vue.d.ts` Is Load-Bearing\n\nThe gate runs `tsc`, **never `vue-tsc`** \u2014 and plain `tsc` cannot resolve an\nimport of a `.vue` file. Without the shim the very first line of `main.ts`\nfails the gate on a phantom error (measured 2026-08-04):\n\n```text\nsrc/main.ts(2,17): error TS2307: Cannot find module \'./App.vue\'\n```\n\nSo the flat tsconfig and the shim are one change: applying either alone is\nworse than the broken state it replaces. Ship both.\n\n`src/shims-vue.d.ts`:\n\n```ts\n/* Lets plain `tsc` resolve `*.vue` imports.\n *\n * Load-bearing: the platform\'s prebuild gate runs `tsc --noEmit`, never\n * `vue-tsc`. Without this shim it stops at\n *   src/main.ts: error TS2307: Cannot find module \'./App.vue\'\n * and every build fails on a phantom error.\n *\n * The shim types an SFC as a generic component, so `tsc` checks all `.ts`\n * files properly but not the internals of a `.vue` file. `npm run verify`\n * runs `vue-tsc --noEmit`, which does check those \u2014 use it before finishing.\n */\ndeclare module \'*.vue\' {\n  import type { DefineComponent } from \'vue\'\n  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>\n  export default component\n}\n```\n\nWhat this buys and what it does not \u2014 all three measured:\n\n| | `tsc` (the gate) | `vue-tsc` (`npm run verify`) |\n| --- | --- | --- |\n| type error in a `.ts` file | caught | caught |\n| type error inside a `.vue` SFC | **missed** \u2014 the shim types it generically | caught |\n\nThat is why `verify` runs `vue-tsc` and why passing the gate is not the same\nas being done.\n\n`tsconfig.json`:\n\n```json\n{\n  "compilerOptions": {\n    "target": "ES2020",\n    "useDefineForClassFields": true,\n    "module": "ESNext",\n    "lib": ["ES2020", "DOM", "DOM.Iterable"],\n    "skipLibCheck": true,\n    "moduleResolution": "bundler",\n    "allowImportingTsExtensions": true,\n    "resolveJsonModule": true,\n    "isolatedModules": true,\n    "noEmit": true,\n    "jsx": "preserve",\n    "strict": true\n  },\n  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]\n}\n```\n\n## Routing Rules\n\nIf adding Vue Router, use `createWebHistory()` (history mode) with `base: \'/\'` in\n`vite.config.ts`. The platform serves at the domain root and falls unknown\ndeep-links back to `index.html`, so routes resolve on hard refresh with clean\nURLs (no `#`). Never use `createWebHashHistory()`. Add `vue-router` only when\nrouting is needed.\n\n## Data And Backend Rules\n\n- No database/server calls unless a backend is configured (respect the build\n  agent\'s STOP gate). Do not invent mock backends or fake data arrays.\n- Keep secrets out of client code; only public keys via `.env.local`.\n\n## Asset Path Rules\n\n- Set `base: \'/\'`. The platform serves the project at the domain root, and\n  history-mode routes need root-absolute assets. Reference the project\'s own\n  assets/routes with root-absolute paths. No `<base>` tag, no hardcoded platform URLs.\n\n## Common Failure Modes\n\n- Using `createWebHashHistory()` \u2192 ugly `#` URLs; use `createWebHistory()`.\n- Keeping relative `base: \'./\'` with history routing \u2192 assets 404 on a deep-link\n  hard refresh; use `base: \'/\'`.\n- Leaving starter boilerplate in `App.vue`.\n- Adding Pinia/Router with no real need.\n\n## ESLint Config\n\nEvery scaffold ships `eslint.config.mjs` (flat config) so the platform lint\ngate and the live ESLint diagnostics work from the very first turn. Verified\nempirically 2026-08-02: `flat/essential` catches real template bugs\n(`vue/require-v-for-key` etc.); `vue/multi-word-component-names` is switched\nOFF because with `--max-warnings 0` it would block every `Hero.vue`-style\nsingle-word component \u2014 a naming convention, not a correctness rule:\n\n`eslint.config.mjs`:\n\n```js\nimport tseslint from \'typescript-eslint\'\nimport vue from \'eslint-plugin-vue\'\n\nexport default tseslint.config(\n  { ignores: [\'dist\'] },\n  {\n    files: [\'**/*.ts\'],\n    extends: [tseslint.configs.base],\n    rules: {\n      \'@typescript-eslint/no-unused-vars\': [\n        \'error\',\n        { argsIgnorePattern: \'^_\', varsIgnorePattern: \'^_\' },\n      ],\n    },\n  },\n  ...vue.configs[\'flat/essential\'],\n  {\n    files: [\'**/*.vue\'],\n    languageOptions: { parserOptions: { parser: tseslint.parser } },\n    rules: {\n      \'vue/multi-word-component-names\': \'off\',\n    },\n  },\n)\n```\n\nThe platform runs `npx eslint . --max-warnings 0` before every build, so any\nviolation blocks the build. Do not add or remove rules, and never "fix" a\nviolation with `eslint-disable` or config edits \u2014 fix the code.\n\n## Verification\n\nRun install, then the full platform verification contract (see the build\nagent\'s "Build And Preview Rules"): typecheck, `npx eslint . --max-warnings 0`\n(the scaffold ships `eslint.config.mjs`, so this check ALWAYS applies and\ndecides acceptance), `npm run build`, and finally verify that\n`dist/index.html` exists. `npm run build` alone is not what the platform gate\nchecks. Never make the lint step pass by disabling rules.\n',
@@ -6498,6 +6587,29 @@ var skills_default = {
 // src/lib/skills.ts
 var SKILLS = skills_default.skills;
 var CONTRACT_SKILL = "agentful-template-contract";
+var MANAGED_DB_SKILL = "agentful-managed-db";
+var MANAGED_DB_LOCAL_ADDENDUM = `## Local session addendum \u2014 managed backend (CLI)
+
+The \`agentful-managed-db\` section above is written for the cloud workspace
+agent. In this LOCAL session there is no \`[BACKEND STATUS]\` preamble, and the
+helper commands it references (\`agentful-managed-collections\`,
+\`agentful-auth-config\`, \`agentful-backend-state\`) are NOT available. Treat
+the section as the authoritative protocol reference whenever the project
+targets the managed backend, with these local rules:
+
+- **Actions:** write each Managed Server Action as \`.server/actions/<name>.js\`
+  and declare its name in \`.agentful/backend.json\` (\`"actions": [...]\`).
+  The normal \`agentful push\` deploys them \u2014 there is no separate sync or
+  upsert command. Push blocks when a declared action has no matching file.
+- **Collections/schema:** you cannot create or upsert collections from here.
+  Document the intended schema in the contract doc plus
+  \`.agentful/backend.json\` and hand over to the user: collections are
+  created and the database enabled in the workspace Backend tab
+  (\`agentful backend\` opens it). Never claim a collection or the database
+  is active before the user enabled it there.
+- **API base:** \`/api/p/{projectId}/\` with exactly the routes the protocol
+  documents (\`/auth/*\`, \`/data/*\`, \`/actions/{name}\`). Never invent paths,
+  SQL schemas, or RLS rules.`;
 var SCAFFOLD_BY_FRAMEWORK = {
   nextjs: "nextjs-scaffold",
   vanilla: "vanilla-scaffold"
@@ -6521,6 +6633,7 @@ function selectSkills(framework, rootDir) {
     const scaffold = SCAFFOLD_BY_FRAMEWORK[framework];
     if (scaffold) names.push(scaffold);
   }
+  names.push(MANAGED_DB_SKILL);
   return names.filter((name) => name in SKILLS);
 }
 function skillBody(name) {
@@ -6532,6 +6645,7 @@ function renderSkillsInstruction(names) {
   const known = names.filter((name) => name in SKILLS);
   if (known.length === 0) return null;
   const sections = known.map((name) => skillBody(name));
+  if (known.includes(MANAGED_DB_SKILL)) sections.push(MANAGED_DB_LOCAL_ADDENDUM);
   return "# Platform deployment skills (mandatory)\n\nThese are the same skills the cloud build agent loads for this stack.\nFollow them when scaffolding or editing \u2014 they are not optional hints.\n\n" + sections.join("\n\n---\n\n") + "\n";
 }
 function skillsInstructionFor(framework, rootDir) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentful",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Agentful in your terminal — local development with push-to-cloud previews",
   "license": "Apache-2.0",
   "homepage": "https://agentful.dev",
@@ -25,7 +25,7 @@
     "typecheck": "tsc --noEmit",
     "dev": "tsx src/index.ts",
     "sync-theme": "cp src/branding/agentful-theme.json ../frontend/public/cli/theme.json",
-    "test": "node --import tsx --test \"src/**/*.test.ts\""
+    "test": "node --import tsx --test src/lib/*.test.ts"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",