@jaggerxtrm/specialists 3.17.0 → 3.18.0

package/docs/skills.md

@@ -0,0 +1,132 @@
+---
+title: Skills Catalog
+scope: skills
+category: overview
+version: 2.0.1
+updated: 2026-06-24
+synced_at: bf6baf7a
+description: Skills shipped in this repo and how they are distributed.
+source_of_truth_for:
+  - "config/skills/**/*.md"
+domain:
+  - skills
+---
+
+# Skills Catalog
+
+> `sp` is a shorter alias for `specialists`.
+
+Skills are prompt packages that add focused guidance to specialist runs and to local coding-agent sessions.
+
+## Managed skill distribution
+
+Skills are **Category B** filesystem-bound assets. External agent runtimes read them directly from disk, so xtrm-tools owns the canonical snapshot under `.xtrm/skills/default/` and exposes active links through `.claude/skills` and `.pi/skills`.
+
+Check and refresh with xtrm-tools:
+
+```bash
+xt doctor --cwd <repo> --json
+xt update --repo <repo> --apply
+xt update --root <projects-root> --apply
+```
+
+User-authored skills belong in the user/active layer used by the local agent setup. Treat `.xtrm/skills/default/` as managed output, not a hand-edited source tree.
+
+## Repo-shipped skills
+
+The package ships the source copies under `config/skills/`. The active `.xtrm/skills/...` files in a project may be refreshed by xtrm-tools.
+
+### `using-specialists-v3`
+
+Location: `config/skills/using-specialists-v3/SKILL.md`
+
+Canonical orchestration doctrine for substantial tracked work. It covers bead contracts, dependency graph shape, conflict-cluster mapping, advisory passes, reviewer rebuttal, debugger-restitch, E2E smoke phases, monitoring cadence, `sp merge` / `sp epic merge`, and session-end handoff. Use this for multi-step implementation, debugging, reviews, docs sync planning, and specialist orchestration.
+
+### `using-specialists-auto`
+
+Location: `config/skills/using-specialists-auto/SKILL.md`
+
+Autonomous/offline orchestration overlay. It delegates shared mechanics to `using-specialists-v3` and adds auto-mode pacing, per-item loop shape, escalation triggers, and unattended-run discipline.
+
+### `using-specialists-v2` / `using-specialists`
+
+Locations:
+
+- `config/skills/using-specialists-v2/SKILL.md`
+- `config/skills/using-specialists/SKILL.md`
+
+Older orchestration references retained for compatibility and migration context. Prefer `using-specialists-v3` for current guidance.
+
+### `sync-docs`
+
+Location: `config/skills/sync-docs/SKILL.md`
+
+Single-document documentation synchronizer. One invocation must name exactly one doc in SCOPE. It uses drift scans plus bounded report/commit context and must not be treated as a whole-tree docs auditor.
+
+### `releasing`
+
+Location: `config/skills/releasing/SKILL.md`
+
+Release workflow driver. Owns version bump, changelog promotion, build, commit, tag, push, and npm publish. It may dispatch `changelog-keeper` to fill `[Unreleased]` gaps, but `changelog-keeper` itself does not publish.
+
+### `update-specialists`
+
+Location: `config/skills/update-specialists/SKILL.md`
+
+Reconciles specialists/xtrm drift. Current model:
+
+- Category A runtime assets: verify with `sp doctor --check-drift`; prune stale `.specialists/default/` snapshots with `sp prune-stale-defaults`.
+- Category B filesystem assets: verify with `xt doctor --cwd <repo> --json`; refresh with `xt update --repo <repo> --apply` or `xt update --root <root> --apply`.
+
+### `specialists-creator`
+
+Location: `config/skills/specialists-creator/SKILL.md`
+
+Guides creation and repair of `.specialist.json` files. Use `sp edit`, presets, `sp view`, and validation instead of hand-written ad-hoc JSON. Always choose models from live `pi --list-models`; do not cargo-cult old examples.
+
+### `setup-specialists`
+
+Location: `config/skills/setup-specialists/SKILL.md`
+
+First-run Specialists setup workflow. Bootstraps `~/.config/specialists/user.json`, checks local Pi models, applies cross-repo `sp edit --global` overrides, and now covers interactive keep-alive defaults plus waiting auto-close settings.
+
+### Other package skills
+
+Additional shipped skills include:
+
+- `using-script-specialists` — synchronous `sp script` / `sp serve` integration guidance
+- `using-kpi` — observability SQLite/KPI analysis
+- `using-nodes` — NodeSupervisor/coordinator workflow
+- `memory-audit-transaction` — file-backed memory audit ledger pattern
+- service/persona authoring and maintenance skills used by local workflows
+
+Use `find config/skills -maxdepth 2 -name SKILL.md` or `sp list` / specialist definitions to see which skills each specialist loads.
+
+## Referencing a skill from a specialist
+
+In specialist JSON:
+
+```json
+{
+  "specialist": {
+    "skills": {
+      "paths": [".xtrm/skills/active/sync-docs/"]
+    }
+  }
+}
+```
+
+Some package skills can also be referenced by canonical name when the runtime resolver supports that package-canonical lookup. Prefer existing package examples and validate with:
+
+```bash
+sp view <name>
+sp config show <name> --resolved
+sp validate
+```
+
+## See also
+
+- [authoring.md](authoring.md)
+- [specialists-catalog.md](specialists-catalog.md)
+- [installation.md](installation.md)
+- [hooks.md](hooks.md)

