feat: add CLI contract workflows

- Add assistant prompt contracts with built-in and file-backed validation plus one repair attempt
- Add opt-in JSON error envelopes via `--error-format json` and `KAGI_ERROR_FORMAT=json`
- Resolve `kagi search --lens` exact enabled lens names to the current numeric position
- Add `kagi extract --filter` JSONL mode for stdin URL pipelines
- Update `quinn-proto` in `Cargo.lock` to satisfy the RustSec audit gate

Author: Microck

.facts

@@ -0,0 +1,29 @@
+
+# domain
+- a Contract is a prompt-mode output shape that the assistant command asks Kagi Assistant to return as JSON and validates before printing
+- an ErrorEnvelope is an opt-in JSON stderr object for command failures with stable code, category, retryable, message, and suggested_commands fields
+
+# cli
+
+## assistant
+- label: kagi assistant --contract decision validates the final assistant reply as a JSON object containing decision, rationale, and next_actions before printing it
+  command: cargo test --test integration-cli assistant_contract_decision_prints_validated_json -- --exact
+  tags: [implemented]
+- label: kagi assistant --contract-file accepts a small JSON contract file with required top-level string keys and rejects assistant replies that do not satisfy it
+  command: cargo test --test integration-cli assistant_contract_file_rejects_missing_required_key -- --exact
+  tags: [implemented]
+
+## errors
+- label: runtime command failures can opt into JSON stderr with --error-format json or KAGI_ERROR_FORMAT=json
+  command: cargo test --test integration-cli json_error_format_prints_structured_stderr -- --exact
+  tags: [implemented]
+
+## search
+- label: kagi search --lens accepts an enabled lens exact name, resolves it through the authenticated lens settings page, and sends the current numeric lens position to search
+  command: cargo test --test integration-cli search_lens_name_resolves_to_current_position -- --exact
+  tags: [implemented]
+
+## extract
+- label: kagi extract --filter reads HTTPS URLs from stdin and writes one compact JSONL record per input in order, including per-item errors without corrupting stdout
+  command: cargo test --test integration-cli extract_filter_prints_ordered_jsonl_records -- --exact
+  tags: [implemented]

Cargo.lock

@@ -14,6 +14,8 @@ Prompt Kagi Assistant, continue an existing thread, use a saved assistant profil
 ```bash
 kagi assistant [OPTIONS] <QUERY>
 kagi assistant --stream [--stream-output text|json] <QUERY>
+kagi assistant --contract decision <QUERY>
+kagi assistant --contract-file ./contract.json <QUERY>
 kagi assistant thread list
 kagi assistant thread get <THREAD_ID>
 kagi assistant thread delete <THREAD_ID>
@@ -76,6 +78,39 @@ kagi assistant --format pretty "What changed in Rust 1.86?"
 kagi assistant --format markdown "Write a release summary"
 ```
 
+#### `--contract <NAME>`
+
+Ask Assistant to return only JSON that satisfies a built-in contract, then validate the final reply before printing it. Contract mode supports `--format json` and `--format compact`.
+
+Supported built-ins:
+
+- `decision` - requires `decision`, `rationale`, and `next_actions`
+- `checklist` - requires `items`
+- `plan` - requires `steps`
+
+```bash
+kagi assistant --contract decision "Should we ship this release?"
+```
+
+If the first reply is invalid, the CLI sends one repair prompt in the same thread. If the repaired reply still fails validation, the command exits with a contract error.
+
+#### `--contract-file <PATH>`
+
+Load a small JSON contract file. The supported subset is a top-level object with `required` and optional `properties.<key>.type` fields:
+
+```json
+{
+  "type": "object",
+  "required": ["summary", "verdict"],
+  "properties": {
+    "summary": { "type": "string" },
+    "verdict": { "type": "string" }
+  }
+}
+```
+
+Required entries default to `string` when `properties` does not specify a type. Supported types are `string`, `number`, `integer`, `boolean`, `object`, and `array`.
+
 #### `--no-color`
 
 Disable ANSI colors in `--format pretty`.
