ai-wingman 0.0.4 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yonatan Katz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,228 +1,297 @@
-# ai-wingman
+<p align="center">
+  <img src=".github/logo.svg" alt="ai-wingman logo" width="128" />
+</p>
 
-Scaffold production-ready AI patterns into your existing Next.js app — one command per pattern.
+<h1 align="center">ai-wingman</h1>
 
-```bash
-npx ai-wingman add chat
-```
+<p align="center">
+  <strong>The right way to wire AI into your Next.js app.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/ai-wingman"><img src="https://img.shields.io/npm/v/ai-wingman.svg" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/ai-wingman"><img src="https://img.shields.io/npm/dm/ai-wingman.svg" alt="npm downloads" /></a>
+  <a href="https://github.com/yontn-oss/ai-wingman/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/ai-wingman.svg" alt="license" /></a>
+  <a href="https://github.com/yontn-oss/ai-wingman/blob/main/CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome" /></a>
+</p>
+
+<p align="center">
+  <a href="https://ai-wingman-psi.vercel.app/">Website</a>
+</p>
 
-ai-wingman wires together the right SDK primitives, generates plain TypeScript files you own, and exits. There is no runtime dependency on ai-wingman after scaffolding.
+<p align="center">
+  <code>npx ai-wingman add chat</code>
+</p>
+
+<p align="center">
+  ai-wingman writes the API route, UI component, and all the wiring into your existing project — then exits.<br />
+  No runtime dependency. No lock-in. Just clean, typed TypeScript you own.
+</p>
 
 ---
 