package/docs/specialists/handoff-schema.md

@@ -0,0 +1,181 @@
+# Specialist handoff schema
+
+Use at end of every `run_complete` turn, resume turns included.
+
+Common fields for all roles:
+- `status`: `success | partial | error`
+- `summary`: 1-3 sentences
+- `files_changed`: `string[]`
+- `follow_ups`: `string[]`
+- `risks`: `string[]`
+- `verification`: `string[]`
+
+Role-specific fields:
+- `reviewer`: `verdict`, `score`, `requirement_coverage[]`
+- `executor` / `debugger`: `symbols_modified[]`, `lint_pass`, `tests_pass`, `impact_report`
+- `changelog-keeper`: `version`, `commit`, `tag`, `pushed`
+- `explorer`: `findings[]`, `recommended_next`
+- `code-sanity`: `outcome`, `findings[]`
+- `security-auditor`: `outcome`, `findings[]`
+- `test-engineer`: machine-readable block uses behavioral `status` (`tests_written | blocked | source_bug_suspected`), plus `coverage_map[]`, `smoke_e2e_commands[]`, `telemetry_assertions[]`, `test_runner_commands[]`, `known_deferred_paths[]`, `source_bug_suspicions[]`
+- `test-runner`: `pass_count`, `fail_count`, `skip_count`, `commands_executed[]`, `artifact_evidence[]`, `classification[]`
+
+Notes:
+- Keep `reviewer` verdict shape aligned with `reviewer-verdict-format`; do not duplicate its prose rules.
+- `tests_pass` may be `true | false | "n/a"` for executor/debugger when tests were not run.
+- JSON block must be last in assistant turn.
+
+## Minimal compliant block
+
+```json
+{
+  "status": "success",
+  "summary": "Done.",
+  "files_changed": ["config/example.json"],
+  "follow_ups": [],
+  "risks": [],
+  "verification": ["bunx tsc --noEmit"]
+}
+```
+
+## Role examples
+
+### executor / debugger
+```json
+{
+  "status": "success",
+  "summary": "Applied targeted fix and verified compile.",
+  "files_changed": ["src/a.ts"],
+  "follow_ups": [],
+  "risks": [],
+  "verification": ["bunx tsc --noEmit"],
+  "symbols_modified": ["runTask"],
+  "lint_pass": true,
+  "tests_pass": "n/a",
+  "impact_report": {
+    "files_touched": ["src/a.ts"],
+    "symbols_analyzed": ["runTask"],
+    "highest_risk": "LOW",
+    "tool_invocations": 3
+  }
+}
+```
+
+### reviewer
+```json
+{
+  "status": "success",
+  "summary": "Reviewed diff against bead.",
+  "files_changed": ["src/a.ts"],
+  "follow_ups": [],
+  "risks": [],
+  "verification": ["git diff --stat"],
+  "verdict": "PASS",
+  "score": 92,
+  "requirement_coverage": [
+    {"requirement": "schema block", "status": "met", "evidence": "present", "gap": ""}
+  ]
+}
+```
+
+### changelog-keeper
+```json
+{
+  "status": "success",
+  "summary": "Release landed.",
+  "files_changed": ["CHANGELOG.md"],
+  "follow_ups": [],
+  "risks": [],
+  "verification": ["git diff --stat"],
+  "version": "1.2.3",
+  "commit": "abc1234",
+  "tag": "v1.2.3",
+  "pushed": true
+}
+```
+
+### explorer
+```json
+{
+  "status": "partial",
+  "summary": "Mapped likely path and one gap remains.",
+  "files_changed": [],
+  "follow_ups": ["inspect src/a.ts"],
+  "risks": ["Path may be stale"],
+  "verification": ["gitnexus_query('concept')"],
+  "findings": ["src/a.ts: likely entry point"],
+  "recommended_next": "Ask executor to patch src/a.ts"
+}
+```
+
+### code-sanity
+```json
+{
+  "status": "success",
+  "summary": "Checked scope and found no drift.",
+  "files_changed": ["src/a.ts"],
+  "follow_ups": [],
+  "risks": [],
+  "verification": ["git diff --stat"],
+  "outcome": "OK",
+  "findings": []
+}
+```
+
+### security-auditor
+```json
+{
+  "status": "partial",
+  "summary": "Reviewed changes for obvious security issues.",
+  "files_changed": ["src/a.ts"],
+  "follow_ups": [],
+  "risks": ["Input path needs caller validation"],
+  "verification": ["git diff --stat"],
+  "outcome": "findings",
+  "findings": [
+    {"severity": "medium", "file": "src/a.ts", "concern": "Unsanitized input", "source": "diff"}
+  ]
+}
+```
+
+### test-engineer
+```json
+{
+  "status": "tests_written",
+  "summary": "Added regression coverage and smoke command contract for changed behavior.",
+  "files_changed": ["tests/a.test.ts", "tests/smoke/a-smoke.sh"],
+  "follow_ups": [],
+  "risks": [],
+  "verification": ["bunx vitest run tests/a.test.ts"],
+  "coverage_map": [
+    {"impl_path": "src/a.ts", "test_path": "tests/a.test.ts", "critical_path": "retry fallback emits terminal event"}
+  ],
+  "smoke_e2e_commands": ["bash tests/smoke/a-smoke.sh"],
+  "telemetry_assertions": [
+    {"event": "job_finished", "fields": ["component", "event", "outcome"], "query_or_grep": "grep 'event=job_finished' .xtrm/logs/jobs.log", "redaction": "no secrets or raw payloads"}
+  ],
+  "test_runner_commands": ["bunx vitest run tests/a.test.ts", "bash tests/smoke/a-smoke.sh"],
+  "known_deferred_paths": [],
+  "source_bug_suspicions": []
+}
+```
+
+### test-runner
+```json
+{
+  "status": "success",
+  "summary": "Targeted tests passed.",
+  "files_changed": ["src/a.ts"],
+  "follow_ups": [],
+  "risks": [],
+  "verification": ["bunx vitest run src/a.test.ts"],
+  "pass_count": 4,
+  "fail_count": 0,
+  "skip_count": 0,
+  "commands_executed": ["bunx vitest run src/a.test.ts"],
+  "artifact_evidence": ["logs/test-runner/latest.log", "artifacts/smoke.json"],
+  "classification": [
+    {"test": "src/a.test.ts", "classification": "in_scope", "owner": "test_engineer", "evidence": "assertion mismatch"}
+  ]
+}
+```