@@ -289,6 +324,16 @@ Prompt mode returns:
 }
 ```
 
+Contract mode returns only the validated contract JSON, not the normal Assistant envelope:
+
+```json
+{
+  "decision": "ship",
+  "rationale": "tests pass",
+  "next_actions": ["open PR"]
+}
+```
+
 `thread list` returns:
 
 ```json

docs/commands/assistant.mdx

@@ -11,6 +11,7 @@ Extract the readable content of a web page as markdown using Kagi's Extract API.
 
 ```bash
 kagi extract <URL> [--format markdown|json|compact]
+kagi extract --filter
 ```
 
 ## Description
@@ -19,6 +20,8 @@ The `kagi extract` command sends one HTTPS URL to Kagi's v1 Extract API and prin
 
 The command uses JSON mode internally because that is the stable envelope returned by the API, then prints the first page's `markdown` field. Use `--format json` or `--format compact` to print the full response envelope, including retained link metadata when Kagi returns it. If Kagi returns no page markdown, the CLI reports the Extract API error details and trace id when available.
 
+Use `--filter` for pipelines that already have one URL per line. Filter mode ignores the single-URL markdown default and prints one compact JSON record per input line in the same order. Successful records include the Extract API response under `response`. Failed records include an `error` envelope on stdout and the command exits nonzero after all inputs are processed.
+
 ## Authentication
 
 **Required:** `KAGI_API_KEY`
@@ -37,6 +40,16 @@ kagi extract "https://example.com/article"
 
 Only `https://` URLs with a valid host are accepted.
 
+Omit `<URL>` when using `--filter`.
+
+### `--filter`
+
+Read one URL per stdin line and print JSONL records.
+
+```bash
+kagi search "rust release notes" --template '{{url}}' | kagi extract --filter
+```
+
 ### `--format <FORMAT>`
 
 Output format. Default: `markdown`.
@@ -81,6 +94,13 @@ With `--format json`, the command prints the full response envelope:
 }
 ```
 
+With `--filter`, stdout is JSONL:
+
+```jsonl
+{"url":"https://example.com/article","ok":true,"response":{"meta":{"trace":"trace-1","node":"test","ms":12},"data":[{"url":"https://example.com/article","markdown":"# Article title\n\nExtracted page content...","links":[]}]}}
+{"url":"http://example.com/bad","ok":false,"error":{"code":"configuration_error","category":"configuration","retryable":false,"message":"configuration error: extract URL must use the https scheme","suggested_commands":[],"docs_url":"https://kagi.micr.dev/reference/error-reference"}}
+```
+
 ## Examples
 
 ### Save an Article
@@ -101,12 +121,18 @@ kagi extract "https://example.com/article" | sed -n '1,80p'
 kagi extract "https://example.com/article" --format json | jq '.data[0].links'
 ```
 
+### Extract Search Results
+
+```bash
+kagi search "rust async cancellation" --template '{{url}}' | kagi extract --filter > pages.jsonl
+```
+
 ## Exit Codes
 
 | Code | Meaning |
 |------|---------|
-| 0 | Success - markdown extracted |
-| 1 | Error - see stderr |
+| 0 | Success - markdown extracted, or every `--filter` input produced an `ok: true` record |
+| 1 | Error - see stderr; `--filter` may still have written per-input records to stdout |
 
 Common errors:
 

docs/commands/extract.mdx

@@ -93,14 +93,17 @@ kagi search --snap reddit "rust async runtime"
 kagi search --snap @map "coffee near london bridge"
 ```
 
-### `--lens <INDEX>`
+### `--lens <INDEX_OR_NAME>`
 
-Scope search to one of your enabled Kagi lenses.
+Scope search to one of your enabled Kagi lenses. Numeric values keep the existing index behavior. Non-numeric values are matched against enabled lens names exactly at runtime, then resolved to the current account-specific numeric position before search.
 
 ```bash
 kagi search --lens 2 "developer documentation"
