@forgeailab/create-spark 0.1.1 → 0.1.3

package/.codex/skills/qa-verify/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: qa-verify
+description: Verify the app actually runs and the feature works end-to-end, not just that code compiles. Use after a feature batch lands, before a demo, when the user says "does this actually work?", "run it and check", or before flipping a task to `Validated`. Do NOT use as a substitute for `/code-review` — they cover different failure modes.
+# Generated from .claude/skills/qa-verify/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: qa-verify
+
+## Goal
+
+Boot the app, click through the real user flow, and confirm the acceptance criteria hold when humans actually use the product. Type-checks and unit tests pass != feature works.
+
+## Recommended model
+
+Sonnet 4.6. This is execution, not judgment.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md` — task(s) being verified
+- `.ai/product-spec.md` — the core user journey
+
+Read if useful:
+
+- `.ai/ux-theme.md` for empty / loading / error patterns
+- `README.md` / `package.json` for the run command
+
+## Rules
+
+- Always run the app. If you cannot launch it, report that explicitly — do not claim verification from reading code.
+- Walk the **core user journey from `product-spec.md`**, not just the changed feature. Regressions in adjacent flows count.
+- Check empty / loading / error / mobile states for every screen touched. MVPs feel broken at the seams, not the happy path.
+- Capture exact commands and outputs so the user can reproduce.
+- Use a real browser or device when relevant (Playwright MCP if available). Curl-ing an API endpoint is not UI verification.
+
+## Workflow
+
+1. Find the run command (project README, `package.json` scripts, or ask).
+2. Boot the app. Note the URL.
+3. Walk the core journey step by step from the spec.
+4. Re-walk the specific feature(s) from the task(s).
+5. Probe empty / loading / error / mobile.
+6. Write the report.
+
+## Output format
+
+```md
+## QA verification — <TASK-ID(s)> / <feature name>
+
+### Boot
+- Command: `<cmd>`
+- Result: app running at <url> | failed (<reason>)
+
+### Core user journey (from spec)
+- [x|✗] Step 1: <description> — <observation>
+- [x|✗] Step 2: ...
+
+### Feature-specific checks
+- [x|✗] <acceptance criterion> — <observation>
+
+### Edge states
+- Empty state: <ok | broken | missing>
+- Loading state: <ok | broken | missing>
+- Error state: <ok | broken | missing>
+- Mobile / narrow viewport: <ok | broken>
+
+### Broken flows discovered
+- <one-line description> — <repro steps>
+
+### Recommended board update
+- <TASK-ID>: review → Validated | review → In progress
+- New tasks to add: <list or none>
+```

package/.codex/skills/risk-check/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: risk-check
+description: Detect whether the project is drifting — scope creep, architecture creep, hidden dependencies, missing tests, unclear tasks, plus stale hybrid-pack helper versions (more than two minor versions behind the latest published). Use every few sessions, when the user says "are we on track?", "is this getting out of hand?", or before a demo. The anti-overthinking and anti-feature-creep skill.
+# Generated from .claude/skills/risk-check/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: risk-check
+
+## Goal
+
+Be the brake. Compare the current state of the project to the spec and architecture, and call out where reality is drifting. Recommend concrete cuts.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+- `.ai/board.md`
+- `.ai/decision-log.md` if it exists
+- `.spark/state.json` if it exists
+- `packs/*/pack.toml` if pack state exists and the registry is available
+
+Sample reality:
+
+- `git log --oneline -30`
+- top-level directory listing
+- list of dependencies in `package.json` / `pyproject.toml` / equivalent
+
+## Rules
+
+- Compare **what is in the code now** to **what the spec said**. Highlight gaps in both directions: missing must-haves, plus things built that the spec did not ask for.
+- Treat the spec's non-goals list as a checklist of things that should NOT be present in code. Violations are creep, not features.
+- Recommend cuts, not additions. The default fix is "remove or defer," not "build more."
+- Distinguish **drift** (planned scope grew quietly) from **discovery** (new task properly added to the board). Discovery is fine; silent drift is not.
+- For pack-level drift, inspect `.spark/state.json` when present. For each installed pack, determine its provided capabilities from state or from `packs/<name>/pack.toml`; if none of those capabilities are referenced in `.ai/product-spec.md` or `.ai/architecture.md`, flag it as drift.
+- The pack-level drift recommendation is exactly: **review or revert the pack-install commit via git**. Do not suggest a CLI removal command; v1 has no pack uninstall flow.
+- For each installed pack whose manifest declares `[runtime_package]` (hybrid pack), inspect the consumer project's `package.json` (`dependencies` + `devDependencies`) for the named helper. Compare the installed version against the latest published version on the npm registry (use `bun pm view <pkg> version` or `npm view <pkg> version` via Bash). If the installed version is more than two minor versions behind the latest, flag it under "Stale helper". A `file:` specifier counts as "local dev link" and is NOT stale.
+
+## Checklist
+
+- **Scope creep** — features in code that are not in `MVP feature list`, or are in `Non-goals`.
+- **Architecture creep** — services / dependencies / abstractions beyond what `architecture.md` declared.
+- **Pack-level drift** — installed packs whose provided capabilities are not justified by the spec or architecture.
+- **Stale helper** — hybrid packs whose helper package is more than two minor versions behind the latest on npm.
+- **Unclear tasks** — open board tasks without observable acceptance criteria.
+- **Missing tests / verification** — tasks marked `Validated` with no run command or no review.
+- **Hidden dependencies** — packages added not justified by a task or decision.
+- **Stalled tasks** — tasks in `In progress` for more than ~2 sessions with no commits.
+
+## Output format
+
+```md
+## Pack-level drift
+- no drift detected
+- <pack-name>: provides <capability tag(s)>; none are referenced in `.ai/product-spec.md` or `.ai/architecture.md` — **recommend: review or revert the pack-install commit via git**
+
+## Stale helper
+- no stale helpers
+- <pack-name>: helper `<helper-package>` installed at <installed-version>, latest is <latest-version> — **recommend: `bun update <helper-package>`**
+
+## Risk check
+
+### Scope creep
+- <thing built / in progress> — not in spec / in non-goals — **recommend: cut | defer | keep with decision log entry**
+
+### Architecture creep
+- <new service / dep / abstraction> — **recommend: revert | document in architecture.md**
+
+### Unclear tasks
+- <TASK-ID>: criteria are vague — **recommend: rewrite or send to `/board-review`**
+
+### Hidden dependencies
+- <package> added in <commit> — justification: <none | <task>>
+
+### Stalled tasks
+- <TASK-ID>: in progress since <when> — **recommend: split | unblock | drop**
+
+### Summary
+- Drift severity: low | medium | high
+- Suggested next action: <one line>
+```

package/.codex/skills/sync-board/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: sync-board
+description: Update `.ai/board.md` to reflect actual code progress — apply status changes from execution reports, add discovered tasks, and recommend the next batch. Use after `/execute-task`, at the end of a working session, or when the user says "update the board", "sync progress", "what's next?". Do NOT use to create the initial board — that is `/mvp-board`.
+# Generated from .claude/skills/sync-board/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: sync-board
+
+## Goal
+
+Keep `.ai/board.md` in sync with reality. The board is the source of truth — if it drifts from what is actually built, the whole system breaks.
+
+## Recommended model
+
+Sonnet 4.6. This is mechanical reconciliation, not planning.
+
+## Inputs
+
+Read these (required):
+
+- `.ai/board.md`
+
+Read if available:
+
+- the most recent `/execute-task` report in the conversation
+- `git status` and `git log` (one screenful) to confirm what actually changed
+- `.ai/execution-log.md` if it exists
+
+## Rules
+
+- **Trust git, not claims.** If a report says a file changed but git disagrees, flag it and do not advance the task.
+- Never set status to `Validated` directly from execution. `Validated` requires a `/code-review` pass and, for user-facing changes, a `/qa-verify` pass. Update `Validation state` accordingly: `code-reviewed`, `qa-verified`, or `both`.
+- Status flow is: `In progress` → `Needs review` → `Validated`. `Blocked` can come from any state.
+- Never move a task to `Approved for execution`. That is `/board-review`'s job.
+- New work discovered during execution becomes a new task in `Clarifying`, at the bottom of the relevant epic — not a silent edit to an existing task.
+- Tasks the user explicitly cut go in the `Cut from MVP` section with a reason — never delete them.
+- If a task is `Blocked`, record the specific blocker in a `Blocked by:` line.
+- When a PR is opened, update `Linked PR:`. When a preview deploy exists, update `Demo URL:`.
+- Append a one-line entry per state change to `.ai/execution-log.md` (create it if missing).
+
+## Workflow
+
+1. Read the board and the latest execution report.
+2. Run `git status` and a short `git log` to confirm actual changes.
+3. For each affected task: update status, append changed-files and verification result.
+4. Add any follow-up tasks discovered.
+5. Identify the next recommended task (or batch) based on dependencies.
+6. Write the updated board and append to the execution log.
+
+## Output format
+
+After writing, return:
+
+```md
+## Board synced
+
+### Status changes
+- <TASK-ID>: <old> → <new>
+
+### Tasks added
+- <NEW-TASK-ID>: <title> (in <EPIC>)
+
+### Blockers
+- <TASK-ID>: <reason>
+
+### Next recommended
+- <TASK-ID> (or batch from `/parallel-execution`)
+- Why now: <one line>
+
+### Drift detected
+- <e.g. "claimed edit to foo.ts but git shows no change"> | none
+```

package/.codex/skills/ux-theme/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ux-theme
+description: Define the visual and product direction (vibe, layout, color, typography, component style) before coding starts. Use when the user says "what should this look like?", "pick a theme", "make it feel like Linear/Notion/Vercel", or right before scaffolding UI. Do NOT use for fine-grained component styling — that belongs in execution.
+# Generated from .claude/skills/ux-theme/SKILL.md — DO NOT EDIT directly
+---
+
+# Skill: ux-theme
+
+## Goal
+
+Produce `.ai/ux-theme.md` — a concrete visual direction that every executor task can consult. Lovable-style theme control: one clear vibe, one set of patterns, one reference product.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5 for the direction. Sonnet 4.6 can implement against it later.
+
+## Inputs
+
+Read these if they exist:
+
+- `.ai/product-spec.md`
+- `.ai/architecture.md`
+- `.ai/decision-log.md`
+
+## Rules
+
+- Pick **one** vibe. Not "minimal but playful but also enterprise."
+- Name **one** reference product to imitate. "Linear-style productivity SaaS" beats "clean and modern."
+- Give concrete tokens (color names, type scale, spacing) so executors do not invent their own.
+- Define empty / loading / error patterns up front — these are where MVPs feel broken.
+- Do not generate full design files. This is a brief, not Figma.
+
+## Reference directions (pick one or describe a new one)
+
+- Linear-style productivity SaaS
+- Notion-like workspace
+- Vercel-like developer tool
+- Stripe-like admin dashboard
+- Arc-like playful consumer app
+
+## Output format
+
+Write `.ai/ux-theme.md`:
+
+```md
+# UX Theme — <name>
+
+## Vibe
+<one sentence>
+
+## Reference product
+<one product, with a link or short description of what to copy>
+
+## Layout style
+<sidebar + content / centered single column / dashboard grid / etc.>
+
+## Color direction
+- Background:
+- Surface:
+- Text primary:
+- Text muted:
+- Accent:
+- Danger:
+(prefer Tailwind palette names or hex)
+
+## Typography
+- Display:
+- Body:
+- Mono:
+- Scale: <e.g. 12 / 14 / 16 / 20 / 24 / 32>
+
+## Component style
+- Corners: <radius>
+- Borders: <weight, color>
+- Shadows: <none / soft / layered>
+- Buttons: <filled / outlined / ghost variants>
+- Inputs: <style>
+
+## Patterns
+- Empty state:
+- Loading state:
+- Error state:
+- Table:
+- Card:
+- Dialog / modal:
+
+## Constraints
+- <hard "no" rules, e.g. "no gradients", "no emoji in UI">
+```
+
+After writing, recommend `/mvp-board` next.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeailab/create-spark",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Interactive scaffolder for spark projects with guided pack picker.",
   "type": "module",
   "publishConfig": {
@@ -8,14 +8,20 @@
   },
   "files": [
     "src",
-    "README.md"
+    "README.md",
+    "packs",
+    "presets",
+    "templates",
+    ".claude",
+    ".codex",
+    "scripts"
   ],
   "bin": {
     "create-spark": "./src/cli.ts"
   },
   "dependencies": {
-    "@forgeailab/spark": "^0.1.1",
-    "@forgeailab/spark-schema": "^0.1.1",
+    "@forgeailab/spark": "^0.1.3",
+    "@forgeailab/spark-schema": "^0.1.3",
     "@clack/prompts": "latest",
     "citty": "latest",
     "picocolors": "latest"

package/packs/README.md

@@ -0,0 +1,132 @@
+# Packs
+
+A **pack** is a self-contained unit of capability — auth, db, payments, UI, AI SDK, email, deploy target, … — that the `spark` CLI can install into a scaffolded project. Packs are TOML-manifested, declarative (no shell hooks), and capability-resolved.
+
+## Directory layout
+
+```
+packs/<name>/
+├── pack.toml         # manifest (REQUIRED)
+├── files/            # tree of files to copy into the project (optional)
+├── skills/           # SKILL.md folders shipped with this pack (optional)
+└── tasks.yaml        # board tasks seeded into .ai/board.md on install (optional)
+```
+
+## `pack.toml`
+
+See [`docs/pack-spec.md`](../docs/pack-spec.md) for the full schema. The Zod source of truth is `packages/spark-schema/src/pack.ts`.
+
+A minimum-viable pack:
+
+```toml
+name = "db-sqlite"
+version = "0.1.0"
+category = "db"
+description = "Local SQLite database via bun:sqlite + drizzle-orm."
+
+provides = ["db"]
+requires = []
+conflicts = ["db"]
+requires_runtime = ["server"]
+compatible_scaffolds = ["nextjs"]
+
+[dependencies]
+runtime = ["drizzle-orm"]
+dev = ["drizzle-kit"]
+
+[env]
+required = ["DATABASE_URL"]
+
+[[files]]
+mode = "create"
+from = "files/lib/db.ts"
+to = "lib/db.ts"
+
+[tasks]
+file = "tasks.yaml"
+```
+
+## File modes
+
+| Mode | Behavior |
+|---|---|
+| `create` | Fails if the destination already exists |
+| `append` | Idempotent; uses `# >>> spark:<pack> >>>` / `# <<<` markers |
+| `merge-json` | Deep-merges into an existing JSON file with deterministic key order |
+| `template` | Handlebars-style substitution from `spark.config.json` (e.g. `{{appName}}`) |
+
+## Capability enums (closed)
+
+**Pack capabilities** (`provides` / `requires` / `conflicts`):
+`db, auth, payments, email, ui-kit, local-runtime, deploy-target, e2e, ai-sdk, blob-storage, analytics, sync`
+
+Exclusive (one provider per project): `db, auth, payments, ui-kit, sync`
+Non-exclusive (multiple providers OK): `ai-sdk, analytics, email, blob-storage, e2e, deploy-target, local-runtime`
+
+**Template capabilities** (`requires_runtime`):
+`static, server, react, native, vue, svelte, mdx-content, edge-runtime`
+
+The two enums are separate and never overlap. Adding a new value requires a registry-wide change.
+
+## What is NOT allowed
+
+- `post_install`, `hooks`, `pre_add`, `scripts` — packs MUST be declarative. If your pack needs a setup step that can't be expressed in `[[files]]`, ship it as a seeded board task the user runs manually.
+- Pack-name conflicts (`conflicts = ["other-pack-name"]`). Use capability tags only.
+- Cross-pack file ownership. Two packs MUST NOT write the same `to` path with `create` mode.
+
+## Adding a new pack
+
+```bash
+# In Claude Code:
+/new-pack realtime-supabase category=db
+```
+
+Then fill in the generated `packs/realtime-supabase/pack.toml`. Validate with:
+
+```bash
+bun -e "import {parsePackToml} from './packages/spark-schema/src/parse.ts'; import {readFileSync} from 'node:fs'; const r = parsePackToml(readFileSync('packs/realtime-supabase/pack.toml','utf8')); console.log(r.ok ? 'OK' : r.error);"
+```
+
+See `packs/example/pack.toml` for a manifest that exercises every field.
+
+## v1 catalog
+
+Each pack is either **copy** (ships file trees the user owns) or **hybrid** (ships thin wiring + imports runtime logic from a versioned `@forgeailab/spark-*` helper under `libs/`). The mode is inferred from the presence of a `[runtime_package]` block in the manifest.
+
+| Pack | Category | Mode | Runtime helper |
+|---|---|---|---|
+| `auth-better-auth` | auth | **hybrid** | `@forgeailab/spark-auth-better-auth` (SQLite) |
+| `auth-better-auth-pg` | auth | **hybrid** | `@forgeailab/spark-auth-better-auth` (Postgres) |
+| `auth-supabase` | auth | copy | — |
+| `db-sqlite` | db | copy | — |
+| `db-postgres` | db | copy | — |
+| `db-supabase` | db | copy | — |
+| `sync-zero` | infra | **hybrid** | `@forgeailab/spark-sync-zero` |
+| `payments-stripe` | payments | **hybrid** | `@forgeailab/spark-stripe-helpers` |
+| `ai-anthropic` | ai | **hybrid** | `@forgeailab/spark-anthropic` |
+| `ai-openai` | ai | copy | — |
+| `ui-shadcn` | ui | copy | — |
+| `email-resend` | email | copy | — |
+| `analytics-posthog` | analytics | copy | — |
+| `docker-compose-dev` | infra | copy | — |
+| `testing-playwright` | testing | copy | — |
+| `deploy-vercel` | deploy | copy | — |
+
+### Picking a db + auth pair
+
+`auth-better-auth` and `auth-better-auth-pg` share the same runtime helper
+(`@forgeailab/spark-auth-better-auth`) — they differ only in the `provider:`
+their generated `lib/auth.ts` template hands to `drizzleAdapter`. Pair them:
+
+- `db-sqlite` + `auth-better-auth` — fastest path, single file db, no infra.
+- `db-postgres` + `auth-better-auth-pg` — production-shaped, **required for `sync-zero`** (Zero needs Postgres logical replication).
+- `db-supabase` + `auth-better-auth-pg` — Supabase-hosted Postgres + Better Auth on top.
+
+The two auth packs both `conflicts = ["auth"]`, so the resolver prevents
+installing both. Mixing wrong pairs (e.g. `db-sqlite` + `auth-better-auth-pg`)
+typechecks but fails at runtime — the drizzle adapter will reject sqlite tables
+with `provider: 'pg'`.
+
+The hybrid packs were authored against [`reference/full-stack-saas/`](../reference/full-stack-saas/) — the canonical integration showing all four helpers working together. When debugging a hybrid pack, start there.
+
+See the root `README.md` for the catalog summary.

package/packs/ai-anthropic/files/app/api/ai/route.ts

@@ -0,0 +1,57 @@
+import { anthropic, streamResponse, type AnthropicChatMessage } from '@/lib/anthropic';
+import { NextResponse, type NextRequest } from 'next/server';
+
+export const runtime = 'nodejs';
+
+const DEFAULT_MODEL = 'claude-sonnet-4-5';
+const DEFAULT_MAX_TOKENS = 1_024;
+const HARD_MAX_TOKENS = 4_096;
+
+type ChatRequest = {
+  messages?: unknown;
+  system?: string;
+  model?: string;
+  maxTokens?: number;
+};
+
+function normalizeMessages(value: unknown): AnthropicChatMessage[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const messages: AnthropicChatMessage[] = [];
+  for (const entry of value) {
+    if (typeof entry !== 'object' || entry === null) return undefined;
+    const role = 'role' in entry ? entry.role : undefined;
+    const content = 'content' in entry ? entry.content : undefined;
+    if ((role !== 'user' && role !== 'assistant') || typeof content !== 'string') return undefined;
+    messages.push({ role, content });
+  }
+  return messages.length > 0 ? messages : undefined;
+}
+
+export async function POST(request: NextRequest) {
+  const body = (await request.json().catch(() => ({}))) as ChatRequest;
+  const messages = normalizeMessages(body.messages);
+
+  if (!messages) {
+    return NextResponse.json(
+      { error: 'messages must be a non-empty array of user/assistant strings' },
+      { status: 400 },
+    );
+  }
+
+  const maxTokens = Math.min(Math.max(1, body.maxTokens ?? DEFAULT_MAX_TOKENS), HARD_MAX_TOKENS);
+
+  const stream = streamResponse(anthropic, {
+    model: body.model ?? DEFAULT_MODEL,
+    max_tokens: maxTokens,
+    system: body.system,
+    messages,
+  });
+
+  return new Response(stream, {
+    headers: {
+      'Content-Type': 'text/event-stream; charset=utf-8',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+    },
+  });
+}

package/packs/ai-anthropic/files/lib/anthropic.ts

@@ -0,0 +1,15 @@
+import type Anthropic from '@anthropic-ai/sdk';
+import { createAnthropicClient, streamResponse } from '@forgeailab/spark-anthropic';
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    throw new Error(`Missing required environment variable: ${name}`);
+  }
+  return value;
+}
+
+export const anthropic = createAnthropicClient(requireEnv('ANTHROPIC_API_KEY'));
+
+export { streamResponse };
+export type AnthropicChatMessage = Anthropic.Messages.MessageParam;

package/packs/ai-anthropic/pack.toml

@@ -0,0 +1,32 @@
+name = "ai-anthropic"
+version = "1.0.0"
+category = "ai"
+description = "Anthropic SDK client and streaming chat endpoint."
+provides = ["ai-sdk"]
+requires = []
+conflicts = []
+requires_runtime = ["server"]
+compatible_scaffolds = []
+
+[runtime_package]
+package = "@forgeailab/spark-anthropic"
+version = "^0.1"
+
+[env]
+required = ["ANTHROPIC_API_KEY"]
+
+[[files]]
+mode = "create"
+from = "lib/anthropic.ts"
+to = "lib/anthropic.ts"
+
+[[files]]
+mode = "create"
+from = "app/api/ai/route.ts"
+to = "app/api/ai/route.ts"
+
+[skills]
+copy = ["skills/ai-feature-patterns"]
+
+[tasks]
+file = "tasks.yaml"

package/packs/ai-anthropic/skills/ai-feature-patterns/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: ai-feature-patterns
+description: Build Anthropic-backed AI features with streaming UX, prompt discipline, and cost controls. Use when implementing or reviewing features after the ai-anthropic pack is installed.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+---
+
+# Skill: ai-feature-patterns
+
+## Goal
+
+Add one focused AI capability that helps the product journey without turning the
+MVP into a generic chat app. Keep prompts inspectable, streams responsive, and
+cost bounded by server-side controls.
+
+## Recommended model
+
+Opus 4.7 or GPT-5.5 for prompt architecture and evaluation. Sonnet 4.6 or GPT-5
+family executor for endpoint, UI, and test wiring.
+
+## Inputs
+
+Read these before changing AI behavior:
+
+- `.ai/product-spec.md` for the user workflow and non-goals
+- `.ai/architecture.md` for persistence, auth, and runtime boundaries
+- `.ai/board.md` for the exact AI task and acceptance criteria
+- `lib/anthropic.ts` for shared client setup
+- `app/api/ai/route.ts` for request, stream, and guardrail behavior
+
+If the spec does not name the decision or artifact the AI should improve, stop
+and ask. Do not add chat just because an AI SDK is installed.
+
+## Prompt Patterns
+
+- Put durable behavior in a server-owned system prompt.
+- Put user-specific state in structured context, not prose pasted from the UI.
+- Keep task prompts narrow: role, input facts, output format, refusal boundary.
+- Prefer JSON or Markdown output contracts only when the UI actually needs them.
+- Do not ask the model to enforce authorization, billing, or data access rules.
+- Include the smallest useful context window; retrieve or summarize before
+  sending long histories.
+
+## Streaming UX
+
+- Stream text when the user is waiting on generation or analysis.
+- Show partial output in the destination surface, not a separate debug pane.
+- Preserve a cancel path when requests can take more than a few seconds.
+- Persist the final answer only after the stream completes successfully.
+- Treat stream errors as recoverable UI state with a retry action.
+
+## Cost Controls
+
+- Cap `max_tokens` on the server, even when the client sends a smaller hint.
+- Rate limit by user, organization, or IP before calling Anthropic.
+- Add a cheap preflight check for empty prompts and unsupported file sizes.
+- Log model, token caps, latency, and user/account id for cost review.
+- Use smaller models or cached summaries for low-stakes transformations.
+- Keep generated artifacts small enough to review and edit.
+
+## Safety and Privacy
+
+- Send only the data needed for the requested feature.
+- Redact secrets and credentials from context before model calls.
+- Avoid storing raw prompts if they may contain sensitive customer data.
+- Make model output advisory unless the product spec explicitly automates action.
+- Require human confirmation before sending emails, charging users, or deleting data.
+
+## Common Pitfalls
+
+- Do not stream from the browser directly with the API key.
+- Do not let the client choose unlimited tokens or arbitrary expensive models.
+- Do not hide prompt changes in component code; keep prompts close to API routes.
+- Do not make acceptance criteria depend on subjective model quality alone.
+- Do not add vector search, agents, or tool calls unless the board asks for them.
+
+## Verification
+
+Use a small real prompt and confirm all of these:
+
+- The endpoint streams incremental `text` events.
+- The final event is `done`.
+- Invalid input returns a 400 before calling Anthropic.
+- Token caps and rate limits are enforced server-side.