package/docs/specialists-catalog.md

@@ -0,0 +1,99 @@
+---
+title: Specialists Catalog
+scope: specialists-catalog
+category: overview
+version: 2.1.0
+updated: 2026-06-23
+synced_at: bf6baf7a
+description: Current package-canonical specialists and what each one is for.
+source_of_truth_for:
+  - "config/specialists/*.specialist.json"
+  - ".specialists/default/*.specialist.json"
+  - ".specialists/user/*.specialist.json"
+domain:
+  - specialists
+---
+
+# Specialists Catalog
+
+Runtime resolution is layered and package-canonical by default:
+
+1. `.specialists/user/` — repo custom specialists and overrides, highest precedence
+2. `.specialists/default/` — optional pins / compatibility snapshots
+3. package-canonical `config/specialists/` — installed package fallback
+4. legacy paths — migration compatibility only
+
+Fresh repositories normally do not need `.specialists/default/` populated. Use `sp doctor --check-drift` and `sp prune-stale-defaults` to remove stale default snapshots; use `.specialists/user/` for intentional customization.
+
+## Current package specialists
+
+Run `sp list` for the live merged registry, including user-local specialists. The table below reflects package-canonical `config/specialists/*.specialist.json` at the current release.
+
+| Name | Version | Model | Permission | Keep-alive | Typical use |
+|---|---:|---|---|---|---|
+| `bare` | 1.0.0 | user-configured | READ_ONLY | user-configured | Minimal read-only specialist for trusted-mode RPC; no mandatory rules. |
+| `changelog-drafter` | 1.0.0 | user-configured | READ_ONLY | user-configured | Read-only bundle synthesis for `xt release prepare`; no publishing or edits. |
+| `changelog-keeper` | 3.0.0 | user-configured | MEDIUM | user-configured | Fill sparse `[Unreleased]` sections from xt reports and commits; edits `CHANGELOG.md` only. |
+| `debugger` | 2.0.0 | user-configured | HIGH | user-configured | Root-cause symptoms, regressions, flaky tests, and unknown-cause bugs before executor. |
+| `executor` | 1.0.0 | user-configured | HIGH | user-configured | Implement already-scoped code or docs changes in an isolated worktree. |
+| `explorer` | 1.1.0 | user-configured | READ_ONLY | user-configured | Map architecture, call flows, dependencies, and implementation options without edits. |
+| `memory-processor` | 1.1.0 | user-configured | MEDIUM | user-configured | Curate persistent project memory into `.xtrm/memory.md`. |
+| `node-coordinator` | 1.3.0 | user-configured | LOW | user-configured | Drive NodeSupervisor research-node runs through `sp node` commands. |
+| `obligations-scanner` | 1.0.0 | user-configured | READ_ONLY | user-configured | Scan source for unmet obligations (TODO, FIXME, XXX, HACK) and emit actionable reports. |
+| `overthinker` | 1.0.0 | user-configured | READ_ONLY | user-configured | Deep reasoning, tradeoff review, premortems, architecture critique. |
+| `planner` | 1.1.0 | user-configured | HIGH | user-configured | Turn broad initiatives into phased bead boards with dependencies and tests. |
+| `quant-methodologist` | 1.0.0 | user-configured | LOW | user-configured | Design quantitative research methodologies, backtesting frameworks, and statistical validation. |
+| `quant-researcher` | 1.0.0 | user-configured | LOW | user-configured | Research quantitative models, market microstructure, and alpha signals. |
+| `researcher` | 1.3.0 | user-configured | MEDIUM | user-configured | Current library/API docs, GitHub examples, and ecosystem evidence. |
+| `reviewer` | 2.0.0 | user-configured | MEDIUM | user-configured | Compliance review of executor/debugger output via `--job`; emits PASS/PARTIAL/FAIL. |
+| `seconder` | 1.0.0 | user-configured | READ_ONLY | user-configured | Smell pass after executor and before reviewer. |
+| `security-auditor` | 1.0.0 | user-configured | LOW | user-configured | Threat modeling, secure-code review, dependency advisory triage; recommendations only. |
+| `service-skills-sync` | 1.6.0 | user-configured | MEDIUM | user-configured | Sync service-oriented skill packages and drift detection across service boundaries. |
+| `specialists-creator` | 1.4.1 | user-configured | HIGH | user-configured | Create/fix `.specialist.json` definitions and validate schema/model choices. |
+| `sync-docs` | 3.1.0 | user-configured | MEDIUM | user-configured | Sync exactly one documentation file from scoped report/commit context. |
+| `test-engineer` | 1.0.0 | user-configured | HIGH | user-configured | Write/update tests, fixtures, smoke/E2E harnesses, and telemetry assertions from actual implementation diff; no production fixes. |
+| `test-runner` | 2.0.1 | user-configured | LOW | user-configured | Execute exact requested test commands first, fall back to manifest-detected suites only when needed, capture evidence, classify failures by owner; no fixes. |
+| `transcriber` | 1.6.0 | user-configured | MEDIUM | user-configured | Transcribe audio/video content and generate searchable structured output. |
+| `xt-merge` | 1.1.0 | user-configured | MEDIUM | user-configured | Drain xt worktree PR queues with CI/rebase/conflict handling. |
+
+## Notable release highlights
+
+- **Package specialists ship with `null` model and keep-alive.** v3.16+ (commit `60b33412`) removed hardcoded models and keep-alive from all package-canonical specialist definitions. Model selection and session persistence are now user-environment-specific via orchestrator config merge; see [KAN-90 upgrade notes](upgrade-notes/kan-90-global-user-config.md).
+- **`reviewer` v2.0 is phase-2-only.** The former phase-1 reviewer responsibilities merged into `seconder` v1.0; reviewer now handles only final compliance sign-off.
+- **`researcher` v1.3 adds web pipeline (Mode 4).** Includes DDGS + agent-browser for current web queries beyond static library docs.
+- **New quantitative specialists** `quant-methodologist` and `quant-researcher` v1.0.0 added for financial/quantitative research workflows.
+- **New supporting specialists:** `transcriber` v1.6.0 (media transcription), `service-skills-sync` v1.6.0 (cross-service drift detection), `obligations-scanner` v1.0.0 (TODO/FIXME tracking), and `bare` v1.0.0 (minimal trusted-mode RPC).
+- **`sync-docs` v3.1 is single-doc only.** One bead scope must name exactly one doc. It is not a broad docs-tree auditor.
+- **`test-engineer` v1 writes tests from actual diff evidence.** It is ambidextrous for `test-only` and `code-with-tests` chains, creates/updates test assets only, emits exact `test-runner` commands, and routes source bugs back to debugger/executor.
+- **`test-runner` v2.0.1 is exact-command first.** It prefers orchestrator/test-engineer command lists, falls back to manifest-detected suites only when no exact command is provided, and reports owner-routed failures with evidence.
+- **`test-runner` v2 is polyglot.** It detects `package.json`, Python, Rust, and Go manifests and runs the appropriate test command.
+- **`changelog-keeper` v3 is file-scoped.** It fills `CHANGELOG.md` gaps only; version bump/build/tag/publish are owned by the release skill flow.
+- **`seconder` and `security-auditor` are advisory passes.** They provide evidence and findings before final reviewer PASS.
+
+## Discover current runtime catalog
+
+```bash
+sp list
+sp list --compact
+sp list --json
+sp list-rules
+```
+
+## Tool resolution
+
+The `Permission` column is the input tier to the manifest-driven tool resolver. Runtime tools are computed from the tier plus package/user catalogs and any per-specialist `permissions[<TIER>]` override.
+
+Inspect a resolved specialist:
+
+```bash
+sp config show <name> --resolved
+```
+
+See [manifest.md](manifest.md) for resolution semantics and override policy.
+
+## See also
+
+- [manifest.md](manifest.md)
+- [authoring.md](authoring.md)
+- [workflow.md](workflow.md)
+- [skills.md](skills.md)