+kagi search --lens "Rust Docs" "borrow checker examples"
 ```
 
+If a name is missing, disabled, or duplicated, the command fails before search and points you to `kagi lens list` or the numeric index path. Numeric-looking names are treated as numeric indexes.
+
 ### `--region <REGION>`
 
 Restrict results to a Kagi region code such as `us`, `gb`, `jp`, or `no_region`.
@@ -361,7 +364,10 @@ kagi search --format markdown "rust ownership"
 - `this search option requires KAGI_SESSION_TOKEN` - you used a web-product-only search option without a session token
 - `search --time cannot be combined with --from-date or --to-date` - choose a preset window or a custom date range
 - `search --from-date must use YYYY-MM-DD format` - dates must be zero-padded ISO dates
-- `lens 'foo' must be a numeric index` - lens values are numeric Kagi lens indices
+- `lens named 'foo' was not found` - named lens search matches enabled lens names exactly. Run `kagi lens list`
+- `lens name 'foo' is ambiguous` - multiple lenses have that exact name. Use the numeric index
+- `lens named 'foo' is disabled` - enable it with `kagi lens enable <ID_OR_NAME>` or choose an enabled lens
+- `lens 'foo' must be a numeric index` - internal numeric validation still applies after named lenses are resolved
 
 ## Related Commands
 

docs/commands/search.mdx

@@ -16,7 +16,7 @@ These endpoints come from Kagi's current OpenAPI contract at `https://kagi.com/a
 | Endpoint | Command | Status |
 |----------|---------|--------|
 | Search API (`POST /api/v1/search`) | `kagi search` | ✅ Implemented for query, limit, and `filters.region/after/before` |
-| Extract API | `kagi extract` | ✅ Implemented |
+| Extract API | `kagi extract` | ✅ Implemented, including stdin URL filter mode |
 
 Current V1 Search optional fields not exposed by this CLI: `workflow`, API response `format`, `lens_id`, inline `lens`, `timeout`, `page`, search-result `extract`, `safe_search`, and explicit personalization rule objects. Subscriber web-product features cover some adjacent workflows, but they are not represented as V1 OpenAPI request fields.
 
@@ -39,12 +39,12 @@ These features use the subscriber web product with `KAGI_SESSION_TOKEN`:
 |---------|---------|--------|
 | Base search | `kagi search` | ✅ Implemented |
 | Snap-prefixed search | `kagi search --snap` | ✅ Implemented |
-| Lens search | `kagi search --lens` | ✅ Implemented |
+| Lens search | `kagi search --lens` | ✅ Implemented for numeric indexes and exact enabled lens names |
 | Filtered search | `kagi search --region/--from-date/--to-date` on V1 API or session path; `--time/--order/...` on session path | ✅ Implemented |
 | Quick Answer | `kagi quick` | ✅ Implemented |
 | Web Summarizer | `kagi summarize --subscriber` | ✅ Implemented |
 | Search result summarize pipeline | `kagi search --follow` | ✅ Implemented |
-| Assistant prompt + thread management | `kagi assistant` | ✅ Implemented |
+| Assistant prompt + thread management | `kagi assistant` | ✅ Implemented, including prompt contracts |
 | Assistant terminal REPL | `kagi assistant repl` | ✅ Implemented |
 | Custom assistant management | `kagi assistant custom` | ✅ Implemented |
 | Ask questions about a page | `kagi ask-page` | ✅ Implemented |
@@ -71,7 +71,7 @@ These require no authentication:
 |---------|-------------|------|--------|
 | `search` | Base Kagi search | API or Session | ✅ |
 | `search --snap` | Snap-prefixed search | API or Session | ✅ |
-| `search --lens` | Lens-aware search | Session | ✅ |
+| `search --lens` | Lens-aware search by numeric index or exact enabled name | Session | ✅ |
 | `search` with filters | Region, time, date, order, verbatim, personalization filters | Session | ✅ |
 | `search --template` | Lightweight result templates | API or Session | ✅ |
 | `search --follow` | Search plus subscriber summaries for top results | Session | ✅ |
@@ -83,7 +83,7 @@ These require no authentication:
 | `summarize` | Public API summarizer | API | ✅ |
 | `summarize --subscriber` | Web summarizer | Session | ✅ |
 | `summarize --filter` | Summarize stdin items as URLs or text | API or Session | ✅ |
