@struktur/skill 2.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mateffy
+
+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

@@ -0,0 +1,87 @@
+<picture height="0">
+  <source media="(min-width: 769px)" srcset="https://raw.githubusercontent.com/mateffy/struktur/main/resources/pixel.png" width="0" height="0">
+  <img src="https://raw.githubusercontent.com/mateffy/struktur/main/resources/struktur-icon-padded.webp" alt="Struktur Logo" width="150">
+</picture>
+
+<div>
+    <h1>
+        <picture>
+            <source media="(max-width: 768px)" srcset="https://raw.githubusercontent.com/mateffy/struktur/main/resources/pixel.png" width="0" height="0">
+            <img src="https://raw.githubusercontent.com/mateffy/struktur/main/resources/struktur-icon-padded.webp" alt="Struktur Logo" width="225" align="left">
+        </picture>
+        Struktur Agent Skill
+    </h1>
+    <p>
+      All-in-one tool for structured data extraction using LLMs. Feed it documents, get back validated JSON. Handles parsing files, chunking, retries, merging, and deduplication — you just define the schema and choose a strategy. <br /><br />
+        <a href="https://struktur.sh/docs/quickstart" target="_blank">Quickstart</a> |
+        <a href="https://struktur.sh/docs" target="_blank">Documentation</a>
+    </p>
+</div>
+
+<br />
+<br />
+
+## @struktur/skill
+
+Agent skill for Struktur - structured data extraction using the Vercel AI SDK. This skill teaches AI coding assistants (like Claude Code, OpenCode, Codex, etc.) how to use Struktur effectively.
+
+## What is This?
+
+This package contains an [Agent Skills](https://github.com/anthropics/skills) compatible skill file that works across 16+ AI agent tools. When you ask your AI agent to work with Struktur, this skill automatically loads and provides:
+
+- **API Usage**: How to use `extract()`, build artifacts, define schemas
+- **Strategy Selection**: When to use `simple`, `parallel`, `sequential`, `doublePass`, etc.
+- **Schema Definition**: JSON Schema patterns and shorthand field syntax
+- **CLI Commands**: All struktur CLI commands and options
+- **Best Practices**: Token budgets, validation retries, merge rules
+
+## Installation
+
+### From npm
+
+```bash
+npm install @struktur/skill
+```
+
+Then copy to your tool's skill directory:
+
+```bash
+# For Claude Code
+cp -r node_modules/@struktur/skill/skills/struktur ~/.config/claude/skills/
+
+# For OpenCode
+cp -r node_modules/@struktur/skill/skills/struktur ~/.config/opencode/skills/
+
+# For OpenAI Codex
+cp -r node_modules/@struktur/skill/skills/struktur ~/.codex/skills/
+```
+
+### Using Skills CLI
+
+```bash
+npx skills add @struktur/skill
+```
+
+## Supported Tools
+
+- ✅ Claude Code
+- ✅ OpenCode
+- ✅ OpenAI Codex
+- ✅ Amp
+- ✅ VS Code (GitHub Copilot)
+- ✅ Cursor
+- ✅ Gemini CLI
+- ✅ JetBrains (Junie)
+- ✅ And 10+ more tools
+
+## Documentation
+
+Full documentation at **[struktur.sh](https://struktur.sh)**
+
+- [Agent Skill Guide](https://struktur.sh/docs/skill)
+- [Installation](https://struktur.sh/docs/skill/installation)
+- [Usage](https://struktur.sh/docs/skill/usage)
+
+## Repository
+
+This package is part of the [Struktur monorepo](https://github.com/mateffy/struktur).

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@struktur/skill",
+  "version": "2.6.0",
+  "description": "Agent skill for Struktur - structured data extraction using Vercel AI SDK",
+  "type": "module",
+  "main": "skills/struktur/SKILL.md",
+  "files": [
+    "skills/**/*"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "skill",
+    "struktur",
+    "structured-data",
+    "extraction",
+    "llm",
+    "vercel-ai-sdk"
+  ],
+  "author": "mateffy",
+  "license": "FSL-1.1-MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mateffy/struktur.git",
+    "directory": "packages/skill"
+  },
+  "bugs": {
+    "url": "https://github.com/mateffy/struktur/issues"
+  },
+  "homepage": "https://github.com/mateffy/struktur#readme"
+}

package/skills/struktur/README.md

@@ -0,0 +1,152 @@
+# Struktur Agent Skill
+
+This directory contains the Agent Skill for Struktur - structured data extraction using the Vercel AI SDK.
+
+## What is an Agent Skill?
+
+An Agent Skill is a modular knowledge package that AI coding agents (like Claude Code, OpenCode, Codex, etc.) can discover and load automatically. Skills follow an open standard and work across 16+ AI agent tools.
+
+## How It Works
+
+When you ask your AI agent to work with Struktur, this skill automatically loads and provides:
+
+- **API Usage**: How to use `extract()`, build artifacts, define schemas
+- **Strategy Selection**: When to use `simple`, `parallel`, `sequential`, `doublePass`, etc.
+- **Schema Definition**: JSON Schema patterns and shorthand field syntax
+- **CLI Commands**: All struktur CLI commands and options
+- **Best Practices**: Token budgets, validation retries, merge rules
+
+## Installation
+
+### For Claude Code
+
+```bash
+# Install globally
+mkdir -p ~/.config/claude/skills
+cp -r . ~/.config/claude/skills/struktur
+
+# Or install in a project
+mkdir -p .agents/skills
+cp -r . .agents/skills/struktur
+```
+
+### For OpenCode
+
+```bash
+# Install globally
+mkdir -p ~/.config/opencode/skills
+cp -r . ~/.config/opencode/skills/struktur
+
+# Or install in a project
+mkdir -p .agents/skills
+cp -r . .agents/skills/struktur
+```
+
+### For OpenAI Codex
+
+```bash
+# Install globally
+mkdir -p ~/.codex/skills
+cp -r . ~/.codex/skills/struktur
+
+# Or install in a project
+mkdir -p .codex/skills
+cp -r . .codex/skills/struktur
+```
+
+### For Amp
+
+```bash
+# Install globally
+mkdir -p ~/.config/amp/skills
+cp -r . ~/.config/amp/skills/struktur
+
+# Or install in a project
+mkdir -p .agents/skills
+cp -r . .agents/skills/struktur
+```
+
+### For VS Code (GitHub Copilot)
+
+```bash
+# Install in workspace
+mkdir -p .vscode/skills
+cp -r . .vscode/skills/struktur
+```
+
+### For Cursor
+
+```bash
+# Install in project
+mkdir -p .cursor/skills
+cp -r . .cursor/skills/struktur
+```
+
+### Using the Skills CLI (Universal)
+
+If you have the [skills CLI](https://github.com/vercel/skills) installed:
+
+```bash
+# Install from npm
+npx skills add @struktur/skill
+
+# Or install from GitHub
+npx skills add https://github.com/mateffy/struktur/tree/main/packages/skill/skills/struktur
+```
+
+## Usage
+
+Once installed, just ask your AI agent:
+
+```
+"Use struktur to extract product data from this PDF"
+"Set up struktur to parse invoices with parallel strategy"
+"Help me configure the struktur CLI for my project"
+```
+
+The agent will automatically load this skill and follow Struktur's best practices.
+
+## Supported Tools
+
+This skill works with any tool that supports the [Agent Skills open standard](https://github.com/anthropics/skills):
+
+- ✅ Claude Code
+- ✅ OpenCode
+- ✅ OpenAI Codex
+- ✅ Amp
+- ✅ VS Code (GitHub Copilot)
+- ✅ Cursor
+- ✅ Gemini CLI
+- ✅ JetBrains (Junie)
+- ✅ And 10+ more tools
+
+## Skill Structure
+
+```
+struktur/
+├── SKILL.md          # Main skill file (this directory)
+├── README.md         # This file
+├── scripts/          # (optional) executable helpers
+├── references/       # (optional) additional docs
+└── assets/           # (optional) templates and examples
+```
+
+## Progressive Disclosure
+
+The skill uses progressive disclosure to minimize token usage:
+
+1. **Metadata Phase** (~100 tokens): Agent loads only name + description
+2. **Activation Phase**: When task matches description, agent asks permission to load
+3. **Full Load** (up to 5,000 tokens): Complete SKILL.md loads into context
+4. **On-Demand**: Supporting files (scripts, references) load as needed
+
+## Resources
+
+- [Struktur Repository](https://github.com/mateffy/struktur)
+- [Struktur Documentation](https://github.com/mateffy/struktur#readme)
+- [Agent Skills Specification](https://github.com/anthropics/skills)
+- [Vercel AI SDK](https://sdk.vercel.ai)
+
+## License
+
+MIT

package/skills/struktur/SKILL.md

@@ -0,0 +1,404 @@
+---
+name: struktur
+description: Extracts structured JSON from documents using an autonomous agent with the Vercel AI SDK. The agent explores documents using a virtual filesystem (read, grep, find, bash tools) and extracts data incrementally. Also supports traditional strategies (simple/parallel/sequential/doublePass) for specific use cases. Use when working with @struktur/sdk — importing extract(), choosing extraction strategies, building Artifacts, defining schemas, or using the struktur CLI.
+metadata:
+  author: mateffy
+  version: "2.0"
+---
+
+# Struktur
+
+Struktur extracts structured JSON from documents using an **autonomous agent**. The agent explores documents via a virtual filesystem, deciding when to read files, search for patterns, and build output incrementally.
+
+**Key concept**: The `agent` strategy is the default. It works best for most documents. Traditional strategies (`simple`, `parallel`, `sequential`, `doublePass`) are available for specific cases where you need more control.
+
+**Package**: `@struktur/sdk`  
+**Runtime**: Bun (use `bun install`, `bun test`, `bun run`)
+
+## Core API
+
+```typescript
+import { extract, agent } from "@struktur/sdk";
+import type { JSONSchemaType } from "ajv";
+
+const result = await extract({
+  artifacts,           // Artifact[]  — required
+  schema,              // JSONSchemaType<T> | AnyJSONSchema — mutually exclusive with fields
+  fields,              // string — shorthand, e.g. "title, price:number" — mutually exclusive with schema
+  strategy,            // ExtractionStrategy<T> — required (use agent() for default)
+  events?,             // ExtractionEvents — optional progress hooks
+  debug?,              // DebugLogger — optional JSON logging
+  strict?,             // boolean — strict schema validation
+});
+
+result.data    // T — extracted, validated output
+result.usage   // { inputTokens, outputTokens, totalTokens }
+result.error   // Error | undefined
+```
+
+## Agent Strategy (Default)
+
+The agent strategy is the **default and recommended** way to use Struktur. It gives the LLM a virtual filesystem and lets it autonomously extract your data.
+
+### How it works
+1. Document loaded into virtual filesystem (`/artifacts/artifact.json`, `/artifacts/images/`)
+2. Agent explores using tools: **read**, **grep**, **find**, **ls**, **bash**
+3. Builds output incrementally via **set_output_data** and **update_output_data**
+4. Calls **finish** when complete, or **fail** if impossible
+5. Schema validation on every update with automatic retry
+
+### Configuration
+
+```typescript
+import { extract, agent } from "@struktur/sdk";
+
+strategy: agent({
+  provider: "anthropic",           // Provider name (anthropic, openai, google, opencode)
+  modelId: "claude-sonnet-4",      // Model identifier
+  maxSteps?: 50,                   // Max agent steps (default: 50)
+  apiKey?: "sk-...",              // API key (or use env vars)
+  outputInstructions?: "string",   // Extra extraction guidance
+})
+```
+
+### Model compatibility
+The agent requires models with tool/function calling support:
+- **Anthropic**: Claude 3.5 Sonnet, Claude 3 Opus, Claude 3 Haiku
+- **OpenAI**: GPT-4o, GPT-4 Turbo, GPT-4, GPT-3.5 Turbo
+- **Google**: Gemini 1.5 Pro, Gemini 1.5 Flash
+
+### Example
+
+```typescript
+import { extract, agent } from "@struktur/sdk";
+
+const result = await extract({
+  artifacts,
+  schema,
+  strategy: agent({
+    provider: "anthropic",
+    modelId: "claude-sonnet-4",
+    maxSteps: 50,
+  }),
+});
+```
+
+### CLI usage
+
+```bash
+# Agent is the default — no --strategy needed
+struktur extract --input ./document.pdf --schema ./schema.json
+
+# With specific model and max steps
+struktur extract --input ./document.pdf \
+  --schema ./schema.json \
+  --model anthropic/claude-sonnet-4 \
+  --max-steps 30
+```
+
+## Traditional Strategies
+
+For specific use cases where you need more control over chunking and parallelism.
+
+| Strategy | When to use | Key config |
+|---|---|---|
+| `agent` (default) | **Most documents** — autonomous exploration | `provider`, `modelId`, `maxSteps` |
+| `simple` | Small input, fits in one context window | `model` |
+| `parallel` | Large input, array/list output, order doesn't matter | `model`, `mergeModel`, `chunkSize`, `concurrency?` |
+| `sequential` | Large input, context must carry over between batches | `model`, `chunkSize` |
+| `parallelAutoMerge` | Large input, array output, need dedup | `model`, `chunkSize`, `dedupeModel?` |
+| `sequentialAutoMerge` | Large input, sequential + dedup | `model`, `chunkSize`, `dedupeModel?` |
+| `doublePass` | Max accuracy: parallel merge then sequential refinement | `model`, `mergeModel`, `chunkSize` |
+| `doublePassAutoMerge` | Max accuracy + dedup | `model`, `chunkSize`, `dedupeModel?` |
+
+```typescript
+import { extract, simple, parallel, sequential, parallelAutoMerge, doublePass } from "@struktur/sdk";
+import { google } from "@ai-sdk/google";
+import { anthropic } from "@ai-sdk/anthropic";
+import { openai } from "@ai-sdk/openai";
+
+// Simple — small inputs
+strategy: simple({ model: google("gemini-2.0-flash") })
+
+// Parallel — large inputs, list output
+strategy: parallel({
+  model: google("gemini-2.0-flash"),
+  mergeModel: google("gemini-2.0-flash"),
+  chunkSize: 10_000,
+  concurrency: 4,
+})
+
+// Sequential — context carryover between batches
+strategy: sequential({ model: anthropic("claude-sonnet-4-5"), chunkSize: 8_000 })
+
+// Double pass — highest accuracy
+strategy: doublePass({
+  model: openai("gpt-4o"),
+  mergeModel: openai("gpt-4o"),
+  chunkSize: 12_000,
+  concurrency: 3,
+})
+```
+
+**Common config options** (all strategies):
+- `model` — Vercel AI SDK model instance
+- `chunkSize` — token budget per batch (default: 10_000)
+- `maxImages?` — max images per batch
+- `outputInstructions?` — extra extraction guidance in system prompt
+- `strict?` — strict schema validation
+
+## Schema Definition
+
+Two approaches — mutually exclusive:
+
+### JSON Schema (typed)
+```typescript
+import type { JSONSchemaType } from "ajv";
+
+type Output = {
+  title: string;
+  items: Array<{ name: string; price: number }>;
+};
+
+const schema: JSONSchemaType<Output> = {
+  type: "object",
+  properties: {
+    title: { type: "string" },
+    items: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string" },
+          price: { type: "number" },
+        },
+        required: ["name", "price"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["title", "items"],
+  additionalProperties: false,
+};
+```
+
+### Shorthand fields string
+```typescript
+// "name" defaults to string; "name:type" for explicit types
+const fields = "title, price:number, active:boolean, tags:array";
+// Supported: string, number, boolean, integer, int, float, bool, enum{a|b|c}, array (defaults to array{string}), array{type}
+```
+
+## Building Artifacts
+
+Struktur does NOT parse PDFs, HTML, or files — it expects pre-parsed Artifacts.
+
+```typescript
+import type { Artifact, ArtifactContent } from "@struktur/sdk";
+
+// Manual construction
+const artifact: Artifact = {
+  id: "doc-1",
+  type: "text",            // "text" | "image" | "pdf" | "file"
+  raw: async () => Buffer.from("source content"),
+  contents: [
+    { page: 1, text: "Extracted text content here..." },
+    { page: 2, text: "More content...", media: [{ type: "image", url: "..." }] },
+  ],
+};
+
+// From URL (fetches Artifact JSON)
+import { urlToArtifact } from "@struktur/sdk";
+const artifact = await urlToArtifact("https://example.com/artifact.json");
+
+// From file buffer with custom provider
+import { fileToArtifact } from "@struktur/sdk";
+const providers = {
+  "application/pdf": async (buffer: Buffer) => ({
+    id: "pdf-1",
+    type: "pdf" as const,
+    raw: async () => buffer,
+    contents: [{ page: 1, text: "..." }],
+  }),
+};
+const artifact = await fileToArtifact(buffer, { mimeType: "application/pdf", providers });
+```
+
+**ArtifactImage** fields: `type`, `url?`, `base64?`, `contents?` (Buffer), `text?`, `x?`, `y?`, `width?`, `height?`
+
+## Events
+
+```typescript
+const result = await extract({
+  artifacts,
+  schema,
+  strategy,
+  events: {
+    onStep: ({ step, total, label, detail }) => {
+      console.log(`[${step}/${total}] ${label} ${detail || ""}`);
+      // label examples: "extract", "Read manifest.json", "Set Output", "agent_explore"
+    },
+    onRetry: ({ attempt, maxAttempts, reason }) => {
+      console.warn(`Retry ${attempt}/${maxAttempts}: ${reason}`);
+    },
+    onTokenUsage: ({ inputTokens, outputTokens, totalTokens, model }) => {
+      console.log(`Tokens: ${totalTokens} (${model})`);
+    },
+    onMessage: ({ role, content }) => { /* full LLM messages */ },
+    onProgress: ({ current, total, percent }) => { /* batch progress */ },
+  },
+});
+```
+
+## Custom Strategy
+
+```typescript
+import type { ExtractionStrategy, ExtractionOptions, ExtractionResult } from "@struktur/sdk";
+
+const myStrategy: ExtractionStrategy<Output> = {
+  name: "my-strategy",
+  getEstimatedSteps: (artifacts) => 3,
+  async run(options: ExtractionOptions<Output>): Promise<ExtractionResult<Output>> {
+    return {
+      data: { /* ... */ },
+      usage: { inputTokens: 0, outputTokens: 0, totalTokens: 0 },
+    };
+  },
+};
+```
+
+## CLI
+
+```bash
+# Extract with agent (default) — no --strategy needed
+struktur extract --input ./document.pdf --schema ./schema.json
+
+# Extract with specific model
+struktur extract -i document.txt -s schema.json -m anthropic/claude-sonnet-4
+
+# Extract with max steps limit
+struktur extract -i docs.pdf -s schema.json -m anthropic/claude-sonnet-4 --max-steps 30
+
+# Extract with inline text
+struktur extract -t "Invoice #1234, total $99" -f "invoice_number, total:number"
+
+# Use traditional strategy (for specific cases)
+struktur extract -i docs.txt -s schema.json -S parallel --chunk-size 8000
+
+# Pipe stdin
+cat document.txt | struktur extract -f "title, summary" -m anthropic/claude-sonnet-4
+
+# Debug mode (verbose JSON logs to stderr)
+struktur extract --debug -t "text" -s schema.json
+
+# Model management
+struktur models list
+struktur models use anthropic/claude-sonnet-4          # set default model
+struktur models alias set fast anthropic/claude-haiku-4
+struktur models alias set smart anthropic/claude-opus-4
+struktur extract -t "text" -f "title" -m fast  # use alias
+
+# Provider setup
+struktur providers add anthropic --token sk-ant-...
+struktur providers add openai --token sk-...
+struktur providers list
+```
+
+**Model format**: `provider/model-name`  
+**Providers**: `anthropic`, `openai`, `google`, `opencode`, `openrouter`  
+**OpenRouter provider routing**: `openrouter/anthropic/claude-3.5-sonnet#cerebras`
+
+## Agent TUI
+
+When using the agent strategy in the CLI, you'll see a live TUI showing:
+
+```
+  ◈  Read manifest.json
+  ◉  Grep "property"  in artifact.json
+  ◐  Set Output  {"real_estate_property":{"name":"Dock 100"...
+  ◆  Bash: head -20 /artifacts/artifact.json
+  ▸  Now let me add the building details
+  ◑  Update Output  {"buildings":[...
+⠋ Agent: completing...
+```
+
+**Icons:**
+- ▸ model thinking/exploring
+- ◈ read file / agent lifecycle
+- ◆ bash command
+- ◉ grep search
+- ◊ find files
+- ◇ list directory
+- ◐ set output data
+- ◑ update output data
+- ◒ finish extraction
+- ◓ fail extraction
+
+## Internal Architecture
+
+**Agent Strategy:**
+```
+extract()
+  → agent.run()
+     → VirtualFilesystem         (src/agent-strategy/ArtifactFilesystem.ts)
+        → Tool definitions       (src/agent-strategy/AgentTools.ts)
+           → Agent session       (@mariozechner/pi-coding-agent)
+              → Tool calls       (read, grep, find, ls, bash)
+              → Output updates   (set_output_data, update_output_data)
+                 → Validation    (schema check + retry)
+                    → finish()   (return validated JSON)
+```
+
+**Traditional Strategies:**
+```
+extract()
+  → strategy.run()
+     → batchArtifacts() / splitArtifact()   (src/chunking/)
+        → buildExtractorPrompt()             (src/prompts/)
+           → runWithRetries()                (src/llm/)
+              → generateStructured()         (Vercel AI SDK)
+               → schema validation / retry
+              → merge / dedupe               (src/merge/)
+```
+
+**Key modules**:
+- `packages/agent-strategy/` — Agent strategy with virtual filesystem
+- `packages/sdk/src/strategies/` — Traditional strategy implementations
+- `packages/sdk/src/artifacts/` — `fileToArtifact`, `urlToArtifact`, `parseInputToArtifacts`
+- `packages/sdk/src/chunking/` — `ArtifactSplitter`, `ArtifactBatcher`
+- `packages/sdk/src/llm/` — `LLMClient`, `RetryingRunner`, `models`
+- `packages/sdk/src/prompts/` — `ExtractorPrompt`, `SequentialExtractorPrompt`, `ParallelMergerPrompt`
+- `packages/sdk/src/merge/` — `SmartDataMerger`, `Deduplicator`
+- `packages/sdk/src/validation/` — schema validator, `SchemaValidationError`
+- `packages/sdk/src/auth/` — token storage, alias/default model config
+- `packages/sdk/src/debug/` — structured JSON logger
+
+## Patterns
+
+**Agent strategy best practices:**
+- Always try agent first — it's the default for a reason
+- Use models with strong tool-calling (Claude 3.5 Sonnet, GPT-4o)
+- Adjust `maxSteps` if the agent needs more exploration time (default: 50)
+- Use traditional strategies only when you need predictable costs or specific chunking
+
+**Merge rules** (SmartDataMerger): arrays concatenate, objects shallow-merge, scalars prefer newest value.
+
+**Validation retries**: `runWithRetries` feeds validation errors back to the LLM (max 3 attempts). `onRetry` fires with `{ attempt, maxAttempts, reason }`.
+
+**Token budget**: `chunkSize` is in tokens. Default `10_000`. Images default to 1000 tokens each. Adjust `maxImages` to control multimodal batch costs.
+
+**Schema strict mode**: Pass `strict: true` to use OpenAI's `strictJsonSchema` — requires `additionalProperties: false` everywhere and no `$ref`.
+
+**Fields shorthand** builds a JSON Schema automatically. Use for quick CLIs or simple schemas; use `JSONSchemaType<T>` for full type inference.
+
+**Debug logs**: Single-line JSON to stderr. Types include `cli_init`, `artifacts_loaded`, `batching_complete`, `llm_call_start`, `llm_call_complete`, `validation_failed`, `retry`, `merge_start`, `extraction_complete`.
+
+## Tests
+
+```bash
+bun test                        # run all tests
+bun test packages/agent-strategy/  # agent strategy tests
+bun test packages/sdk/src/strategies/  # traditional strategy tests
+```
+
+Tests are colocated: `foo.ts` → `foo.test.ts`. Add or update tests whenever behavior changes.