package/docs/specialists-service-install.md

@@ -0,0 +1,226 @@
+---
+title: Specialists Service Install
+scope: specialists-service-install
+category: deployment
+version: 2.1.2
+updated: 2026-06-24
+synced_at: bf6baf7a
+description: Install runbook for consumers who do not clone specialists source. Deployment steps, trust/readiness gates, hot-reload, common pitfalls.
+source_of_truth_for:
+  - Dockerfile
+  - docker/compose.example.yml
+cross_references:
+  - docs/specialists-service.md (HTTP contract, CLI flags, trust gates, hot-reload)
+  - docs/authoring.md (script-class schema)
+---
+
+# Specialists Service Install
+
+Install path for consumers who do **not** clone specialists source.
+
+For HTTP contract details, CLI flags (`--allow-skills`, `--allow-skills-roots`, `--reload-poll-ms`), trust gates, and hot-reload semantics, see the SSOT: **[docs/specialists-service.md](specialists-service.md)**.
+
+## Prerequisites
+
+- Docker
+- host `pi` config at `~/.pi`
+- local writable `.specialists/` directory for specs and observability state
+
+The container reads `pi` auth from a bind-mounted `~/.pi` directory. No secret file ships in image.
+
+## Build the image
+
+> Image publishing to a registry is deferred. For now, build from this repo's source.
+
+```bash
+git clone https://github.com/Jaggerxtrm/specialists.git
+cd specialists
+docker build -t specialists-service:local .
+# or with rootless podman:
+podman build -t specialists-service:local .
+```
+
+Tag whatever you want (`:local`, `:v0.1`, etc.) — your compose file references the same tag.
+
+The image runs as non-root, UID `10001` (label `org.specialists.uid=10001`). Override at runtime with `--user $UID:$GID` (Docker) or `--userns=keep-id --user $UID:$GID` (rootless Podman) so container writes are owned by your host user. The compose template wires this automatically.
+
+The image installs `@earendil-works/pi-coding-agent` at build time. Current service execution uses pi's subprocess runner; SDK-backed execution is future work if/when it lands.
+
+> **Future** — `docker pull ghcr.io/<org>/specialists-service:<tag>` once the image is published.
+
+## Author first specialist
+
+Create one script-class specialist in `.specialists/user/hello.specialist.json`. Minimal example:
+
+```json
+{
+  "specialist": {
+    "metadata": {
+      "name": "hello",
+      "version": "1.0.0",
+      "description": "Tiny demo specialist",
+      "category": "demo"
+    },
+    "execution": {
+      "mode": "auto",
+      "model": "openai-codex/gpt-5.4-mini",
+      "timeout_ms": 30000,
+      "interactive": false,
+      "response_format": "json",
+      "output_type": "custom",
+      "permission_required": "READ_ONLY",
+      "requires_worktree": false,
+      "max_retries": 0
+    },
+    "prompt": {
+      "task_template": "Say hello to $name and return JSON of shape {\"greeting\": \"...\"}.",
+      "output_schema": { "required": ["greeting"] }
+    }
+  }
+}
+```
+
+Variable substitution uses `$name` (single-dollar, no braces). Pick a model your host's `~/.pi/agent/auth.json` has credentials for. The runtime contract — script-class, non-interactive, read-only, no worktree, task_template present — is enforced at request time; mismatches return `specialist_load_error`.
+
+A working reference example ships with the repo at [`docs/examples/smoke-echo.specialist.json`](examples/smoke-echo.specialist.json) — copy it into your `.specialists/user/` to verify a fresh deployment end-to-end.
+
+For the full schema (every required, optional, and forbidden field with explanations), see [`docs/authoring.md` § Script-class authoring](authoring.md#script-class-authoring).
+
+## Compose file walkthrough
+
+Copy `docker/compose.example.yml` and replace placeholders.
+
+> **Adding to an existing multi-service stack?** See [`deploying-alongside.md`](deploying-alongside.md) for the production recipe with the three undocumented tweaks (`user:`, `HOME=/pi-home`, rw `.specialists/`) and a troubleshooting matrix.
+
+### Container naming: dev vs consumer service
+
+This repository's root `compose.yml` is only a local developer convenience. It now sets `container_name: sp-service-dev` so `docker ps` is visually distinct from real consumer deployments.
+
+- `sp-service-dev` — local specialists repo dev container from `/home/dawid/dev/specialists/compose.yml`.
+- `specialists-service` — consumer-owned sidecar/service name, for example darth-feedor's `ingestion/infra/docker-compose.yml` service that other app containers call at `http://specialists-service:8000`.
+- `specialists-specialists-1` — legacy Docker Compose auto-name for the old local dev service (`project=specialists`, `service=specialists`); an already-running container keeps that name until it is recreated.
+
+Use compose labels to verify ownership before debugging traffic:
+
+```bash
+docker inspect <container> --format '{{ index .Config.Labels "com.docker.compose.project" }} {{ index .Config.Labels "com.docker.compose.service" }} {{ index .Config.Labels "com.docker.compose.project.config_files" }}'
+```
+
+No production deployment is implied by the local dev compose file.
+
+- `image`: published tag or local build tag
+- `user`: align host UID/GID with container UID label
+- `.specialists:/work/.specialists:z` (omit `:z` on standard Docker; required on Fedora rootless Podman for SELinux relabel)
+- `${HOME}/.pi:/pi-home/.pi:ro` (add `:z` if SELinux blocks access)
+- `HOME=/pi-home`: makes pi resolve auth from mounted home
+- `working_dir: /work`: keeps relative specialist paths anchored to consumer project
+- `networks`: internal app network for sidecar calls
+
+No secret file needed. pi handles model auth from its own config.
+
+## First request
+
+Before sending traffic, verify readiness:
+
+```bash
+curl -sS http://localhost:8000/readyz
+```
+
+Returns `200 {"ready":true}` when all checks pass, or `503` with a reason when degraded. Six failure reasons exist: `draining`, `degraded:audit`, `pi_config_unreadable`, `db_not_writable`, `empty_user_dir`, `invalid_spec_in_user_dir`. See [specialists-service.md](specialists-service.md#readiness) for full taxonomy.
+
+For trusted single-tenant deployments needing skill-driven specs, pass trust flags at container start: `--allow-skills`, `--allow-skills-roots=<path[:path]>`. `skills.scripts` remain unsupported and are always rejected. Default is **deny all**. See [specialists-service.md](specialists-service.md#trust-flags).
+
+Send one generate request:
+
+```bash
+curl -sS http://localhost:8000/v1/generate \
+  -H 'content-type: application/json' \
+  -d '{"specialist":"hello","variables":{"name":"world"}}'
+```
+
+Expected shape:
+
+```json
+{
+  "success": true,
+  "output": "...",
+  "parsed_json": { "greeting": "..." },
+  "meta": {
+    "specialist": "hello",
+    "model": "openai-codex/gpt-5.4-mini",
+    "duration_ms": 1234,
+    "trace_id": "..."
+  }
+}
+```
+
+Process health check:
+
+```bash
+curl -sS http://localhost:8000/healthz
+```
+
+`/healthz` is process-alive only. Use `/readyz` for operational readiness.
+
+## Verify trace row
+
+Each call writes one row to `.specialists/db/observability.db`. The `surface` marker is stored inside the `status_json` JSON column, queryable with `json_extract`:
+
+```bash
+sqlite3 .specialists/db/observability.db \
+  "SELECT job_id, specialist,
+          json_extract(status_json, '\$.surface') AS surface,
+          json_extract(status_json, '\$.model') AS model,
+          json_extract(status_json, '\$.elapsed_s') AS sec
+   FROM specialist_jobs
+   WHERE json_extract(status_json, '\$.surface') = 'script_specialist'
+   ORDER BY updated_at_ms DESC LIMIT 5;"
+```
+
+This is the same DB `sp run` writes to; filter by surface to separate script-service calls from agent runs.
+
+## Common pitfalls
+
+- **UID mismatch.** Container default UID is `10001` (image label). To write into a bind-mounted host directory owned by your user, override at runtime: `--user "$UID:$GID"` (Docker) or `--userns=keep-id --user "$UID:$GID"` (rootless Podman). The compose template wires this with `user: "${UID:-1000}:${GID:-1000}"`.
+- **`~/.pi` missing or empty.** Container boots, but every request fails auth lookup. Run `pi --version` on the host first and ensure at least one provider is configured in `~/.pi/agent/auth.json`.
+- **OAuth refresh.** The default mount is `:ro` (read-only). If a provider's token expires mid-request, pi inside the container cannot refresh it back to disk. Refresh on the host (the host's pi tooling can do it interactively) and the container picks up new tokens on next file read.
+- **Model not in `pi` auth.json.** Request fails with `auth` or `internal`. Either run `pi auth` on the host to add the provider, or pick a model the host already has access to.
+
+### Rootless Podman / Fedora SELinux
+
+If you're using `podman` instead of `docker` on a Fedora-family host:
+
+- Add `:z` to bind-mount specs so SELinux relabels the dir for container access:
+  ```
+  -v ./.specialists:/work/.specialists:z
+  -v $HOME/.pi:/pi-home/.pi:ro,z
+  ```
+- Add `--userns=keep-id` so the container's UID maps to your host UID instead of a subuid (otherwise the container can read/write into a "1000:1000" host dir but the kernel still denies it).
+- Don't override `--user` to a UID outside the rootless `subuid` range; `1000:1000` (your user) is what `keep-id` will map.
+
+A working rootless podman invocation that mirrors the compose example:
+
+```bash
+podman run -d --rm --name specialists \
+  --userns=keep-id --user "$UID:$GID" \
+  -v "$PWD/.specialists:/work/.specialists:z" \
+  -v "$HOME/.pi:/pi-home/.pi:ro,z" \
+  -e HOME=/pi-home \
+  -p 8000:8000 \
+  specialists-service:local
+```
+
+The compose template targets standard Docker; if you're on Fedora + rootless Podman, copy the above command form instead.
+
+## Hot-reload
+
+The watcher auto-reloads `.specialists/user/*.specialist.json` on change. Native `fs.watch` is default. For container environments without inotify, use `--reload-poll-ms=1000` for polling fallback. See [specialists-service.md](specialists-service.md#hot-reload).
+
+## Upgrade story
+
+1. bump image tag in compose file
+2. restart container
+3. wait for `GET /readyz` to return `{"ready":true}`
+4. let traffic resume after readiness gate passes
+
+Future work: multi-arch buildx, cosign, SBOM, and rollout automation.