-| `extract` | Extract page content as markdown | API | ✅ |
+| `extract` | Extract page content as markdown or stdin URL JSONL records | API | ✅ |
 | `watch` | Search diff monitoring | API or Session | ✅ |
 | `notify` | Webhook notifications for search/news | API, Session, or None | ✅ |
 | `history` | Local history and stats | None | ✅ |
@@ -130,19 +130,22 @@ These require no authentication:
 | `--personalized` / `--no-personalized` | search, batch, assistant | ✅ |
 | `--template` | search, batch | ✅ |
 | `--local-cache` / `--cache-ttl` | search, summarize, quick, fastgpt | ✅ |
+| `--error-format` | global | Implemented |
 
 ### Assistant and Settings Options
 
 | Option | Commands | Status |
 |--------|----------|--------|
 | `--assistant` | assistant | ✅ |
+| `--contract` / `--contract-file` | assistant | Implemented |
 | `--thread-id` | assistant | ✅ |
 | `--model` | assistant, assistant custom | ✅ |
 | `--lens` | assistant, assistant custom | ✅ |
 | `--web-access` / `--no-web-access` | assistant, assistant custom | ✅ |
 | `thread list/get/delete/export` | assistant | ✅ |
 | `custom list/get/create/update/delete` | assistant | ✅ |
 | `repl` | assistant | ✅ |
+| `--filter` | extract | Implemented |
 | `list/get/create/update/delete` | lens | ✅ |
 | `enable` / `disable` | lens, redirect | ✅ |
 | `custom list/get/create/update/delete` | bang | ✅ |

docs/reference/coverage.mdx

@@ -9,7 +9,7 @@ This guide catalogs all error messages from the *kagi* CLI, organized by categor
 
 ## Error Format
 
-Errors follow this pattern:
+Plain text errors follow this pattern:
 
 ```
 Error: {category}: {message}
@@ -31,6 +31,27 @@ Transport errors include the request URL when the HTTP client exposes it:
 Error: Network error: request to https://kagi.com/api/v1/search timed out after the configured timeout
 ```
 
+Automation can request compact JSON stderr instead:
+
+```bash
+kagi --error-format json search "rust"
+KAGI_ERROR_FORMAT=json kagi search "rust"
+```
+
+The JSON error envelope uses stable top-level fields:
+
+```json
+{
+  "code": "missing_credentials",
+  "category": "configuration",
+  "retryable": false,
+  "message": "configuration error: missing credentials: search was not sent...",
+  "required_auth": "KAGI_API_KEY or KAGI_SESSION_TOKEN",
+  "suggested_commands": ["kagi auth status", "kagi auth set --api-key <key>", "kagi auth set --session-token <token>"],
+  "docs_url": "https://kagi.micr.dev/reference/error-reference"
+}
+```
+
 ## Authentication Errors
 
 ### "missing credentials"
@@ -269,22 +290,25 @@ Error: Config: --length requires --subscriber
 kagi summarize --subscriber --url https://example.com --length digest
 ```
 
-### "lens 'abc' must be a numeric index"
+### "lens named 'abc' was not found"
 
 **Message:**
 ```
-configuration error: lens 'abc' must be a numeric index (e.g., '0', '1', '2').
+configuration error: lens named 'abc' was not found. Lens names are matched exactly; run `kagi lens list` to inspect available lenses
 ```
 
-**Meaning:** Lens-aware commands only accept the numeric `l=` value from Kagi's web UI.
+**Meaning:** `kagi search --lens` was given a non-numeric value, but no enabled lens has that exact name.
 
 **Solution:**
 ```bash
-# Search
-kagi search --lens 2 "developer documentation"
+kagi lens list
+kagi search --lens "Exact Lens Name" "developer documentation"
+```
 
-# Quick Answer
-kagi quick --lens 2 "best rust tutorials"
+Use a numeric index when names are duplicated or numeric-looking:
+
+```bash
+kagi search --lens 2 "developer documentation"
 ```
 
 ### "--engine is only supported for the paid public summarizer API"