-## Patterns
-
-| Command | Core primitive | What you get |
-|---------|---------------|-------------|
-| `wingman add chat` | `streamText` | Streaming chat route, conversation storage, multi-turn page |
-| `wingman add structured-output` | `generateText + Output.object` | Typed JSON route, Zod schema, React hook |
-| `wingman add tools` | `streamText + tools` | Tool-calling route, typed tool stubs |
-| `wingman add stream-object` | `streamObject + useObject` | Streaming structured JSON route and hook |
-| `wingman add rag` | `embed + cosineSimilarity` | Embed route, query route, vector store, client hook |
-| `wingman add interrupt` | `tool({ needsApproval: true }) + addToolApprovalResponse` | Human-in-the-loop approval route, widget, page |
-| `wingman add agent` | `streamText + stopWhen: stepCountIs(N)` | Autonomous agent route, tool stubs, storage, page |
-| `wingman add multimodal` | `convertToModelMessages` | Vision-aware chat route and page with image upload |
-| `wingman add audio` | `experimental_transcribe` / `experimental_generateSpeech` | Transcription route, TTS route, recording page |
-| `wingman add eval` | `generateText` (LLM judge) | Runnable eval script with string-match and judge scoring |
-| `wingman add image-gen` | `generateImage` | Prompt-to-image route (DALL·E), display page with download |
-| `wingman add generative-ui` | `streamUI` (ai/rsc) | Server action that streams React component trees to the client |
-| `wingman add document-processing` | `generateText + Output.object` | File upload route, schema, and hook for PDF / document extraction |
+## Table of contents
+
+- [The problem it solves](#the-problem-it-solves)
+- [How it works](#how-it-works)
+- [18 patterns across 4 categories](#18-patterns-across-4-categories)
+- [New to AI development?](#new-to-ai-development)
+- [Quick start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Under the hood](#under-the-hood)
+- [Contributing](#contributing)
+- [License](#license)
 
 ---
 
-## Quick start
+## The problem it solves
 
-Run inside an existing Next.js + TypeScript project:
+Calling an AI API is three lines of code. Shipping a production AI feature is not.
 
-```bash
-npx ai-wingman add chat
+You need to handle streaming tokens to the UI, structure outputs as typed JSON, store conversation history, let the model call your own functions, guard against bad content, measure quality over time, and do it all without turning your codebase into a mess of `fetch` calls and `any` types.
+
+Every team figures this out from scratch. ai-wingman packages 18 of those patterns — each one the right way to wire that use-case — and scaffolds them with a single command.
+
+---
+
+## How it works
+
+```
+$ npx ai-wingman add rag
 ```
 
-The CLI will:
+```
+┌  ai-wingman
+│
+◆  Next.js 16.2.1 found
+│
+◇  AI provider?
+│  Anthropic
+│
+◇  RAG storage backend?
+│  SQLite + sqlite-vec
+│
+◇  Embedding model ID?
+│  voyage-3
+│
+◇  Stream the query response?
+│  Yes
+│
+◇  Plan ─────────────────────────╮
+│                                │
+│  Install packages:             │
+│    @ai-sdk/anthropic           │
+│    ai                          │
+│    better-sqlite3              │
+│    sqlite-vec                  │
+│                                │
+│  Create files:                 │
+│    app/api/rag/embed/route.ts  │
+│    app/api/rag/query/route.ts  │
+│    lib/rag/store.ts            │
+│    lib/rag/sqlite-store.ts     │
+│    lib/rag/chunker.ts          │
+│    hooks/use-rag-query.ts      │
+│                                │
+├────────────────────────────────╯
+│
+◇  Proceed?
+│  Yes
+│
+◆  Installed @ai-sdk/anthropic, ai, better-sqlite3, sqlite-vec
+│
+◆  Created app/api/rag/embed/route.ts
+◆  Created app/api/rag/query/route.ts
+◆  Created lib/rag/store.ts
+◆  Created lib/rag/sqlite-store.ts
+◆  Created lib/rag/chunker.ts
+◆  Created hooks/use-rag-query.ts
+│
+◇  Add to .env.local ───────────╮
+│                               │
+│  ANTHROPIC_API_KEY=           │
+│  SQLITE_RAG_PATH=             │
+│                               │
+├───────────────────────────────╯
+│
+└  Done! Start your dev server: npm run dev
+```
 
-1. Detect Next.js, TypeScript, and shadcn/ui prerequisites
-2. Ask which provider (Anthropic / OpenAI / Google)
-3. Ask pattern-specific questions (storage, auth, output paths)
-4. Show the full plan and ask for confirmation
-5. Install packages, run `npx ai-elements@latest` and `npx shadcn@latest add`
-6. Write your files
-7. Print the env vars you need to set
+The CLI detects your project, asks targeted questions, shows the full plan before touching anything, installs packages, writes files, and exits. No runtime dependency on ai-wingman after that point.
+
+```
+your project
+    │
+    ▼
+◆ detect  ──── Next.js · TypeScript · shadcn/ui
+    │
+    ▼
+◇ prompt  ──── provider · storage · model · options
+    │
+    ▼
+◇ plan    ──── packages to install · files to create
+    │
+    ▼
+◇ confirm ──── review before anything is written
+    │
+    ▼
+◆ execute ──── install · write · done
+    │
+    ▼
+your project + production-ready AI feature
+```
 
 ---
 
-## CLI commands
+## 18 patterns across 4 categories
 
-```bash
-wingman add <pattern>               # scaffold a pattern interactively
-wingman list                        # list all available patterns
-wingman add <pattern> --overwrite   # re-scaffold, overwriting existing files
-```
+### Generate
 
-Pass flags to skip prompts. `-y` / `--yes` accepts all defaults.
+Text, images, audio, structured data, and UI — anything the model produces directly.
 
-```bash
-# Fully non-interactive
-npx ai-wingman add chat --provider anthropic --storage memory --yes
+| Command | What it builds | What that means |
+|---------|---------------|-----------------|
+| `ai-wingman add chat` | Streaming chat with conversation history | A ChatGPT-style interface backed by your own API route. Responses appear word-by-word instead of all at once. |
+| `ai-wingman add structured-output` | AI that returns typed JSON, not prose | Ask the model a question; get back a strongly-typed object with named fields. Ready to store, display, or pass to the next function. |
+| `ai-wingman add tools` | AI route that can call your functions | You expose functions like `searchDatabase()` or `sendEmail()`. The model decides when to call them and with what arguments. Your code executes them. |
+| `ai-wingman add stream-object` | Progressively streamed typed JSON | The same typed object, but fields fill in one by one as the model generates them — good for long extractions where you want the UI to feel alive. |
+| `ai-wingman add multimodal` | Vision-aware chat with image upload | The same chat interface, but users can attach images. The model can see, describe, and reason about them. |
+| `ai-wingman add audio` | Speech-to-text input + text-to-speech replies | Users speak; the model transcribes, responds, and reads the answer back aloud. |
+| `ai-wingman add image-gen` | Prompt-to-image route with display page | Generate images from a text prompt (DALL·E 3 by default). Includes a download button and swappable model flag. |
+| `ai-wingman add generative-ui` | AI that streams back live React components | Instead of returning text, the model returns actual UI — charts, cards, forms — rendered in real time as they arrive. |
+| `ai-wingman add document-processing` | Upload a file, extract structured data | Drop in a PDF; get back a typed object. Useful for invoice parsing, resume extraction, contract review. |
 
-# Custom output paths
-npx ai-wingman add chat --provider anthropic --api-route app/api/assistant/route.ts --yes
+### Retrieval
 
-# Different storage backend
-npx ai-wingman add rag --provider openai --storage pgvector --yes
+Patterns for grounding the model in your own data.
 
-# Re-scaffold after an update
-npx ai-wingman add chat --provider anthropic --overwrite --yes
-```
+| Command | What it builds | What that means |
+|---------|---------------|-----------------|
+| `ai-wingman add rag` | Embed → store → retrieve → answer pipeline | Let the AI answer questions about *your* documents. It converts text to vectors, finds the most relevant chunks at query time, and uses them as context. This is how "chat with your PDF" products work. |
+| `ai-wingman add hybrid-search` | Keyword + semantic search, merged | Runs a BM25 keyword search and a vector similarity search in parallel, then blends the rankings. More accurate than either approach alone — a drop-in upgrade to `rag`. |
+| `ai-wingman add memory` | Per-user long-term memory across sessions | Saves facts about each user as embeddings, retrieves the most relevant ones at the start of each conversation, and injects them into the system prompt automatically. |
 
----
+### Agents
 
-## Providers
+Patterns where the model takes multiple steps or hands off to humans or other models.
 
-| Flag | Package installed | Env var |
-|------|------------------|---------|
-| `anthropic` | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY` |
-| `openai` | `@ai-sdk/openai` | `OPENAI_API_KEY` |
-| `google` | `@ai-sdk/google` | `GOOGLE_GENERATIVE_AI_API_KEY` |
+| Command | What it builds | What that means |
+|---------|---------------|-----------------|
+| `ai-wingman add agent` | Autonomous multi-step agent loop | The model thinks, calls a tool, sees the result, thinks again — repeating until the task is done. You set the step limit and define the tools. |
+| `ai-wingman add interrupt` | Agent with human-in-the-loop approval gates | Like the agent pattern, but the model pauses and asks a human to confirm before taking any action that can't be undone. |
+| `ai-wingman add multi-agent` | Orchestrator that delegates to specialist sub-agents | A coordinator model breaks work into sub-tasks and hands each off to a focused specialist. Results are synthesized into a single response. |
+| `ai-wingman add background-agent` | Agent that runs outside the HTTP request cycle | Enqueue a task, get a job ID back immediately, then poll for status and result. For work that takes too long to complete in a single HTTP request. |
 
----
+### Quality & Safety
 
-## Common flags
+Patterns that judge, classify, or score AI inputs and outputs.
 
-| Flag | Applies to | Description |
-|------|-----------|-------------|
-| `--provider <id>` | all | `anthropic` / `openai` / `google` |
-| `--auth` | all | Include NextAuth v5 session check (default: off) |
-| `--no-page` | patterns with pages | Omit the generated page component |
-| `--storage <id>` | `rag` | `memory` / `sqlite` / `pgvector` |
-| `--storage memory` | `chat` | Include conversation storage (default: off) |
-| `--interrupt` | `chat` | Embed a human-in-the-loop approval gate in the chat route |
-| `--stream` | `rag` | Use `streamText` instead of `generateText` in query route |
-| `--schema-name <name>` | `structured-output`, `stream-object` | Name for the schema, hook, and type |
-| `--no-hook` | `structured-output`, `stream-object` | Omit the generated client hook |
-| `--tool-name <name>` | `tools` | Name for the generated tool stub file |
-| `--image-model <model>` | `image-gen` | `dall-e-3` (default) or `dall-e-2` |
-| `--overwrite` | all | Overwrite existing files without prompting |
-| `-y, --yes` | all | Accept all defaults |
+| Command | What it builds | What that means |
+|---------|---------------|-----------------|
+| `ai-wingman add eval` | LLM-as-judge evaluation harness | A test suite for AI outputs. You write test cases; a judge model scores each answer. Catch regressions when you change prompts or swap models — the same way unit tests catch bugs in regular code. |
+| `ai-wingman add content-moderation` | LLM-based content classifier | Classifies any input or output against a policy you define. Returns `{ allowed, category, reason }` — drop it in front of any route. |
 
 ---
 
-## File conflict handling
+## New to AI development?
 
-Before writing each file, the CLI checks if it already exists:
+These terms come up constantly. Here's what they actually mean:
 
-- If taken, a warning appears inline
-- You can overwrite, enter a different path, or skip the component
-- `--overwrite` bypasses this prompt silently
-- The CLI never silently overwrites without permission
+**Streaming** — the model generates one token (roughly one word) at a time. Streaming means sending each token to the browser as it arrives, so the UI updates live. Without streaming, you wait for the full response before showing anything.
 
----
+**Structured output** — by default, models return plain text. Structured output forces the model to return a JSON object that matches a schema you define — so you get typed fields instead of a paragraph you'd have to parse.
 
-## Prerequisites
+**Tool calling** — you define functions in your code and tell the model they exist. The model decides when to call them and what arguments to pass. Your code runs the function and returns the result. The model incorporates that result and keeps going. This is the foundation of all agent behavior.
 
-| Requirement | Check | Auto-install |
-|-------------|-------|-------------|
-| React in `package.json` | Required — exits if missing | No |
-| `tsconfig.json` | Required — exits if missing | No |
-| shadcn/ui (`components.json`) | Required for page components | Prompted |
+**RAG** — Retrieval-Augmented Generation. Your documents are converted to vectors (lists of numbers that capture meaning), stored in a vector database, and searched at query time. The most relevant chunks are included in the prompt alongside the user's question. The model answers using your data, not just what it learned during training.
 
----
+**Eval** — AI outputs are non-deterministic. An eval harness measures quality by running your prompts against test cases and scoring the outputs — usually with a second model acting as a judge. It's how you tell whether a prompt change made things better or worse.
 
-## Development
+---
 
-### Local dev loop
+## Quick start
 
 ```bash
-# 1. Build and link the CLI globally (run once)
-bash scripts/dev-link.sh
+npx ai-wingman add chat
+```
 
-# 2. Start watch mode
-pnpm --filter ai-wingman watch
+Add `--yes` to accept all defaults non-interactively:
 
-# 3. Create a fresh test project
-bash scripts/new-fixture.sh
-cd /tmp/wingman-fixture
+### AI coding assistant integration
 
-# 4. Run against it
-ai-wingman add chat --provider anthropic --storage memory --yes
+If you use Claude Code, Cursor, or another AI coding assistant, run:
+
+```bash
+npx ai-wingman skill
 ```
 
-Or point directly at the built binary from any project:
+This downloads a `SKILL.md` into your project that tells your assistant about ai-wingman — what patterns are available, when to use them, and how to invoke them. Once it's there, your assistant will automatically reach for `ai-wingman add` instead of writing AI boilerplate by hand.
 
 ```bash
-node /path/to/wingman/packages/ai-wingman/dist/wingman.js add chat --yes
+npx ai-wingman skill                        # saves to ./SKILL.md (default)
+npx ai-wingman skill --output .cursorrules  # custom output path
 ```
 
-### Tests
-
 ```bash
-pnpm --filter ai-wingman test
+npx ai-wingman add chat --provider anthropic --yes
+npx ai-wingman add rag --provider openai --storage pgvector --yes
+npx ai-wingman add chat --provider anthropic --overwrite --yes  # re-scaffold
 ```
 
-330 tests across all 13 generators. Generators are pure `(config) => string` functions — fast, deterministic, snapshot-tested.
+### Providers
 
-### Project structure
+| Value | Package installed | Env var required |
+|-------|------------------|-----------------|
+| `anthropic` | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY` |
+| `openai` | `@ai-sdk/openai` | `OPENAI_API_KEY` |
+| `google` | `@ai-sdk/google` | `GOOGLE_GENERATIVE_AI_API_KEY` |
 
-```
-packages/ai-wingman/
-├── bin/
-│   └── wingman.ts              # CLI entry point (commander)
-├── src/
-│   ├── types.ts                # Config types for all patterns
-│   ├── registry/
-│   │   ├── providers.ts        # Anthropic, OpenAI, Google
-│   │   ├── storage-adapters.ts
-│   │   ├── patterns.ts         # Pattern registry + resolvers
-│   │   └── index.ts
-│   ├── generators/             # Pure (config) => string functions
-│   ├── patterns/               # One dir per pattern
-│   │   ├── chat/
-│   │   ├── structured-output/
-│   │   ├── tools/
-│   │   ├── stream-object/
-│   │   ├── rag/
-│   │   ├── interrupt/
-│   │   ├── agent/
-│   │   ├── multimodal/
-│   │   ├── audio/
-│   │   ├── eval/
-│   │   ├── image-gen/
-│   │   ├── generative-ui/
-│   │   └── document-processing/
-│   ├── commands/
-│   │   ├── add/                # Main orchestrator
-│   │   └── list/
-│   ├── planner/                # Builds ExecutionPlan before writing
-│   ├── steps/                  # Shared interactive steps
-│   └── utils/
-└── tests/
-    └── unit/generators/        # Snapshot tests per generator
-```
+### All flags
 
-### Adding a provider
+| Flag | Applies to | What it does |
+|------|-----------|-------------|
+| `--provider <id>` | all | `anthropic` / `openai` / `google` |
+| `--auth` | all | Add a NextAuth v5 session check to the route |
+| `--no-page` | patterns with pages | Skip generating the page component |
+| `--storage <id>` | `rag` | `memory` / `sqlite` / `pgvector` |
+| `--storage memory` | `chat` | Add in-memory conversation storage |
+| `--interrupt` | `chat` | Add a human approval gate to the chat route |
+| `--stream` | `rag` | Stream the answer instead of waiting for the full response |
+| `--schema-name <name>` | `structured-output`, `stream-object` | Name for the generated schema, type, and hook |
+| `--no-hook` | `structured-output`, `stream-object` | Skip the generated React hook |
+| `--tool-name <name>` | `tools` | Name for the generated tool stub |
+| `--image-model <model>` | `image-gen` | `dall-e-3` (default) or `dall-e-2` |
+| `--api-route <path>` | all | Custom output path for the API route |
+| `--overwrite` | all | Overwrite existing files without prompting |
+| `-y, --yes` | all | Accept all defaults |
 
-Add an entry to `src/registry/providers.ts`:
+The CLI never silently overwrites a file — it prompts for each conflict unless `--overwrite` is set.
 
-```ts
-{
-  id: 'mistral',
-  label: 'Mistral',
-  package: '@ai-sdk/mistral',
-  importName: 'mistral',
-  envVar: 'MISTRAL_API_KEY',
-  defaultModel: 'mistral-large-latest',
-  modelFactory: 'mistral("mistral-large-latest")',
-}
-```
+---
 
-No other changes needed — the prompt and all generators pick it up automatically.
+## Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| Next.js + TypeScript | Required. The CLI exits if either is missing. |
+| shadcn/ui | Required for page components. The CLI offers to set it up if it's not found. |
+
+---
+
+## Under the hood
+
+- **Generators are pure functions** — `(config) => string`. No side effects, no network calls, no filesystem reads. Fast to test, easy to snapshot.
+- **The planner runs before any files are written** — every `ai-wingman add` builds a complete `ExecutionPlan` first, shows it to you for confirmation, then executes. Nothing is written speculatively.
+- **525 snapshot tests** across all 18 generators. Changing a generator output requires updating the snapshot deliberately — not by accident.
+- **Providers and patterns are registry entries** — adding a new provider is one object in `providers.ts`. All generators pick it up automatically.
+
+For project structure, local dev setup, and contribution guidelines see [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+---
 
-### Adding a pattern
+## Contributing
 
-1. Create `src/patterns/<name>/index.ts` implementing the `Pattern` interface
-2. Add `prompt-config.ts` and `execute.ts` alongside it
-3. Add generators to `src/generators/` as needed
-4. Register the pattern in `src/registry/patterns.ts`
-5. Add snapshot tests in `tests/unit/generators/<name>.test.ts`
+Contributions are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get started.
 
 ---
 

package/dist/index.d.ts

@@ -0,0 +1,117 @@
+type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun';
+
+/** Config collected once before any pattern-specific prompts. */
+interface SharedConfig {
+    provider: ProviderEntry;
+    pathAlias: string;
+    hasSrcDir: boolean;
+    packageManager: PackageManager;
+    targetDir: string;
+    prereqs: {
+        hasShadcn: boolean;
+        hasNext: boolean;
+    };
+}
+/** A single entry in the execution plan (display + execution metadata). */
+type PlanEntry = {
+    kind: 'run';
+    command: string;
+    args: string[];
+} | {
+    kind: 'create';
+    path: string;
+    overwrite?: boolean;
+};
+/** Unified plan produced by the planner across all requested patterns. */
+interface ExecutionPlan {
+    /** Deduplicated package names to install before execution. */
+    packages: string[];
+    /** Ordered entries: CLI runs first, then file creates. */
+    entries: PlanEntry[];
+    /** Per-pattern groups used for display — same entries as above, grouped by pattern id. */
+    groups: Array<{
+        patternId: string;
+        entries: PlanEntry[];
+    }>;
+}
+/** Every pattern implements this interface. */
+interface Pattern {
+    id: string;
+    description: string;
+    /** Non-universal CLI flags this pattern accepts (beyond provider, auth, overwrite, yes). */
+    cliFlags: (keyof AddChatOptions)[];
+    promptConfig(shared: SharedConfig, opts: unknown): Promise<unknown>;
+    getPackages(config: unknown): string[];
+    getPlanEntries(config: unknown): PlanEntry[];
+    getEnvVars(config: unknown): string[];
+    execute(config: unknown, shared: SharedConfig): Promise<void>;
+}
+interface ProviderEntry {
+    id: 'anthropic' | 'openai' | 'google';
+    label: string;
+    package: string;
+    importName: string;
+    envVar: string;
+    defaultModel: string;
+    modelFactory: string;
+    /** Method name on the provider for embedding models (e.g. 'embedding' for openai, 'textEmbeddingModel' for google). Absent if the provider has no native embedding support. */
+    embeddingMethod?: string;
+    /** Method name on the provider for speech generation (e.g. 'speech' for openai). Absent if unsupported. */
+    speechMethod?: string;
+    /** Method name on the provider for speech transcription (e.g. 'transcription' for openai). Absent if unsupported. */
+    transcriptionMethod?: string;
+}
+interface StorageEntry {
+    id: 'memory' | 'postgres';
+    label: string;
+    package?: string;
+    envVar?: string;
+}
+interface StackRegistry {
+    providers: ProviderEntry[];
+    storage: StorageEntry[];
+}
+/** Values parsed from CLI flags — undefined means "not supplied, prompt the user" */
+interface AddChatOptions {
+    /** anthropic | openai | google */
+    provider?: string;
+    /** memory | postgres — presence implies storage component included (default: off) */
+    storage?: string;
+    /** true = --auth (default: off) */
+    auth?: boolean;
+    /** false = --no-page */
+    page?: boolean;
+    /** false = --no-chat-ui */
+    chatUi?: boolean;
+    /** override API route output path */
+    apiRoute?: string;
+    /** override storage output path */
+    storagePath?: string;
+    /** override page component output path */
+    pagePath?: string;
+    /** overwrite existing files without prompting */
+    overwrite?: boolean;
+    /** accept all defaults, skip optional prompts */
+    yes?: boolean;
+    /** schema/hook/type name (default: output) */
+    schemaName?: string;
+    /** override schema output path */
+    schemaPath?: string;
+    /** override hook output path */
+    hookPath?: string;
+    /** false = --no-hook */
+    hook?: boolean;
+    /** true = --interrupt */
+    interrupt?: boolean;
+    /** embedding model ID */
+    embeddingModel?: string;
+    /** image model: dall-e-3 | dall-e-2 (default: dall-e-3) */
+    imageModel?: string;
+    /** override API route output path (generative-ui) */
+    routePath?: string;
+}
+
+declare function resolvePatterns(ids: string[]): Pattern[];
+declare function resolveAllPatterns(): Pattern[];
+
+export { type ExecutionPlan, type PackageManager, type Pattern, type PlanEntry, type ProviderEntry, type SharedConfig, type StackRegistry, type StorageEntry, resolveAllPatterns, resolvePatterns };