@aiaiai-pt/frankctl 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/frankctl",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Terminal-first client for the Frank Low-Code Pipeline platform",
   "homepage": "https://franksdocs.nomadriver.co",
   "repository": {

package/skills/frank-cli/SKILL.md

@@ -1,170 +1,242 @@
 ---
 name: frank-cli
-description: Use the frankctl CLI to interact with the Frank API — auth, config, pipelines, sources, transforms, runs
+description: Use the frankctl CLI to provision Frank pipelines declaratively — apply/scaffold/export multi-doc YAML — plus auth, sources, transforms, backing datasets, and runs
 ---
 
-# frankctl (Frank CLI) — Phase 1
+# frankctl — the Frank CLI
 
-## 1. Overview
+`frankctl` is the command-line client for the Frank platform: a scriptable, repeatable
+way to build and operate end-to-end data pipelines — Sources (Extract/Load into an
+Iceberg bronze lakehouse), Transforms/Pipelines (bronze → silver/gold), and Backing
+Datasets (silver → ontology entities).
 
-`frankctl` is a TypeScript CLI that gives humans and agents scriptable access to the Frank API: authentication against Keycloak, config/profile management, and the core data-flow surface — pipelines, sources, transforms, and runs. Version: `0.2.0`.
+It is built for two audiences: developers scripting Frank from a terminal or CI, and
+agents composing and self-checking pipelines without a UI. Every command speaks the
+public Frank API and authenticates against Keycloak.
 
-## 2. When to use
+The heart of the tool is **declarative provisioning**: describe a whole pipeline in one
+YAML file and `apply` it idempotently. Reach for the imperative subcommands
+(`sources`, `transforms`, …) for inspection, one-off actions, and debugging — but let
+YAML be your source of truth.
 
-- Before activating a pipeline: `frankctl pipelines validate <id>` to run it end-to-end in sandbox mode, stream step badges to stderr, emit a final JSON summary on stdout.
-- Scripting against Frank from bash/CI: `$(frankctl auth token)` injects a fresh access token into any `curl` call.
-- Agents composing pipelines via Martha can self-check their work without going through the UI.
-
-## 3. Installation & binary location
+## Install
 
 ```bash
-cd /home/ork/harnasso/frank/frank-cli
-npm install
-npm run build
-npm link    # installs `frankctl` on PATH
+npm install -g @aiaiai-pt/frankctl
+frankctl --version
 ```
 
-The built entry point is `dist/index.js` (ESM, esbuild-bundled, `#!/usr/bin/env node` shebang). Node ≥18 required.
+Node ≥18. The binary is `frankctl`. Docs: https://franksdocs.nomadriver.co
 
-## 4. First-run setup
+## Connect & authenticate
 
 ```bash
-frankctl status                    # shows defaults, unauthenticated
-frankctl auth login                # browser PKCE flow (default)
-frankctl auth status               # confirms subject + tenant
-frankctl pipelines list
+frankctl status              # effective config + whether you're logged in
+frankctl auth login          # browser PKCE flow (opens Keycloak)
+frankctl auth status         # confirms your subject + tenant
 ```
 
-Credentials are written to `~/.frankctl/credentials.json` (0o600).
+Point it at an environment by setting the API URL once (or per-invocation with
+`--api-url`):
 
-## 5. Global options
+```bash
+frankctl config set profiles.default.apiUrl https://api.frank.nomadriver.co
+frankctl config set profiles.default.keycloakUrl https://auth.frank.nomadriver.co
+```
 
-Available on every subcommand:
+Auth modes:
+- **PKCE (default)** — `frankctl auth login`. Browser-based, best for humans.
+- **Headless** — `frankctl auth login --headless --username … --password …`. For containers/CI.
+- **Service account** — `frankctl auth login --service-account --client-id … --client-secret …`.
 
-| Flag | Purpose |
-|------|---------|
-| `-p, --profile <name>` | Select config profile (default: `default`) |
-| `--json` | Emit machine-readable JSON to stdout |
-| `-v, --verbose` | Verbose logging (stderr) |
-| `-q, --quiet` | Suppress non-error output |
-| `--no-color` | Disable ANSI colors |
-| `--api-url <url>` | Override API base URL for this invocation |
+Tokens are stored per-profile at `~/.frankctl/credentials.json` (0600) and refresh
+automatically before expiry. In scripts, inject a fresh token instead of reading the
+file:
 
-## 6. Environment variables
+```bash
+TOKEN=$(frankctl auth token)
+curl -H "Authorization: Bearer $TOKEN" https://api.frank.nomadriver.co/api/v1/pipelines
+```
 
-| Var | Effect |
-|-----|--------|
-| `FRANKCTL_API_URL` | Override `apiUrl` |
-| `FRANKCTL_KEYCLOAK_URL` | Override `keycloakUrl` |
-| `FRANKCTL_KEYCLOAK_REALM` | Override `realm` |
-| `FRANKCTL_CLIENT_ID` | Override `clientId` |
-| `FRANKCTL_CLIENT_SECRET` | Service-account secret |
-| `FRANKCTL_PROFILE` | Active profile |
-| `FRANKCTL_TOKEN` | Bypass token store; use this raw JWT |
-| `FRANK_DEV_MODE=true` + `FRANKCTL_TENANT_ID` | Forward `X-Tenant-ID` header |
+---
 
-## 7. Profiles & `~/.frankctl/config.yaml`
+## Declarative pipelines — the repeatable path
 
-```yaml
-defaultProfile: default
-profiles:
-  default:
-    apiUrl: http://localhost:8000
-    keycloakUrl: http://localhost:8180
-    realm: frank
-    clientId: frank-low-code
-  prod:
-    apiUrl: https://frank.prod.example
-    keycloakUrl: https://kc.prod.example
-    realm: frank
-    clientId: frank-low-code
-```
+A pipeline is one multi-document YAML file describing three kinds of object under the
+`frank.platform/v1` API version:
+
+| `kind` | Role |
+|--------|------|
+| `Source` | Extract/Load config — connector `pattern_id`, streams, schedule → Iceberg **bronze** |
+| `Pipeline` | Transform steps (SQL/Python) turning bronze → **silver/gold** |
+| `BackingDataset` | Maps a silver table's columns to **ontology** entity properties |
+
+Objects reference each other by `metadata.name`, so one file is self-contained and
+version-controllable. Commit these files to git — they *are* your infrastructure.
 
-Precedence (top wins): CLI flag → env → YAML → built-in default.
+### The loop: scaffold → edit → apply
 
-## 8. Auth flows
+**1. Scaffold** a starter manifest from a source you've already synced. Frank reads the
+real physical bronze schema and pre-fills the SQL with the actual Trino `ROW` refs:
 
-- **PKCE (default)** — browser-based, best for humans. Requires a free port in `[5173, 4173, 5174]` (matches the `frank-low-code` Keycloak client's registered redirect URIs).
-- **Headless (ROPC)** — `frankctl auth login --headless --username ... --password ...`. Uses `frank-low-code` public client.
-- **Service account** — `frankctl auth login --service-account --client-id frank-api --client-secret $S`. Uses `client_credentials` grant.
+```bash
+frankctl pipelines scaffold --source ipma_indice_uv -o pipeline.yaml
+```
 
-## 9. Token handling
+**2. Edit** `pipeline.yaml`. Usually the only required change is naming the ontology
+entity (`BackingDataset.entity_type_id` / `entity_type_name`); optionally refine the
+`primary_key_column`, add casts, or tune the SELECT.
 
-- Tokens refresh automatically 30s before expiry.
-- Service-account tokens re-acquire via `client_credentials` when `FRANKCTL_CLIENT_SECRET` is set.
-- Agents should use `TOKEN=$(frankctl auth token)` rather than reading the credentials file.
+**3. Apply** it idempotently. Re-running is safe — Frank reconciles to the declared
+state rather than creating duplicates:
+
+```bash
+frankctl pipelines apply -f pipeline.yaml
+```
 
-## 10. `frankctl status`
+Add `--wait` to drive the whole chain to completion and let a non-zero exit mean "it
+didn't land": sync Sources → bronze, materialize Pipeline steps → silver, sync Backing
+Datasets → ontology.
 
-Prints version, active profile, URLs, and authentication state. `--json` mirrors all fields.
+```bash
+frankctl pipelines apply -f pipeline.yaml --wait --timeout 600
+```
 
-## 11. `frankctl auth`
+### Preflight before you apply
 
-- `login [--headless | --service-account] [--username --password --client-id --client-secret --no-browser]`
-- `logout` — deletes credentials for active profile.
-- `status` — exits 3 if not logged in.
-- `token` — prints a valid access token to stdout.
+| Flag | What it does |
+|------|--------------|
+| `--dry-run` | Client-side parse + cross-ref resolve. Catches malformed YAML and broken references. No server call. |
+| `--dry-run-server` | Server-side preflight against the catalog + DB without persisting. Catches unknown `pattern_id`s, would-be immutable-diff conflicts, and unresolved refs. |
 
-## 12. `frankctl config`
+Run `--dry-run-server` in CI on every change; run `apply --wait` to promote.
 
-- `config set <key> <value>` — dotted key (e.g. `profiles.default.apiUrl`).
-- `config get <key>` — returns `{value, source}` where source ∈ `flag | env | config | default`.
-- `config list` — merged effective profile.
+### Immutable state & when to force
 
-## 13. `frankctl pipelines list`
+Backing Datasets carry operational state (ontology cursor, sync history). If a change
+would require destroying that state, `apply` returns `409 immutable_diff` and stops —
+it will not silently discard your data. Two explicit opt-ins exist for when you *do*
+mean it:
 
-`GET /api/v1/pipelines` with optional `--status`, `--search`, `--page`, `--page-size`. Table output by default; `--json` returns the full `PipelineListResponse`.
+- `--allow-recreate` — DELETE the conflicting row and re-create. **Loses** cursor,
+  ledger, snapshot ids, and run history. Use knowingly.
+- `--allow-deprecate` — permit an `ensure_schema` that narrows the ontology schema.
 
-## 14. `frankctl pipelines get <id>`
+Without these, `apply` is fully idempotent.
 
-`GET /api/v1/pipelines/{id}`. Optional `--include-version` to include the active version payload.
+### Export existing work back to YAML
 
-## 15. `frankctl pipelines validate <id>`
+Already built a pipeline in the UI? Pull it — plus its Sources and Backing Datasets —
+into a manifest you can commit and re-apply elsewhere:
 
-`POST /api/v1/pipelines/{id}/sandbox` then polls `/sandbox/{wf}/status` every 2500 ms (`--poll-interval` to override). Step badges stream to **stderr**; the final status JSON is written to **stdout**.
+```bash
+frankctl pipelines export <pipeline-id> > pipeline.yaml
+```
 
-Flags: `--sample-limit <n=1000> --timeout <sec=600> --no-wait`.
+### Minimal manifest shape
 
-Exit codes: `completed` → 0, `partial_failure | failed` → 5.
+```yaml
+apiVersion: frank.platform/v1
+kind: Source
+metadata:
+  name: ipma_indice_uv
+spec:
+  pattern_id: ipma
+  source_config:
+    streams: [uv_index]
+  streams:
+    - name: ipma_uv_index
+      sync_mode: full_refresh
+      write_disposition: replace
+  schedule_type: cron
+  schedule_value: "0 6 * * *"
+---
+apiVersion: frank.platform/v1
+kind: Pipeline
+metadata:
+  name: ipma_indice_uv_pipeline
+spec:
+  source_ids: [ipma_indice_uv]
+  steps:
+    - name: ipma_indice_uv_silver
+      kind: custom_sql
+      sources: [bronze.tenant_00000000_ipma_indice_uv.ipma_uv_index]
+      emits_to: backing_dataset
+      config: { output_layer: silver }
+      params:
+        sql: |-
+          SELECT o."date" AS date, o."uv_index" AS uv_index, o."record_key" AS record_key
+          FROM tenant_00000000_ipma_indice_uv.ipma_uv_index o
+---
+apiVersion: frank.platform/v1
+kind: BackingDataset
+metadata:
+  name: uv_index_forecast
+spec:
+  entity_type_id: uv_index_forecast
+  entity_type_name: UV Index Forecast
+  pipeline: ipma_indice_uv_pipeline
+  sync_mode: on_materialization
+  primary_key_column: record_key
+  property_mappings:
+    - { column: date, property: date, type: date }
+    - { column: uv_index, property: uv_index, type: long }
+```
 
-## 16. JSON output contracts
+---
 
-- `--json` on `list`/`get`/`status`/`auth status`/`config *` emits a single JSON object/array on stdout.
-- `validate` always emits the final sandbox status as JSON on stdout, regardless of `--json`.
+## Global options
 
-## 17. Exit codes
+Available on every subcommand:
 
-| Code | Meaning |
+| Flag | Purpose |
 |------|---------|
-| 0 | Success |
-| 1 | Generic error |
-| 2 | Usage error |
-| 3 | Authentication error |
-| 4 | API error (non-2xx) |
-| 5 | Validation failed |
+| `-p, --profile <name>` | Select config profile (default: `default`) |
+| `--json` | Emit machine-readable JSON to stdout |
+| `-v, --verbose` | Verbose logging (stderr) |
+| `-q, --quiet` | Suppress non-error output |
+| `--no-color` | Disable ANSI colors |
+| `--api-url <url>` | Override the API base URL for this invocation |
 
-## 18. Errors & troubleshooting
+### Environment variables
 
-- FastAPI returns `{detail: str}` or `{detail: [...]}` — both shapes are normalized.
-- `401` triggers a single token refresh + retry before surfacing.
-- Port binding failure on PKCE prints the candidate list — use `--headless` in containers.
+| Var | Effect |
+|-----|--------|
+| `FRANKCTL_API_URL` | Override `apiUrl` |
+| `FRANKCTL_KEYCLOAK_URL` | Override `keycloakUrl` |
+| `FRANKCTL_KEYCLOAK_REALM` | Override `realm` |
+| `FRANKCTL_CLIENT_ID` / `FRANKCTL_CLIENT_SECRET` | Client id / service-account secret |
+| `FRANKCTL_PROFILE` | Active profile |
+| `FRANKCTL_TOKEN` | Use this raw JWT instead of the token store |
+
+### Profiles (`~/.frankctl/config.yaml`)
 
-## 19. Dev mode
+```yaml
+defaultProfile: default
+profiles:
+  default:
+    apiUrl: https://api.frank.nomadriver.co
+    keycloakUrl: https://auth.frank.nomadriver.co
+    realm: frank
+    clientId: frank-low-code
+```
 
-Setting `FRANK_DEV_MODE=true` + `FRANKCTL_TENANT_ID=<uuid>` forwards `X-Tenant-ID` to bypass JWT-based tenant resolution (dev only).
+Precedence (top wins): CLI flag → env var → YAML → built-in default.
+`config get <key>` reports `{value, source}` so you can see which layer won;
+`config list` prints the merged effective profile.
 
-## 20. Relationship to `frank-pattern` (Python)
+---
 
-The existing Python `frank` CLI in `utils/frank_cli/` handles pattern authoring (`init|validate|test|build`) and is being renamed to `frank-pattern` in a follow-up PR on the `frank-shared-utils` submodule. The TS `frankctl` and Python `frank-pattern` are orthogonal: different domains, different binaries.
+## Command reference
 
-## 20b. Data-flow subtrees (WEC-133)
+Use these to inspect and act on what `apply` provisioned, and to debug.
 
-### `sources`
+### Sources (Extract/Load → bronze)
 
 ```bash
 frankctl sources list [--type <pattern-id>] [--status <s>] [--search <q>]
 frankctl sources get <id> [--no-streams]
-frankctl sources create -f source.yaml [--name ...] [--type ...]
+frankctl sources create -f source.yaml           # {name, pattern_id, source_config}
 frankctl sources update <id> -f patch.yaml
 frankctl sources delete <id> --yes
 frankctl sources discover <id> [--no-wait] [--timeout <s>]
@@ -175,149 +247,134 @@ frankctl sources history <id> [--limit N] [--offset N]
 frankctl sources streams list <source-id> [--enabled-only]
 frankctl sources streams set <source-id> -f streams.yaml
 frankctl sources streams refresh-schema <source-id> --from-discovery
-frankctl sources streams refresh-schema <source-id> -f discovery.json
 ```
 
-`-f` accepts YAML, JSON, or `-` (stdin). `sources create` requires `{name, pattern_id, source_config}`. `sources streams set` body can be a bare array or `{streams: [...]}`.
+`-f` accepts YAML, JSON, or `-` (stdin). `streams set` takes a bare array or `{streams: […]}`.
 
-### `transforms`
+### Pipelines & Transforms (bronze → silver/gold)
 
 ```bash
+frankctl pipelines list [--status <s>] [--search <q>]
+frankctl pipelines get <id> [--include-version]
+frankctl pipelines validate <id>       # sandbox run; badges → stderr, JSON summary → stdout
+frankctl pipelines delete <id>         # does not delete silver tables
+
 frankctl transforms list [--status <s>] [--pipeline-id <id>]
 frankctl transforms get <id>
 frankctl transforms runs <id> [--status] [--limit N]
 frankctl transforms logs <id> <run-id> [-f] [--level]
-frankctl transforms trigger <id>       # UI "Run Now" path
+frankctl transforms trigger <id>       # "Run Now"
 ```
 
-### `runs`
+`pipelines validate` runs the pipeline end-to-end in sandbox mode against a sample and
+streams step results — use it as a pre-activation check.
+
+### Backing Datasets (silver → ontology)
+
+```bash
+frankctl bd list
+frankctl bd get <id>
+frankctl bd create -f bd.yaml
+frankctl bd update <id> -f patch.yaml
+frankctl bd delete <id> --yes          # does not delete underlying data
+frankctl bd sync <id> [--force] [--no-wait]  # trigger ontology sync, poll exact run
+frankctl bd entities <id>              # read entities back out — confirm values landed
+```
+
+`bd entities` closes the authoring loop: it reads the ontology to prove your rows
+actually materialized as entities, not just that the sync reported success.
+`bd sync --force` full-replays through REST even when the snapshot and effective
+mapping spec are unchanged. Normal output includes replay reason, row/snapshot
+evidence, and safe attempted/applied SyncSpec fingerprint prefixes. Human output
+prefers the precision-safe decimal string `snapshot_id_exact`; JSON exposes it
+alongside the legacy numeric `snapshot_id`.
+
+For an ordinary sync, the CLI falls back to BackingDataset status polling when
+an older API does not return exact-run evidence, and clearly marks replay
+evidence unavailable. `--force` does not fall back: it checks
+`/api/v1/backing-datasets/capabilities` before mutation and sends no sync POST
+unless version 2, exact-run polling, and force replay are explicitly supported.
+After the POST, it also requires `force_replay: true` confirmation.
+
+### Runs
 
 ```bash
 frankctl runs get <workflow-id>
 frankctl runs wait <workflow-id> [--timeout <s>] [--poll-interval <ms>]
-frankctl runs cancel <id> --yes        # UUID cascades through transform-runs → sync-runs; non-UUID hits temporal
+frankctl runs cancel <id> --yes
 ```
 
-## 20c. AI subtree (WEC-134)
+### Datasets (browse the lakehouse)
 
 ```bash
-frankctl ai compose-pipeline -f spec.yaml [--no-wait] [--timeout <s>] [--poll-interval <ms>]
-frankctl ai generate-transform -f spec.yaml
-frankctl ai review-sql -f spec.yaml
-frankctl ai fix-ci-failure -f spec.yaml
-frankctl ai suggest target-schema  -f spec.yaml
-frankctl ai suggest field-mappings -f spec.yaml
-frankctl ai suggest pattern-params -f spec.yaml
-frankctl ai publish-transform -f spec.yaml
+frankctl datasets list [--layer bronze|silver|gold] [--namespace <ns>] [--page N]
+frankctl datasets preview <layer.namespace.table> [--limit 20]
+frankctl datasets snapshots <layer.namespace.table>
 ```
 
-All AI commands emit JSON. Every response includes `available: bool`; when `false`, the CLI exits 4 with `AI service unavailable (Martha offline).`.
-
-**compose-pipeline quirks** (observed against the dev stack):
-- With incomplete/unknown `source_tables`, the backend returns `{available:true, execution_id:null, status:"error"}` synchronously. The CLI detects `execution_id==null && !processing` and exits 5 immediately (no poll).
-- With valid inputs, `execution_id` is returned and the CLI polls `/api/v1/ai/compose-pipeline/{id}/status` until `{completed, failed, error, cancelled}` or `--timeout` elapses. Exit 0 on `completed`, 5 on other terminal, 4 on timeout.
+Dataset ids are the 3-part `layer.namespace.table` dotted form used directly in the API
+path. `--json` on `preview` returns `{dataset_id, columns, rows, row_count}`.
 
-## 20d. Patterns subtree (WEC-134)
+### Patterns & schedules
 
 ```bash
 frankctl patterns list [--category <c>] [--search <q>]
 frankctl patterns get <id>
 frankctl patterns validate-params <pattern-id> -f params.yaml
-frankctl patterns register -f webhook-payload.json       # CI only
-```
-
-- `validate-params` POSTs `{params: <file>}` to `/api/v1/transform-patterns/{id}/validate`; file contents are a bare params object. Exits 5 if `valid: false`.
-- `patterns register` HMAC-signs the payload with `X-Hub-Signature-256: sha256=<hex>` using `PATTERN_WEBHOOK_SECRET`. **This command is CI-only** — pattern publish workflows in `frank-transforms` invoke it after pushing a digest-pinned image to GHCR. If `PATTERN_WEBHOOK_SECRET` is unset the CLI exits **6** with a message pointing at the env var; there is no override flag because unsigned payloads are rejected by the backend with `403` regardless.
 
-## 20e. Schedules subtree (WEC-134, source-scoped)
-
-```bash
 frankctl schedules list
 frankctl schedules get <source-id>
-frankctl schedules set <source-id> -f sched.yaml   # schedule_value required
+frankctl schedules set <source-id> -f sched.yaml    # schedule_value required, even for manual
 frankctl schedules pause|resume|trigger <source-id>
 frankctl schedules delete <source-id> --yes
 ```
 
-Backend expects `schedule_value` even for `schedule_type: manual` (it 422s on omission), so the zod schema requires it. Example:
+### AI assistance
 
-```yaml
-schedule_type: cron
-schedule_value: "0 */6 * * *"
-```
-
-**Transform schedules are a follow-up.** The backend surface exists (`/api/v1/transforms/{id}/schedule[/pause|resume|trigger]`) but we did not add a parallel `frankctl transform-schedules` tree in WEC-134 to keep scope tight; tracked for a future phase.
-
-## 20f. Datasets subtree (WEC-134)
-
-```bash
-frankctl datasets list [--layer bronze|silver|gold] [--namespace <ns>] [--page N] [--page-size N]
-frankctl datasets preview <layer.namespace.table> [--limit 20]
-frankctl datasets snapshots <layer.namespace.table>
-```
-
-- Dataset IDs are the 3-part `layer.namespace.table` dotted form the backend uses directly in the path (FastAPI `{dataset_id:path}` converter accepts dots verbatim).
-- `preview` renders the payload as a table of column headers + row values with cells capped at 60 chars; `--json` returns `{dataset_id, columns, rows, row_count}` unmodified.
-
-## 20a. Running E2E tests
-
-E2E tests exercise the compiled CLI against a live Frank stack. They are gated on `FRANK_E2E=1` so `npm test` stays hermetic.
-
-Preconditions:
-- Frank stack running (`docker-compose up -d` from repo root; `curl localhost:8002/health` → 200).
-- Test user provisioned (`testuser` / `testuser123` in the `frank` realm).
-- Dev tenant id: `550e8400-e29b-41d4-a716-446655440001`.
-
-Recipe:
-```bash
-cd frank-cli
-export FRANKCTL_API_URL=http://localhost:8002
-export FRANK_DEV_MODE=true
-export FRANKCTL_TENANT_ID=550e8400-e29b-41d4-a716-446655440001
-./dist/index.js auth login --headless --username testuser --password testuser123
-export FRANKCTL_TOKEN=$(./dist/index.js auth token)
-npm run build
-npm run test:e2e
-```
-
-Expect ≥24 tests green in ~90s on a healthy stack (new AI file is skipped unless Martha is available). Run a single file:
 ```bash
-FRANK_E2E=1 npx vitest run --config vitest-e2e.config.ts tests/e2e/sources.e2e.test.ts
+frankctl ai compose-pipeline -f spec.yaml [--no-wait] [--timeout <s>]
+frankctl ai generate-transform -f spec.yaml
+frankctl ai review-sql -f spec.yaml
+frankctl ai suggest target-schema  -f spec.yaml
+frankctl ai suggest field-mappings -f spec.yaml
+frankctl ai suggest pattern-params -f spec.yaml
 ```
 
-Fixtures live in `tests/e2e/fixtures/` (bash scripts). Each test wraps its seed in try/finally so a failed assertion never leaks state. Config is `vitest-e2e.config.ts` (serial, 120s timeouts).
-
-Notes on dev-stack quirks the suite tolerates:
-- `sources discover --wait` against real postgres can exceed 45s — test accepts exit 0 OR clean timeout (exit 4/5).
-- `sources sync` kicks off a Temporal workflow but `sync_run` rows may not materialize synchronously in dev — test asserts sync acceptance + well-formed history response, not a populated row.
-- `transforms trigger` returns 500 when Dagster code location is unreachable — test accepts 2xx JSON OR exit 4/5 with a stderr message.
-
-## 21. Known limitations
+AI commands emit JSON. Every response carries `available: bool`; when the AI service is
+offline the command exits 4 with a clear message. `compose-pipeline` returns a manifest
+you can review, edit, and feed straight into `pipelines apply`.
 
-- Prod tenant resolution requires `FRANK_DEV_MODE=true` + `FRANKCTL_TENANT_ID` (backend expects `X-Tenant-ID` today — tracked as follow-up WEC-135).
-- `runs cancel` against a raw temporal workflow-id currently 501s (backend gap).
-- No `pipelines create/update`.
-- No `transform-schedules` tree (follow-up). No transform-run cancel.
-- PKCE redirect ports are fixed by Keycloak realm JSON.
-
-## 22. Roadmap
+---
 
-Phase 3+: JWT-claim tenant resolution (removes `FRANK_DEV_MODE` requirement), transform-schedules subtree, shell completion bundle, `pipelines create/update`.
+## Output & exit codes
 
-## 23. Exit code reference
+- `--json` makes `list`/`get`/`status`/`config`/`auth status` emit a single JSON
+  object or array on stdout.
+- `pipelines validate` and the `ai` commands always emit their result as JSON.
+- FastAPI error shapes (`{detail: …}`) are normalized; a `401` triggers one automatic
+  token refresh + retry before surfacing.
 
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
 | 1 | Generic error |
 | 2 | Usage error |
-| 3 | Authentication |
-| 4 | API (incl. Martha unavailable) |
-| 5 | Validation (sandbox/compose-pipeline terminal failure, validate-params invalid) |
-| 6 | Config (e.g. `PATTERN_WEBHOOK_SECRET` unset for `patterns register`) |
+| 3 | Authentication error |
+| 4 | API error (non-2xx, incl. AI service unavailable) |
+| 5 | Validation failed (sandbox/compose terminal failure, invalid params) |
+| 6 | Config error (missing required env/secret) |
+
+## Troubleshooting
 
-## 24. Changelog
+- **PKCE can't bind a port** (containers/headless): use `frankctl auth login --headless`.
+- **401 after login**: your token expired and refresh failed — `frankctl auth login` again.
+- **`409 immutable_diff` on apply**: a Backing Dataset change would destroy state; see
+  `--allow-recreate` above and decide deliberately.
+- **`apply` did nothing**: that's idempotency — the declared state already matches. Use
+  `-v` to see the reconcile plan, or `--dry-run-server` to preview.
 
-- `0.3.0` — WEC-134: ai (compose-pipeline + generate/review/fix-ci/suggest/publish), patterns (list/get/validate-params/register with HMAC), schedules (source-scoped list/get/set/delete/pause/resume/trigger), datasets (list/preview/snapshots). Adds ExitCode 6 (Config).
-- `0.2.0` — WEC-133: sources CRUD + discover/sync/streams/logs/history, transforms list/get/runs/logs/trigger, runs get/wait/cancel.
-- `0.1.0` — WEC-132: status, auth (PKCE/ROPC/client-credentials), config, pipelines list/get/validate.
+## Print this reference
+
+```bash
+frankctl skill      # prints this document to stdout
+```