From 3dc1cbb410e99c6500ea767efb35245905964ed2 Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 17:50:28 +0200
Subject: [PATCH 01/11] docs(wp5): refresh runtime_stats and fix tool-category
 count

- generate_runtime_stats.py: count featured presets via ast (avoid
  pre-existing circular import in providers package init chain)
- runtime_stats.yaml: tests 30536, providers_curated 20, mem0_stars 55792
- inject markers (README + docs/roadmap/index.md)
- docs/roadmap/index.md: 8+ tool categories becomes 12+, list now matches
  docs/design/tools.md table
---
 README.md                         |  2 +-
 data/runtime_stats.yaml           | 14 ++++----
 docs/roadmap/index.md             |  4 +--
 scripts/generate_runtime_stats.py | 56 ++++++++++++++++++++++++++-----
 4 files changed, 58 insertions(+), 18 deletions(-)

diff --git a/README.md b/README.md
index 83a3dd08f6..62d38ba3aa 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ SynthOrg is a Python framework for building **synthetic organizations**, autonom
 
 Define your company in YAML. Agents collaborate through a message bus, follow workflows (Kanban, Agile sprints, or custom), track costs against budgets, and produce real artifacts. The framework is provider-agnostic (<!--RS:providers_via_litellm-->2700+<!--/RS--> LLMs via [LiteLLM](https://github.com/BerriAI/litellm)), configuration-driven ([Pydantic v2](https://docs.pydantic.dev/) models), and designed for the full autonomy spectrum, from human approval on every action to fully autonomous operation.
 
-> **Early access.** Core subsystems are built and tested (<!--RS:tests-->29,000+<!--/RS--> tests, 80%+ coverage). APIs may change between releases. See the [roadmap](https://synthorg.io/docs/roadmap/) for what's next.
+> **Early access.** Core subsystems are built and tested (<!--RS:tests-->30,000+<!--/RS--> tests, 80%+ coverage). APIs may change between releases. See the [roadmap](https://synthorg.io/docs/roadmap/) for what's next.
 
 ## Why SynthOrg?
 
diff --git a/data/runtime_stats.yaml b/data/runtime_stats.yaml
index 07935a79ca..a0c0150853 100644
--- a/data/runtime_stats.yaml
+++ b/data/runtime_stats.yaml
@@ -1,18 +1,18 @@
 schema_version: 1
-last_generated_utc: '2026-05-13T19:13:08Z'
-generator_revision: 3e69976a8
+last_generated_utc: '2026-05-15T15:49:25Z'
+generator_revision: d29621464
 stats:
   tests:
-    raw: 30090
+    raw: 30536
     rounded: 30000
     display: 30,000+
   mem0_stars:
-    raw: 55598
+    raw: 55792
     rounded: 55000
     display: 55k+
   providers_curated:
-    raw: 19
-    display: '19'
+    raw: 20
+    display: '20'
   providers_via_litellm:
     raw: 2708
     display: 2700+
@@ -25,7 +25,7 @@ stats:
 sources:
   tests: uv run python -m pytest --collect-only -q
   mem0_stars: gh api repos/mem0ai/mem0 --jq .stargazers_count
-  providers_curated: synthorg.providers.presets.list_presets
+  providers_curated: synthorg.providers.presets.list_featured_presets
   providers_via_litellm: len(litellm.model_cost)
   subagents: glob .claude/agents/*.md
   convention_gates: glob scripts/check_*.py
diff --git a/docs/roadmap/index.md b/docs/roadmap/index.md
index 2169acc13e..201183a95d 100644
--- a/docs/roadmap/index.md
+++ b/docs/roadmap/index.md
@@ -2,7 +2,7 @@
 
 ## Current Status
 
-SynthOrg is in **active development**. The core subsystems are built, tested (<!--RS:tests-->29,000+<!--/RS--> tests in the latest run, 80%+ coverage), and integrated through a REST + WebSocket API, React 19 dashboard, and Go CLI. See the [releases page](https://github.com/Aureliolo/synthorg/releases) for the latest tagged build.
+SynthOrg is in **active development**. The core subsystems are built, tested (<!--RS:tests-->30,000+<!--/RS--> tests in the latest run, 80%+ coverage), and integrated through a REST + WebSocket API, React 19 dashboard, and Go CLI. See the [releases page](https://github.com/Aureliolo/synthorg/releases) for the latest tagged build.
 
 What works today:
 
@@ -14,7 +14,7 @@ What works today:
 - **Memory** with hybrid retrieval (dense + BM25 sparse with RRF fusion), tool-based injection, procedural memory auto-generation from failures, consolidation (LLM Merge, Search-and-Ask), and MVCC snapshot reads on the shared knowledge store
 - **Communication** with message bus, hierarchical delegation with loop prevention, conflict resolution (4 strategies), meeting protocols, and an A2A gateway for external agent systems
 - **Workflow engine** with Kanban, Agile sprints, ceremony scheduling (8 strategies), visual workflow editor, and workflow execution from graph definitions
-- **Tool ecosystem** with 8+ categories (file system, git, web, database, terminal, sandbox, MCP bridge, analytics, communication) and sandbox security (auth proxy, gVisor, Chainguard packages)
+- **Tool ecosystem** with 12+ categories (file system, code execution, version control, web, database, terminal, design, communication, analytics, deployment, memory, MCP servers) and sandbox security (auth proxy, gVisor, Chainguard packages)
 - **Persistence** with SQLite (single-node default) and PostgreSQL (multi-instance, dual-backend conformance-tested) backends, yoyo-managed schema migrations, and ISO 4217 currency stamping on every cost-bearing row
 - **Distributed runtime** with NATS JetStream message bus and distributed task queue for multi-instance deployments
 - **Web dashboard** (React 19 + shadcn/ui) with org chart, task board, agent detail, budget tracking, provider management, workflow editor, ceremony policy settings, setup wizard, and WebSocket / SSE resilience
diff --git a/scripts/generate_runtime_stats.py b/scripts/generate_runtime_stats.py
index e6029f23a0..8055126a12 100644
--- a/scripts/generate_runtime_stats.py
+++ b/scripts/generate_runtime_stats.py
@@ -5,7 +5,7 @@
 
 * ``tests``                 -- ``uv run python -m pytest --collect-only -q``
 * ``mem0_stars``            -- ``gh api repos/mem0ai/mem0 --jq .stargazers_count``
-* ``providers_curated``     -- ``len(synthorg.providers.presets.list_presets())``
+* ``providers_curated``     -- ``len(synthorg.providers.presets.list_featured_presets())``
 * ``providers_via_litellm`` -- ``len(litellm.model_cost)``
 * ``subagents``             -- ``glob .claude/agents/*.md``
 * ``convention_gates``      -- ``glob scripts/check_*.py``
@@ -27,6 +27,7 @@
 Numeric thresholds are named module constants -- never magic literals.
 """
 
+import ast
 import datetime as dt
 import re
 import subprocess
@@ -65,7 +66,7 @@
 _SOURCES: Final[dict[str, str]] = {
     "tests": "uv run python -m pytest --collect-only -q",
     "mem0_stars": "gh api repos/mem0ai/mem0 --jq .stargazers_count",
-    "providers_curated": "synthorg.providers.presets.list_presets",
+    "providers_curated": "synthorg.providers.presets.list_featured_presets",
     "providers_via_litellm": "len(litellm.model_cost)",
     "subagents": "glob .claude/agents/*.md",
     "convention_gates": "glob scripts/check_*.py",
@@ -197,18 +198,57 @@ def _fetch_mem0_stars() -> StatEntry:
     }
 
 
+_PRESETS_PATH: Final[Path] = REPO_ROOT / "src" / "synthorg" / "providers" / "presets.py"
+_FEATURED_TUPLE_NAME: Final[str] = "_FEATURED_PRESETS"
+
+
 def _fetch_providers_curated() -> StatEntry:
-    """Count curated provider presets via ``synthorg.providers.presets``."""
+    """Count hand-curated featured provider presets.
+
+    Tracks ``_FEATURED_PRESETS`` (the hand-curated entries with brand
+    logo, vetted description, and prefilled model defaults), not the
+    full ``list_presets()`` surface which auto-derives an entry for
+    every LiteLLM chat namespace. The public claim is the featured
+    count because that is what surfaces in the setup wizard's primary
+    grid.
+
+    Uses an ``ast`` walk of ``presets.py`` rather than an ``import``:
+    the providers package pulls in the budget tracker which has its own
+    initialisation chain, and a one-shot script must not pay that cost
+    (or fail when the chain has unrelated circular-import drift). The
+    tuple literal is the authoritative source either way.
+    """
     name = "providers_curated"
     source = _SOURCES[name]
+    if not _PRESETS_PATH.is_file():
+        raise _StatFetchError(name, source, f"{_PRESETS_PATH} not found")
     try:
-        from synthorg.providers.presets import list_presets
-    except ImportError as exc:
+        tree = ast.parse(_PRESETS_PATH.read_text(encoding="utf-8"))
+    except (OSError, SyntaxError) as exc:
         raise _StatFetchError(
-            name, source, f"could not import synthorg.providers.presets: {exc}"
+            name, source, f"could not parse {_PRESETS_PATH.name}: {exc}"
         ) from exc
-    raw = len(list_presets())
-    return {"raw": raw, "display": str(raw)}
+    for node in tree.body:
+        if not isinstance(node, ast.AnnAssign | ast.Assign):
+            continue
+        targets = [node.target] if isinstance(node, ast.AnnAssign) else node.targets
+        for target in targets:
+            if not isinstance(target, ast.Name):
+                continue
+            if target.id != _FEATURED_TUPLE_NAME:
+                continue
+            value = node.value
+            if not isinstance(value, ast.Tuple):
+                raise _StatFetchError(
+                    name,
+                    source,
+                    f"{_FEATURED_TUPLE_NAME} is not a tuple literal",
+                )
+            raw = len(value.elts)
+            return {"raw": raw, "display": str(raw)}
+    raise _StatFetchError(
+        name, source, f"{_FEATURED_TUPLE_NAME} not found in {_PRESETS_PATH.name}"
+    )
 
 
 def _fetch_providers_via_litellm() -> StatEntry:

From 1b8e9a09b85f1d59942d41170a601dfbca10e91c Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 17:51:09 +0200
Subject: [PATCH 02/11] docs(wp5): mark shipped features FULL in competitors
 and roadmap

- competitors.yaml: budget_tracking + security_model become full; notes
  list risk-unit action budgets and self-healing SSRF as shipped
- roadmap/future-vision.md: drop Notification sink MVP from Planned;
  PG row narrowed to TimescaleDB hypertable support
- roadmap/index.md: promote Notification sinks to What works today;
  drop the Notification sink bullet from Planned; narrow PG bullet to
  TimescaleDB
---
 data/competitors.yaml         | 4 ++--
 docs/roadmap/future-vision.md | 3 +--
 docs/roadmap/index.md         | 4 ++--
 3 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/data/competitors.yaml b/data/competitors.yaml
index 3ee443c4df..e55adb59e6 100644
--- a/data/competitors.yaml
+++ b/data/competitors.yaml
@@ -113,8 +113,8 @@ competitors:
       memory: {support: full, note: "Pluggable architecture with 3 backends (Mem0, composite, in-memory); 5 memory types (working, episodic, semantic, procedural, social); hybrid retrieval (dense + BM25 sparse, linear-weighted fusion)"}
       tool_use: {support: full, note: "MCP protocol, sandbox isolation, invocation tracking; 14 ToolCategory values (file_system, code_execution, version_control, web, database, terminal, design, communication, analytics, deployment, memory, ontology, mcp, other)"}
       human_in_loop: {support: full, note: "Approval gates, review workflows, 4 autonomy tiers (FULL, SEMI, SUPERVISED, LOCKED), two-stage safety classifier, LLM fallback evaluator"}
-      budget_tracking: {support: partial, note: "Per-token, per-agent, hierarchical cascades, CFO optimization, and automatic model downgrade shipped; risk-unit action budgets still in progress"}
-      security_model: {support: partial, note: "Rule engine + LLM evaluator, progressive trust, audit trail, output scanning, and hallucination detection shipped; self-healing SSRF still in progress"}
+      budget_tracking: {support: full, note: "Per-token, per-agent, hierarchical cascades, CFO optimization, automatic model downgrade, and risk-unit action budgets"}
+      security_model: {support: full, note: "Rule engine + LLM evaluator, progressive trust, audit trail, output scanning, hallucination detection, and self-healing SSRF validation"}
       observability: {support: full, note: "Structured logging, correlation tracking, log shipping, redaction, Prometheus metrics, OTLP"}
       web_dashboard: {support: full, note: "React 19 dashboard with org chart, tasks, budgets, workflow editor, setup wizard, WebSocket + SSE resilience"}
       cli: {support: partial, note: "Go binary for container management and verification; not used for agent orchestration"}
diff --git a/docs/roadmap/future-vision.md b/docs/roadmap/future-vision.md
index 9f7b47904c..7cb1c8ae81 100644
--- a/docs/roadmap/future-vision.md
+++ b/docs/roadmap/future-vision.md
@@ -6,13 +6,12 @@ The longer-term direction for SynthOrg. Items here are either **planned** (sched
 
 | Feature | Status |
 |---------|--------|
-| PostgreSQL performance tuning + TimescaleDB hypertable support | Planned |
+| TimescaleDB hypertable support for append-only time-series tables | Planned |
 | Multi-project support with project-scoped teams and isolated budgets | Planned |
 | Dynamic company scaling across clusters | Planned |
 | Plugin system | Planned |
 | Benchmarking suite | Planned |
 | REST API and dashboard UI for agent evolution | Planned |
-| Notification sink MVP (Slack, ntfy, HTTP-relay) | Planned |
 | OpenAPI TypeScript codegen for the dashboard | Planned |
 
 ## Backlog (Research Candidates)
diff --git a/docs/roadmap/index.md b/docs/roadmap/index.md
index 201183a95d..47c81b2cda 100644
--- a/docs/roadmap/index.md
+++ b/docs/roadmap/index.md
@@ -23,6 +23,7 @@ What works today:
 - **Multi-user access** with HttpOnly cookie sessions, CSRF protection, concurrent session control, JWT auth, and session management
 - **Local model management** for Ollama and LM Studio (browse, pull, delete, configure launch parameters)
 - **Observability** with structured logging, correlation tracking, log shipping, redaction, Prometheus metrics, and OTLP
+- **Notification sinks** with operator alerts via Slack, ntfy, email, and HTTP relay (severity filtering and per-channel routing)
 
 What's not there yet:
 
@@ -34,10 +35,9 @@ What's not there yet:
 Prioritised by dependency order. All work is tracked on the [GitHub issue tracker](https://github.com/Aureliolo/synthorg/issues).
 
 - Operational guides: runtime settings reference, notifications and event subscriptions, workflow API tutorials, agent lifecycle, memory admin API
-- Notification sink MVP for operator alerts (Slack, ntfy, email via HTTP sink relay)
 - OpenAPI TypeScript codegen for the web dashboard
 - REST API and dashboard UI for agent evolution configuration and triggering
-- PostgreSQL performance tuning + TimescaleDB hypertable support for append-only time-series tables
+- TimescaleDB hypertable support for append-only time-series tables
 - Dynamic company scaling across clusters
 - Multi-project support with project-scoped teams and isolated budgets
 - Plugin system and benchmarking suite

From 223c119de0ed00d7e720bc1095a159513267485b Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 17:51:54 +0200
Subject: [PATCH 03/11] docs(wp5): align marketing site autonomy tiers to 4
 (design spec)

site/src/pages/index.astro, site/src/pages/compare.astro, and
site/src/components/FeatureShowcase.astro previously claimed 'five'
or '5 autonomy tiers'. Design spec (docs/design/security.md) and the
AutonomyLevel enum document four: full, semi, supervised, locked.
All three surfaces now match.
---
 site/src/components/FeatureShowcase.astro | 2 +-
 site/src/pages/compare.astro              | 7 ++++---
 site/src/pages/index.astro                | 4 ++--
 3 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/site/src/components/FeatureShowcase.astro b/site/src/components/FeatureShowcase.astro
index 827b5b01a6..6de4f17af3 100644
--- a/site/src/components/FeatureShowcase.astro
+++ b/site/src/components/FeatureShowcase.astro
@@ -16,7 +16,7 @@ const heroFeatures = [
     title: "Governance & Security",
     headline: "Every action classified, audited, and gated.",
     description:
-      "Hybrid SecOps: rule engine fast-path for ~95% of actions in sub-millisecond, plus LLM evaluator for uncertain cases. Five autonomy tiers. 25+ classified action types. Budget enforcement at every layer.",
+      "Hybrid SecOps: rule engine fast-path for ~95% of actions in sub-millisecond, plus LLM evaluator for uncertain cases. Four autonomy tiers (full, semi, supervised, locked). 25+ classified action types. Budget enforcement at every layer.",
     differentiator:
       "Progressive trust: privileges never auto-granted, auto-downgrade on violations.",
     href: "/docs/security/",
diff --git a/site/src/pages/compare.astro b/site/src/pages/compare.astro
index cd96e47f02..044578d6db 100644
--- a/site/src/pages/compare.astro
+++ b/site/src/pages/compare.astro
@@ -100,9 +100,10 @@ const description = `Interactive comparison of SynthOrg against ${competitorCoun
             <h3 class="text-xl font-semibold">Progressive Security</h3>
           </div>
           <p class="text-gray-400 leading-relaxed">
-            A rule engine combined with LLM-based evaluation, 5 autonomy tiers,
-            progressive trust scoring, comprehensive audit trails, and output scanning.
-            Security is built into the framework from day one, not bolted on after.
+            A rule engine combined with LLM-based evaluation, 4 autonomy tiers
+            (full, semi, supervised, locked), progressive trust scoring,
+            comprehensive audit trails, and output scanning. Security is built
+            into the framework from day one, not bolted on after.
           </p>
         </div>
 
diff --git a/site/src/pages/index.astro b/site/src/pages/index.astro
index e32660908d..796db25813 100644
--- a/site/src/pages/index.astro
+++ b/site/src/pages/index.astro
@@ -153,10 +153,10 @@ const description = "Framework for building synthetic organizations, autonomous
         <a href="/docs/security/#application-security" class="block bg-[#0F1219] rounded-xl p-8 border border-teal-500/20 hover:border-teal-500/40 transition-colors no-underline text-white">
           <div class="w-12 h-12 rounded-lg bg-teal-600/20 flex items-center justify-center text-teal-400 mb-4 text-xl">&#128737;</div>
           <h3 class="text-xl font-semibold mb-3">Runtime Protection</h3>
-          <p class="text-gray-400 mb-4">Hybrid SecOps: rule engine fast-path handles ~95% of actions in sub-millisecond, with an LLM evaluator for uncertain edge cases. 25+ classified action types, five autonomy tiers.</p>
+          <p class="text-gray-400 mb-4">Hybrid SecOps: rule engine fast-path handles ~95% of actions in sub-millisecond, with an LLM evaluator for uncertain edge cases. 25+ classified action types, four autonomy tiers (full, semi, supervised, locked).</p>
           <ul class="text-sm text-gray-400 space-y-1">
             <li>Fail-closed rule engine + LLM fallback evaluator</li>
-            <li>5 autonomy tiers with progressive trust</li>
+            <li>4 autonomy tiers with progressive trust</li>
             <li>Output scanning with redaction policies</li>
             <li>Persistent audit trail for every decision</li>
           </ul>

From bec39079dead08fcc813fe71f89ebf6ac6a7029e Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 17:54:41 +0200
Subject: [PATCH 04/11] docs(wp5): fix setup-wizard order and create CLI
 commands reference

- docs/user_guide.md: swap Company and Providers (Providers comes
  directly after Template per web/src/stores/setup-wizard/navigation.ts)
- docs/reference/cli-commands.md (new): operator-facing per-command
  flag inventory with defaults (start --timeout=90s, status
  --interval=2s, logs --tail=100, cleanup --keep=0, backup create
  --timeout=60s, backup restore --timeout=30s, backup list --limit=0,
  init --encrypt-secrets=true, backup restore --confirm required)
- mkdocs.yml: surface the new CLI commands page and the existing
  cli-config-subcommands / cli-env-vars / cli-persistence-backends /
  configuration-precedence reference pages in the Reference section
- docs/guides/quickstart.md and docs/reference/configuration-precedence.md
  already match the code; no change
---
 docs/reference/cli-commands.md | 116 +++++++++++++++++++++++++++++++++
 docs/user_guide.md             |   4 +-
 mkdocs.yml                     |   5 ++
 3 files changed, 123 insertions(+), 2 deletions(-)
 create mode 100644 docs/reference/cli-commands.md

diff --git a/docs/reference/cli-commands.md b/docs/reference/cli-commands.md
new file mode 100644
index 0000000000..cbab6a362d
--- /dev/null
+++ b/docs/reference/cli-commands.md
@@ -0,0 +1,116 @@
+---
+title: CLI Per-Command Flags
+description: Operator reference for synthorg subcommands and their flags, with defaults and tunable env-var overrides.
+---
+
+# CLI Per-Command Flags
+
+Operator reference for the `synthorg` CLI binary. The CLI is Docker-only: `init` provisions the deployment, `start` / `stop` / `update` manage the container lifecycle, `status` / `logs` / `doctor` introspect, `backup` / `wipe` / `cleanup` cover data and image hygiene. Feature work runs in the web dashboard against the REST API.
+
+Defaults shown below are compiled into the binary; tunable defaults are also reachable via `synthorg config set <key> <value>` and the matching `SYNTHORG_*` env var.
+
+## Lifecycle
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `init` | `--backend-port` | (prompted) | Host port for the REST / WebSocket API |
+| `init` | `--web-port` | (prompted) | Host port for the web dashboard |
+| `init` | `--sandbox` | (prompted) | Mount the Docker socket for the agent code-execution sandbox |
+| `init` | `--log-level` | (prompted) | Backend log level (`debug` / `info` / `warn` / `error`) |
+| `init` | `--image-tag` | (pinned) | Override container image tag |
+| `init` | `--channel` | `stable` | Release channel (`stable` / `dev`) |
+| `init` | `--bus-backend` | `inproc` | Communication bus backend (`inproc` / `nats`) |
+| `init` | `--persistence-backend` | `sqlite` | Persistence backend (`sqlite` / `postgres`) |
+| `init` | `--postgres-port` | `5432` | Host port when `--persistence-backend=postgres` |
+| `init` | `--encrypt-secrets` | `true` | Encrypt connection secrets at rest via Fernet (`true` / `false`) |
+| `start` | `--no-wait` | `false` | Skip the health check after start |
+| `start` | `--timeout` | `90s` | Health-check timeout (Go duration, e.g. `90s`, `2m`) |
+| `start` | `--no-pull` | `false` | Skip image verification and pull |
+| `start` | `--dry-run` | `false` | Show what would happen without executing |
+| `start` | `--no-detach` | `false` | Run in foreground (stream logs; Ctrl+C to stop) |
+| `start` | `--no-verify` | `false` | Skip image signature verification (also `--skip-verify`) |
+| `stop` | `--timeout` / `-t` | `10s` | Graceful shutdown timeout |
+| `stop` | `--volumes` | `false` | Remove named volumes (destructive) |
+| `update` | `--dry-run` | `false` | Show what would happen without executing |
+| `update` | `--no-restart` | `false` | Pull images but do not restart containers |
+| `update` | `--timeout` | `90s` | Health-check and verification timeout |
+| `update` | `--cli-only` | `false` | Only update the CLI binary |
+| `update` | `--images-only` | `false` | Only update container images (skip CLI) |
+| `update` | `--check` | `false` | Check for updates and exit (`0`=current, `10`=available) |
+
+## Introspection
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `status` | `--watch` / `-w` | `false` | Continuously poll status |
+| `status` | `--interval` | `2s` | Watch polling interval (Go duration) |
+| `status` | `--wide` | `false` | Show extra columns (ports) |
+| `status` | `--no-trunc` | `false` | Show full image names |
+| `status` | `--services` | (all) | Filter by service names (comma-separated) |
+| `status` | `--check` | `false` | Exit code only (`0`=healthy, `3`=unhealthy, `4`=unreachable) |
+| `logs` | `--follow` / `-f` | `false` | Follow log output |
+| `logs` | `--tail` | `100` | Number of lines to show from the tail |
+| `logs` | `--since` | (none) | Show logs since timestamp or relative (e.g. `1h`, `2024-01-01`) |
+| `logs` | `--until` | (none) | Show logs until timestamp or relative |
+| `logs` | `--timestamps` / `-t` | `false` | Show timestamps |
+| `logs` | `--no-log-prefix` | `false` | Suppress the service prefix |
+| `doctor` | `--checks` | `all` | Comma-separated check categories (`environment`, `health`, ...) |
+| `doctor` | `--fix` | `false` | Auto-fix detected issues where supported |
+| `version` | `--short` | `false` | Print only the version string |
+
+## Hygiene
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `cleanup` | `--dry-run` | `false` | List images without removing |
+| `cleanup` | `--all` | `false` | Include ALL SynthOrg images, not just old ones |
+| `cleanup` | `--keep` | `0` | Keep N most recent previous versions (`0`=remove all old) |
+| `wipe` | `--dry-run` | `false` | Show what would happen without executing |
+| `wipe` | `--no-backup` | `false` | Skip the interactive backup prompt |
+| `wipe` | `--keep-images` | `false` | Leave container images on disk |
+| `uninstall` | `--keep-data` | `false` | Leave the data directory in place |
+| `uninstall` | `--keep-images` | `false` | Leave container images on disk |
+
+## Backup
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `backup create` | `--output` / `-o` | (data dir) | Output path for the backup archive |
+| `backup create` | `--timeout` | `60s` | API request timeout (Go duration). Default is the `backup_create_timeout` tunable. |
+| `backup list` | `--limit` / `-n` | `0` | Show N most recent (`0`=all) |
+| `backup list` | `--sort` | `newest` | Sort order (`newest` / `oldest` / `size`) |
+| `backup restore` | `--confirm` | (required) | Required acknowledgement that restore overwrites current data |
+| `backup restore` | `--dry-run` | `false` | Validate the archive without overwriting |
+| `backup restore` | `--no-restart` | `false` | Restore without restarting containers afterwards |
+| `backup restore` | `--timeout` | `30s` | API request timeout (Go duration). Default is the `backup_restore_timeout` tunable. |
+
+## Workers
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `worker start` | `--workers` | `4` | Number of worker processes |
+| `worker start` | `--nats-url` | `nats://nats:4222` | NATS URL (also `SYNTHORG_NATS_URL`) |
+| `worker start` | `--stream-prefix` | `SYNTHORG` | NATS stream prefix (also `SYNTHORG_DEFAULT_NATS_STREAM_PREFIX`) |
+| `worker start` | `--container` | (empty) | Container name; falls back to `synthorg-backend` when unset |
+
+## Completion
+
+| Command | Description |
+|---------|-------------|
+| `completion <shell>` | Emit autocompletion script (`bash` / `zsh` / `fish` / `powershell`) |
+| `completion-install <shell>` | Write the autocompletion script into your shell startup |
+
+## Scaffolding
+
+| Command | Flag | Default | Description |
+|---------|------|---------|-------------|
+| `new <kind> <domain>` | `--dry-run` | `false` | Print the file plan without writing |
+| `new <kind> <domain>` | `--overwrite` | `false` | Overwrite existing files in the target |
+
+`<kind>` is one of `service` / `persistence` / `tool` / `controller`. See [scaffolding.md](scaffolding.md) for the per-kind file set and the convention enforcement coverage.
+
+## See also
+
+- [cli-config-subcommands.md](cli-config-subcommands.md): `synthorg config` get / set / unset and the full settable-key inventory.
+- [cli-env-vars.md](cli-env-vars.md): the `SYNTHORG_*` env var inventory consumed by the CLI binary.
+- [cli-persistence-backends.md](cli-persistence-backends.md): SQLite vs Postgres orchestration.
diff --git a/docs/user_guide.md b/docs/user_guide.md
index ba66796661..3012cb2154 100644
--- a/docs/user_guide.md
+++ b/docs/user_guide.md
@@ -75,8 +75,8 @@ After the containers are running, open the web dashboard at [http://localhost:30
 
 1. **Account** (conditional): create the first admin user. This step only appears when no admin account exists yet.
 2. **Template**: choose a company template. Templates are displayed in a searchable grid with category and size filters, grouped into Recommended and Other sections. Each card shows structural metadata (agent count, departments, autonomy level, workflow). Side-by-side comparison is available.
-3. **Company**: name your synthetic organization, set a description, choose a display currency, and select a model tier profile (Economy, Balanced, or Premium).
-4. **Providers**: configure LLM providers. Local providers (e.g. Ollama) are auto-detected with a re-scan button; additional providers can be added via the full provider form supporting API key, subscription, and custom configurations. Model discovery runs automatically after adding a provider.
+3. **Providers**: configure LLM providers. Local providers (e.g. Ollama) are auto-detected with a re-scan button; additional providers can be added via the full provider form supporting API key, subscription, and custom configurations. Model discovery runs automatically after adding a provider.
+4. **Company**: name your synthetic organization, set a description, choose a display currency, and select a model tier profile (Economy, Balanced, or Premium).
 5. **Agents**: customize agent names, personality presets, and model assignments. Agents are pre-populated from the selected template with models matched to configured providers.
 6. **Theme**: set UI preferences including color palette, typography, layout density, animation level, and sidebar position.
 7. **Complete**: review a summary of your configuration and launch the organization.
diff --git a/mkdocs.yml b/mkdocs.yml
index 6a53ff689b..fba33bb43f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -179,6 +179,11 @@ nav:
       - reference/standards.md
       - Implicit Conventions: reference/conventions.md
       - Framework Comparison: reference/comparison.md
+      - CLI Per-Command Flags: reference/cli-commands.md
+      - CLI Config Subcommands: reference/cli-config-subcommands.md
+      - CLI Environment Variables: reference/cli-env-vars.md
+      - CLI Persistence Backends: reference/cli-persistence-backends.md
+      - Configuration Precedence: reference/configuration-precedence.md
       - Embedding Evaluation: reference/embedding-evaluation.md
       - Scoring Hyperparameters: reference/scoring-hyperparameters.md
       - Error Reference: errors.md

From e085e4ad663c9a5f617e63f620570aed9a16697e Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 17:57:36 +0200
Subject: [PATCH 05/11] docs(wp5): redirect legacy doc URLs to canonical paths
 via Caddyfile

Added mkdocs-redirects to the docs dependency group and mkdocs.yml as a
fallback. The production site is served by Caddy in front of the mkdocs
output and zensical does not run mkdocs plugins, so the authoritative
redirect lives in web/Caddyfile. Three legacy paths now resolve:
/docs/getting-started/ to /docs/getting_started/, /docs/decisions/ to
/docs/architecture/decisions/, /docs/comparison/ to /docs/reference/comparison/.
---
 mkdocs.yml     |   8 ++++
 pyproject.toml |   1 +
 uv.lock        | 113 +++++++++++++++++++++++++++++--------------------
 web/Caddyfile  |  11 +++++
 4 files changed, 86 insertions(+), 47 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index fba33bb43f..19951a6659 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -31,6 +31,14 @@ theme:
 
 plugins:
   - search
+  # Preserve old URLs from before docs reshuffles. Each line maps an
+  # old path to its current location. Keep entries minimal and remove
+  # any once the corresponding inbound links are updated.
+  - redirects:
+      redirect_maps:
+        'getting-started.md': 'getting_started.md'
+        'decisions.md': 'architecture/decisions.md'
+        'comparison.md': 'reference/comparison.md'
   # D2 rendering is handled via pymdownx.superfences custom_fences
   # (see d2_fence.py) because zensical does not run mkdocs plugin
   # lifecycle hooks. Keep the config here so d2_fence.py reads it.
diff --git a/pyproject.toml b/pyproject.toml
index 85eacdd14c..3b25475479 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -91,6 +91,7 @@ docs = [
     "mkdocstrings[python]==1.0.4",
     "griffe-pydantic==1.3.1",
     "mkdocs-d2-plugin==1.7.0",
+    "mkdocs-redirects==1.2.2",
     # Used by scripts/patch_sitemap.py to safely parse the built sitemap.
     # Present as a transitive via py-serializable, but declared here so the
     # build script has a stable explicit dependency.
diff --git a/uv.lock b/uv.lock
index b201f0c15d..4e633f0794 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1587,6 +1587,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/88/29/744136411e785c4b0b744d5413e56555265939ab3a104c6a4b719dad33fd/mkdocs_get_deps-0.2.2-py3-none-any.whl", hash = "sha256:e7878cbeac04860b8b5e0ca31d3abad3df9411a75a32cde82f8e44b6c16ff650", size = 9555, upload-time = "2026-03-10T02:46:32.256Z" },
 ]
 
+[[package]]
+name = "mkdocs-redirects"
+version = "1.2.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "mkdocs" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f1/a8/6d44a6cf07e969c7420cb36ab287b0669da636a2044de38a7d2208d5a758/mkdocs_redirects-1.2.2.tar.gz", hash = "sha256:3094981b42ffab29313c2c1b8ac3969861109f58b2dd58c45fc81cd44bfa0095", size = 7162, upload-time = "2024-11-07T14:57:21.109Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c4/ec/38443b1f2a3821bbcb24e46cd8ba979154417794d54baf949fefde1c2146/mkdocs_redirects-1.2.2-py3-none-any.whl", hash = "sha256:7dbfa5647b79a3589da4401403d69494bd1f4ad03b9c15136720367e1f340ed5", size = 6142, upload-time = "2024-11-07T14:57:19.143Z" },
+]
+
 [[package]]
 name = "mkdocstrings"
 version = "1.0.4"
@@ -3081,10 +3093,10 @@ name = "scikit-learn"
 version = "1.8.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "joblib" },
-    { name = "numpy" },
-    { name = "scipy" },
-    { name = "threadpoolctl" },
+    { name = "joblib", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "numpy", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "scipy", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "threadpoolctl", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0e/d4/40988bf3b8e34feec1d0e6a051446b1f66225f8529b9309becaeef62b6c4/scikit_learn-1.8.0.tar.gz", hash = "sha256:9bccbb3b40e3de10351f8f5068e105d0f4083b1a65fa07b6634fbc401a6287fd", size = 7335585, upload-time = "2025-12-10T07:08:53.618Z" }
 wheels = [
@@ -3107,7 +3119,7 @@ name = "scipy"
 version = "1.17.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy" },
+    { name = "numpy", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/7a/97/5a3609c4f8d58b039179648e62dd220f89864f56f7357f5d4f45c29eb2cc/scipy-1.17.1.tar.gz", hash = "sha256:95d8e012d8cb8816c226aef832200b1d45109ed4464303e997c5b13122b297c0", size = 30573822, upload-time = "2026-02-23T00:26:24.851Z" }
 wheels = [
@@ -3138,16 +3150,16 @@ name = "sentence-transformers"
 version = "5.4.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "huggingface-hub" },
-    { name = "numpy" },
-    { name = "scikit-learn" },
-    { name = "scipy" },
-    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "huggingface-hub", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "numpy", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "scikit-learn", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "scipy", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
     { name = "torch", version = "2.11.0", source = { registry = "https://pypi.org/simple" }, marker = "(extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "tqdm" },
-    { name = "transformers" },
-    { name = "typing-extensions" },
+    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
+    { name = "tqdm", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "transformers", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "typing-extensions", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/4d/68/7f98c221940ce783b492ad6140384daf2e2918cd7175009d6a362c22b9ee/sentence_transformers-5.4.1.tar.gz", hash = "sha256:436bcb1182a0ff42a8fb2b1c43498a70d0a75b688d182f2cd0d1dd115af61ddc", size = 428910, upload-time = "2026-04-14T13:34:59.006Z" }
 wheels = [
@@ -3292,7 +3304,7 @@ name = "sympy"
 version = "1.14.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "mpmath" },
+    { name = "mpmath", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/83/d3/803453b36afefb7c2bb238361cd4ae6125a569b4db67cd9e79846ba2d68c/sympy-1.14.0.tar.gz", hash = "sha256:d3d3fe8df1e5a0b42f0e7bdf50541697dbe7d23746e894990c030e2b05e72517", size = 7793921, upload-time = "2025-04-27T18:05:01.611Z" }
 wheels = [
@@ -3337,14 +3349,14 @@ distributed = [
 ]
 fine-tune-cpu = [
     { name = "sentence-transformers" },
-    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
 ]
 fine-tune-gpu = [
     { name = "sentence-transformers" },
-    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
     { name = "torch", version = "2.11.0", source = { registry = "https://pypi.org/simple" }, marker = "(extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu') or (extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
 ]
 postgres = [
     { name = "psycopg", extra = ["binary"] },
@@ -3362,6 +3374,7 @@ dev = [
     { name = "griffe-pydantic" },
     { name = "hypothesis" },
     { name = "mkdocs-d2-plugin" },
+    { name = "mkdocs-redirects" },
     { name = "mkdocstrings", extra = ["python"] },
     { name = "mypy" },
     { name = "nats-py" },
@@ -3392,19 +3405,20 @@ docs = [
     { name = "defusedxml" },
     { name = "griffe-pydantic" },
     { name = "mkdocs-d2-plugin" },
+    { name = "mkdocs-redirects" },
     { name = "mkdocstrings", extra = ["python"] },
     { name = "zensical" },
 ]
 fine-tune-cpu = [
     { name = "sentence-transformers" },
-    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu')" },
-    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu')" },
 ]
 fine-tune-gpu = [
     { name = "sentence-transformers" },
-    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
     { name = "torch", version = "2.11.0", source = { registry = "https://pypi.org/simple" }, marker = "(extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "torch", version = "2.11.0+cpu", source = { registry = "https://download.pytorch.org/whl/cpu" }, marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
 ]
 test = [
     { name = "hypothesis" },
@@ -3471,6 +3485,7 @@ dev = [
     { name = "griffe-pydantic", specifier = "==1.3.1" },
     { name = "hypothesis", specifier = "==6.152.4" },
     { name = "mkdocs-d2-plugin", specifier = "==1.7.0" },
+    { name = "mkdocs-redirects", specifier = "==1.2.2" },
     { name = "mkdocstrings", extras = ["python"], specifier = "==1.0.4" },
     { name = "mypy", specifier = "==1.20.2" },
     { name = "nats-py", specifier = "==2.14.0" },
@@ -3501,6 +3516,7 @@ docs = [
     { name = "defusedxml", specifier = "==0.7.1" },
     { name = "griffe-pydantic", specifier = "==1.3.1" },
     { name = "mkdocs-d2-plugin", specifier = "==1.7.0" },
+    { name = "mkdocs-redirects", specifier = "==1.2.2" },
     { name = "mkdocstrings", extras = ["python"], specifier = "==1.0.4" },
     { name = "zensical", specifier = "==0.0.40" },
 ]
@@ -3676,17 +3692,16 @@ name = "torch"
 version = "2.11.0"
 source = { registry = "https://download.pytorch.org/whl/cpu" }
 resolution-markers = [
-    "python_full_version >= '3.15' and sys_platform == 'darwin'",
     "python_full_version < '3.15' and sys_platform == 'darwin'",
 ]
 dependencies = [
-    { name = "filelock", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "fsspec", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "jinja2", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "networkx", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "setuptools", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "sympy", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "typing-extensions", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "filelock", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "fsspec", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "jinja2", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "networkx", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "setuptools", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "sympy", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "typing-extensions", marker = "(python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and sys_platform == 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
 ]
 wheels = [
     { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.11.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:072a0d6e4865e8b0dc0dbfe6ebed68fae235124222835ef03e5814d414d8c012", upload-time = "2026-03-23T15:17:10Z" },
@@ -3735,23 +3750,27 @@ source = { registry = "https://download.pytorch.org/whl/cpu" }
 resolution-markers = [
     "python_full_version >= '3.15' and sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version < '3.15' and sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
+    "python_full_version >= '3.15' and sys_platform == 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version >= '3.15' and sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version < '3.15' and sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu'",
+    "python_full_version >= '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version >= '3.15' and sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version < '3.15' and sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
+    "python_full_version >= '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version >= '3.15' and sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version < '3.15' and sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
+    "python_full_version >= '3.15' and sys_platform == 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra != 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
     "python_full_version < '3.15' and sys_platform != 'darwin' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra != 'group-8-synthorg-fine-tune-gpu'",
 ]
 dependencies = [
-    { name = "filelock", marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "fsspec", marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "jinja2", marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "networkx", marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "setuptools", marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "sympy", marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
-    { name = "typing-extensions", marker = "(python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (python_full_version >= '3.15' and extra != 'extra-8-synthorg-fine-tune-cpu' and extra != 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (extra == 'extra-8-synthorg-fine-tune-gpu' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu')" },
+    { name = "filelock", marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
+    { name = "fsspec", marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
+    { name = "jinja2", marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
+    { name = "networkx", marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
+    { name = "setuptools", marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
+    { name = "sympy", marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
+    { name = "typing-extensions", marker = "(python_full_version >= '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu') or (python_full_version >= '3.15' and extra == 'group-8-synthorg-fine-tune-cpu') or (python_full_version < '3.15' and extra == 'extra-8-synthorg-fine-tune-cpu' and extra == 'extra-8-synthorg-fine-tune-gpu') or (python_full_version < '3.15' and extra == 'group-8-synthorg-fine-tune-cpu' and extra == 'group-8-synthorg-fine-tune-gpu') or (sys_platform != 'darwin' and extra == 'extra-8-synthorg-fine-tune-cpu') or (sys_platform != 'darwin' and extra == 'group-8-synthorg-fine-tune-cpu')" },
 ]
 wheels = [
     { url = "https://download-r2.pytorch.org/whl/cpu/torch-2.11.0%2Bcpu-cp314-cp314-linux_s390x.whl", hash = "sha256:c9a14c367f470623b978e273a4e1915995b4ba7a0ae999178b06c273eea3536f", upload-time = "2026-04-28T00:07:54Z" },
@@ -3782,15 +3801,15 @@ name = "transformers"
 version = "5.8.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "huggingface-hub" },
-    { name = "numpy" },
-    { name = "packaging" },
-    { name = "pyyaml" },
-    { name = "regex" },
-    { name = "safetensors" },
-    { name = "tokenizers" },
-    { name = "tqdm" },
-    { name = "typer" },
+    { name = "huggingface-hub", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "numpy", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "packaging", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "pyyaml", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "regex", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "safetensors", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "tokenizers", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "tqdm", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
+    { name = "typer", marker = "extra == 'extra-8-synthorg-fine-tune-cpu' or extra == 'extra-8-synthorg-fine-tune-gpu' or extra == 'group-8-synthorg-fine-tune-cpu' or extra == 'group-8-synthorg-fine-tune-gpu'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/e7/e6/4134ea2fbea322cddc7ffc94a0d8ee47fe32ce8e876b320cd37d88edfc4d/transformers-5.8.1.tar.gz", hash = "sha256:4dd5b6de4105725104d84fd6abd74b305f4debfc251b38c648ee5dd087cf543b", size = 8532019, upload-time = "2026-05-13T03:21:57.234Z" }
 wheels = [
diff --git a/web/Caddyfile b/web/Caddyfile
index bce47e64e3..350975bec4 100644
--- a/web/Caddyfile
+++ b/web/Caddyfile
@@ -139,6 +139,17 @@
 		redir /docs/ permanent
 	}
 
+	# --- Legacy doc URL redirects (must precede the generic /docs/* handler) ---
+	# Keep old inbound links working when docs were moved or renamed.
+	# Add an entry here when relocating a page; remove once the link
+	# source is updated.
+	@legacy_getting_started path /docs/getting-started /docs/getting-started/
+	redir @legacy_getting_started /docs/getting_started/ permanent
+	@legacy_decisions path /docs/decisions /docs/decisions/
+	redir @legacy_decisions /docs/architecture/decisions/ permanent
+	@legacy_comparison path /docs/comparison /docs/comparison/
+	redir @legacy_comparison /docs/reference/comparison/ permanent
+
 	# --- Static MkDocs documentation (no nonce) ---
 	handle /docs/* {
 		header {

From b3141dfb6c01d8ad891c46d8fc3bc6144a999fb1 Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 18:00:25 +0200
Subject: [PATCH 06/11] docs(wp5): retire stale temporal-drift labels

- docs/guides/agent-management.md: TaskReassignmentStrategy and
  MemoryArchivalStrategy concrete classes already ship; reword to say
  the strategies are not wired into the DELETE flow rather than the
  inaccurate 'not yet implemented'. Drop the (planned) heading on the
  rehire section and point at the issue tracker.
- docs/guides/budget.md: rewrite report-generation note to drop
  'planned but not yet implemented' (point at the issue tracker).
- docs/design/a2a-protocol.md: reword the quadratic enforcement note
  to describe alert_only as shipped and the other three modes as
  defined-in-config but not wired into MessageBus.publish (matches
  the actual code state).
- docs/research/multi-agent-failure-audit.md and
  docs/research/s1-multi-agent-decision.md: drop the v0.8+ forward
  reference; describe the templates as backlog instead.
---
 docs/design/a2a-protocol.md                | 2 +-
 docs/guides/agent-management.md            | 6 +++---
 docs/guides/budget.md                      | 2 +-
 docs/research/multi-agent-failure-audit.md | 2 +-
 docs/research/s1-multi-agent-decision.md   | 2 +-
 5 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/design/a2a-protocol.md b/docs/design/a2a-protocol.md
index 461d6274c6..5386149715 100644
--- a/docs/design/a2a-protocol.md
+++ b/docs/design/a2a-protocol.md
@@ -103,7 +103,7 @@ Four enforcement strategies are defined behind `QuadraticEnforcementStrategy`:
 | `hard_block` | Reject new connections when `max_agent_connections` exceeded |
 | `disabled` | No detection or enforcement |
 
-Only `alert_only` ships today; the other three are defined in config but not yet implemented. See [Security -> Quadratic Communication Enforcement](security.md#quadratic-communication-enforcement).
+`alert_only` is the shipped enforcement strategy. `soft_throttle`, `hard_block`, and `disabled` are defined in config; the dispatch shape is in place but the per-mode behaviour is not yet wired into `MessageBus.publish`. See [Security -> Quadratic Communication Enforcement](security.md#quadratic-communication-enforcement).
 
 ## Configuration Summary
 
diff --git a/docs/guides/agent-management.md b/docs/guides/agent-management.md
index 98e7c8338e..c71b5a4fe8 100644
--- a/docs/guides/agent-management.md
+++ b/docs/guides/agent-management.md
@@ -93,11 +93,11 @@ Current behavior (`delete_agent` in `src/synthorg/api/services/_org_agent_mutati
 2. The agent record is removed from the active org configuration.
 3. A company snapshot is persisted and an `API_AGENT_DELETED` event is logged and broadcast on the `agents` WebSocket channel.
 
-Planned (not yet implemented): automated task reassignment via `TaskReassignmentStrategy`, memory archival via `MemoryArchivalStrategy`, selective promotion to `OrgMemoryBackend`, and an explicit `TERMINATED` lifecycle state. Until those land, fires are best paired with manual task reassignment before the DELETE call.
+Not yet wired into the DELETE flow: automated task reassignment via `TaskReassignmentStrategy` (concrete: `QueueReturnStrategy` in `src/synthorg/hr/queue_return_strategy.py`), memory archival via `MemoryArchivalStrategy` (concrete: `FullSnapshotStrategy` in `src/synthorg/hr/full_snapshot_strategy.py`), selective promotion to `OrgMemoryBackend`, and an explicit `TERMINATED` lifecycle state. The strategies exist as part of the offboarding-service shape but the API DELETE handler does not invoke them; fires are best paired with manual task reassignment before the DELETE call.
 
-## Rehiring from archive (planned)
+## Rehiring from archive
 
-A dedicated `POST /api/v1/agents/{agent_name}/rehire` endpoint (which would restore archived memory into a new identity with a fresh hire date and version chain) is **not yet implemented** in the agents controller. Until it ships, rehiring is a manual two-step: list archived agents via the existing listing, then recreate with `POST /api/v1/agents` using a fresh `CreateAgentOrgRequest` payload; memory restoration is performed out-of-band through the Memory Admin API. This planned surface sits alongside the same lifecycle automation called out in [Firing](#firing).
+A dedicated `POST /api/v1/agents/{agent_name}/rehire` endpoint (which would restore archived memory into a new identity with a fresh hire date and version chain) is not implemented in the agents controller. Rehiring is a manual two-step today: list archived agents via the existing listing, then recreate with `POST /api/v1/agents` using a fresh `CreateAgentOrgRequest` payload; memory restoration is performed out-of-band through the Memory Admin API. The endpoint sits alongside the same lifecycle automation called out in [Firing](#firing); track on the GitHub issue tracker.
 
 ## Lifecycle events (WebSocket)
 
diff --git a/docs/guides/budget.md b/docs/guides/budget.md
index 7818c51fa0..cdf24b79d2 100644
--- a/docs/guides/budget.md
+++ b/docs/guides/budget.md
@@ -275,7 +275,7 @@ curl "http://localhost:3001/api/v1/budget/records?task_id=${TASK_ID}" \
 
 The response includes `data` (paginated records), `daily_summary` (per-day totals aggregated across ALL matching records, not just the page), and `period_summary` (overall totals + computed `avg_cost`).
 
-Supported query parameters: `agent_id`, `task_id`, `offset`, `limit`. Additional slicing (by provider, model, tag, project, date range) is done client-side from the paginated response today; a dedicated report-generation endpoint is planned but not yet implemented.
+Supported query parameters: `agent_id`, `task_id`, `offset`, `limit`. Additional slicing (by provider, model, tag, project, date range) is done client-side from the paginated response. A dedicated report-generation endpoint with server-side slicing is tracked on the GitHub issue tracker.
 
 ### Budget alert webhook integration
 
diff --git a/docs/research/multi-agent-failure-audit.md b/docs/research/multi-agent-failure-audit.md
index cd2b30b87d..50166a402d 100644
--- a/docs/research/multi-agent-failure-audit.md
+++ b/docs/research/multi-agent-failure-audit.md
@@ -420,7 +420,7 @@ appendix maps each risk to SynthOrg coverage. Full analysis in
 
 | # | Risk | Coverage | Location / Action |
 |---|---|---|---|
-| 1.1 | Tacit collusion | Gap (low priority) | Only relevant for negotiation/client-simulation templates (v0.8+). |
+| 1.1 | Tacit collusion | Gap (low priority) | Only relevant for negotiation / client-simulation templates that are still on the backlog. |
 | 1.2 | Priority monopolization | Partial | `budget/coordination_config.py`; no fee/rotation mechanism yet. |
 | 1.3 | Competitive task avoidance | Partial | Manual / hierarchical strategies safe; `AuctionAssignmentStrategy` vulnerable. |
 | 1.4 | Strategic information withholding | Gap (low priority) | Material only for adversarial A2A federation. Constraint on #1253. |
diff --git a/docs/research/s1-multi-agent-decision.md b/docs/research/s1-multi-agent-decision.md
index f5f00790f0..ab0a025d3c 100644
--- a/docs/research/s1-multi-agent-decision.md
+++ b/docs/research/s1-multi-agent-decision.md
@@ -59,7 +59,7 @@ For each risk: coverage status, SynthOrg design location, and action.
 
 | # | Risk | Coverage | Location | Action |
 |---|---|---|---|---|
-| **1.1** | Tacit collusion | **Gap** (low priority) | - | LATER: mechanism-level anti-collusion only relevant for negotiation/client-simulation templates (v0.8+). |
+| **1.1** | Tacit collusion | **Gap** (low priority) | - | LATER: mechanism-level anti-collusion only relevant for negotiation / client-simulation templates on the backlog. |
 | **1.2** | Priority monopolization | **Partial** | `budget/coordination_config.py`, task priority field | Current priority is manual/role-based; no fee/rotation mechanism. LATER: relevant only when multiple clients compete for shared agent pool. |
 | **1.3** | Competitive task avoidance | **Partial** | `TaskAssignmentStrategy` (6 strategies) | Manual / hierarchical hard-bind is a mitigation by design. `AuctionAssignmentStrategy` is vulnerable; document risk in docstring. |
 | **1.4** | Strategic information withholding | **Gap** (low priority) | `Message` parts have no integrity proofs | LATER: only material for adversarial A2A federation. Ties to R4. |

From 34be3dc14abe801486db662621d97e8232d84b74 Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 18:02:44 +0200
Subject: [PATCH 07/11] docs(wp5): fix config example schema drift

docs/guides/company-config.md: expand persistence example with the
SQLite wal_mode/journal_size_limit fields and the Postgres TimescaleDB
block (enable_timescaledb plus chunk_interval). Annotate every field
with its default. Add a Cross-provider Fallback tab to Provider
Examples showing primary provider degradation pointing at a secondary
provider that exposes the same alias names so routing hands off
cleanly. Promote the routing constraint 'at least one of role_level or
task_type' out of a trailing admonition into the introductory paragraph.

docs/guides/workflow-api.md: add a Company-Level Workflow Configuration
section with the WorkflowConfig schema and a table of which sub-configs
each workflow_type reads.

A2AConfig is already documented in design/security.md and design/a2a-protocol.md.
---
 docs/guides/company-config.md | 70 +++++++++++++++++++++++++++--------
 docs/guides/workflow-api.md   | 48 ++++++++++++++++++++++++
 2 files changed, 102 insertions(+), 16 deletions(-)

diff --git a/docs/guides/company-config.md b/docs/guides/company-config.md
index 821ca4d0b8..01be5bac85 100644
--- a/docs/guides/company-config.md
+++ b/docs/guides/company-config.md
@@ -188,6 +188,41 @@ Each provider lists its available models under the `models` key:
             alias: "medium"
     ```
 
+=== "Cross-provider Fallback"
+
+    Configure a secondary provider that takes over when the primary
+    rejects, rate-limits, or times out a request. The `degradation`
+    block on the primary names the fallback provider; agents resolve
+    the alias on the secondary when degradation fires.
+
+    ```yaml
+    providers:
+      primary-cloud:
+        auth_type: api_key
+        api_key: "sk-..."
+        degradation:
+          fallback_provider: secondary-cloud
+          trigger_on:
+            - rate_limit
+            - provider_timeout
+            - provider_connection
+        models:
+          - id: "example-large-001"
+            alias: "large"
+          - id: "example-small-001"
+            alias: "small"
+      secondary-cloud:
+        auth_type: api_key
+        api_key: "sk-backup-..."
+        models:
+          # Both providers expose the same alias names so the routing
+          # layer can hand off without reconfiguring agents.
+          - id: "alt-large-001"
+            alias: "large"
+          - id: "alt-small-001"
+            alias: "small"
+    ```
+
 ---
 
 ## Model Routing
@@ -207,7 +242,7 @@ The `routing` section controls how models are selected for agent tasks.
 
 ### Routing Rules
 
-Rules are evaluated in order. Each rule matches by `role_level` and/or `task_type`:
+Rules are evaluated in order. Each rule matches by `role_level` and / or `task_type`. **Validation: at least one of `role_level` or `task_type` MUST be set per rule.** A rule with both fields null is rejected at company-load time with a `ConfigValidationError`.
 
 ```yaml
 routing:
@@ -232,10 +267,6 @@ routing:
 | `preferred_model` | string | *(required)* | Preferred model alias or ID |
 | `fallback` | string | `null` | Fallback model |
 
-!!! note
-
-    At least one of `role_level` or `task_type` must be set per rule.
-
 ---
 
 ## Agents
@@ -301,20 +332,27 @@ Operational data persistence (tasks, cost records, messages, workflows, audit en
 persistence:
   backend: "postgres"              # "sqlite" (default) or "postgres"
   sqlite:
-    path: "/data/synthorg.db"    # file path; used when backend == "sqlite"
-  postgres:                        # used when backend == "postgres"
+    path: "/data/synthorg.db"      # file path; used when backend == "sqlite"
+    wal_mode: true                 # enable WAL journal mode (default)
+    journal_size_limit: 67108864   # WAL journal cap in bytes (default 64 MB)
+  postgres:                        # required when backend == "postgres"
     host: "db.internal"
-    port: 5432
+    port: 5432                     # default 5432
     database: "synthorg"
     username: "synthorg_app"
-    password: "${POSTGRES_PASSWORD}"  # SecretStr -- redacted from logs
-    ssl_mode: "verify-full"          # prefer verify-full in production
-    pool_min_size: 1
-    pool_max_size: 10
-    pool_timeout_seconds: 30.0
-    application_name: "synthorg"
-    statement_timeout_ms: 30000
-    connect_timeout_seconds: 10.0
+    password: "${POSTGRES_PASSWORD}"  # SecretStr; redacted from logs
+    ssl_mode: "verify-full"        # default "require"; prefer "verify-full" in prod
+    pool_min_size: 1               # default 1
+    pool_max_size: 10              # default 10; must be >= pool_min_size
+    pool_timeout_seconds: 30.0     # default 30.0
+    application_name: "synthorg"   # appears in pg_stat_activity
+    statement_timeout_ms: 30000    # default 30000 (0 disables)
+    connect_timeout_seconds: 10.0  # default 10.0
+    # TimescaleDB hypertable support (Apache-2.0 features only).
+    # Not available on managed Postgres providers (RDS, Cloud SQL, Azure).
+    enable_timescaledb: false
+    cost_records_chunk_interval: "1 day"
+    audit_entries_chunk_interval: "1 day"
 ```
 
 The Postgres backend requires the optional extra: install with
diff --git a/docs/guides/workflow-api.md b/docs/guides/workflow-api.md
index 63083cae43..69fbf2af01 100644
--- a/docs/guides/workflow-api.md
+++ b/docs/guides/workflow-api.md
@@ -215,6 +215,54 @@ See the [engine design](../design/engine.md#subworkflows) for the full subworkfl
 
 ---
 
+---
+
+## Company-Level Workflow Configuration
+
+The runtime workflow type (Kanban, Agile Kanban, sequential, parallel)
+and its sub-config (board columns, sprint cadence, ceremony policy) is
+configured in the company YAML alongside agents and providers. The
+runtime engine consults the active type only; the inactive
+sub-configs are accepted for convenience but emit a
+`WORKFLOW_CONFIG_UNUSED_SUBCONFIG` warning if customised.
+
+```yaml
+workflow:
+  workflow_type: agile_kanban     # kanban | agile_kanban | sequential | parallel
+  kanban:
+    columns:
+      - name: "To Do"
+        wip_limit: null           # null = unlimited
+      - name: "In Progress"
+        wip_limit: 4
+      - name: "In Review"
+        wip_limit: 2
+      - name: "Done"
+        wip_limit: null
+  sprint:
+    duration_days: 14
+    velocity_calculator: "rolling_average"
+    auto_transition: true
+    ceremonies:
+      planning_strategy: "fixed_start"
+      retro_strategy: "fixed_end"
+```
+
+The active `workflow_type` controls which sub-config blocks the engine
+reads:
+
+| `workflow_type` | Reads `kanban` | Reads `sprint` |
+|------------------|----------------|----------------|
+| `KANBAN` | yes | no |
+| `AGILE_KANBAN` | yes | yes |
+| `SEQUENTIAL` / `PARALLEL` | no | no |
+
+Customising an unused sub-config block does not break anything; the
+engine emits a single advisory warning at company-load time so
+operators can clean the YAML up at their leisure.
+
+---
+
 ## See Also
 
 - [OpenAPI Reference](../openapi/index.md): full schema for every endpoint

From 3731148fedb083ee52513a7eeb2843caa6355f6e Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 18:11:28 +0200
Subject: [PATCH 08/11] docs(wp5): clarify verification stage vs review
 pipeline ordering and OpenAPI params

docs/design/verification-quality.md: add an Order of Operations
section with a table that places each quality and approval surface
(AUTH_REQUIRED park, verification stage, review pipeline) on the task
lifecycle and lists trigger, task status during the phase, and exit
transitions. Names the canonical home for each.

scripts/generate_dto_types_ts.py regenerates web/src/api/types/
openapi.gen.ts to surface the new Parameter description= strings on
the wire types so the Scalar UI and TypeScript codegen stay in sync.

Tightened the descriptions added in the previous commit to fit the
ruff 88-character line limit.
---
 docs/design/verification-quality.md           | 31 +++++++++++
 .../controllers/agent_identity_versions.py    |  8 ++-
 src/synthorg/api/controllers/approvals.py     |  8 ++-
 src/synthorg/api/controllers/audit.py         | 53 ++++++++++++++++---
 src/synthorg/api/controllers/budget.py        | 18 ++++++-
 .../api/controllers/budget_config_versions.py |  8 ++-
 .../api/controllers/ceremony_policy.py        |  5 +-
 .../api/controllers/company_versions.py       |  8 ++-
 .../api/controllers/coordination_metrics.py   | 18 ++++++-
 .../controllers/evaluation_config_versions.py |  8 ++-
 src/synthorg/api/controllers/events.py        |  2 +
 src/synthorg/api/controllers/meetings.py      |  8 ++-
 .../api/controllers/meta_analytics.py         |  7 ++-
 src/synthorg/api/controllers/providers.py     | 27 ++++++++--
 src/synthorg/api/controllers/role_versions.py |  8 ++-
 src/synthorg/api/controllers/subworkflows.py  | 18 +++++--
 src/synthorg/api/controllers/tasks.py         | 18 ++++++-
 .../api/controllers/workflow_versions.py      |  8 ++-
 web/src/api/types/openapi.gen.ts              | 15 ++++++
 19 files changed, 248 insertions(+), 28 deletions(-)

diff --git a/docs/design/verification-quality.md b/docs/design/verification-quality.md
index 66e8c28fc4..418b7b57ae 100644
--- a/docs/design/verification-quality.md
+++ b/docs/design/verification-quality.md
@@ -134,6 +134,37 @@ intake strategy contracts.
 
 ---
 
+## Order of Operations
+
+The four quality and approval surfaces (verification stage, review
+pipeline, mid-execution `AUTH_REQUIRED` park, post-completion
+`IN_REVIEW` gate) operate at distinct points in the task lifecycle.
+
+| Phase | Surface | Trigger | Task status during | Exit | Where documented |
+|-------|---------|---------|--------------------|------|------------------|
+| Mid-execution | `AUTH_REQUIRED` park | Agent calls a tool that requires approval at runtime (e.g. `deploy`, `db:admin`). Driven by `ApprovalGate` middleware. | `AUTH_REQUIRED` | Approved: returns to `ASSIGNED`. Denied / timeout: `CANCELLED`. | [Security: Approval Workflow](security.md#approval-workflow) |
+| Agent done | Verification stage | Workflow blueprint has a `VERIFICATION` control-flow node. Runs as a separate evaluator agent with its own context. | `IN_PROGRESS` (engine-internal) | Pass: continue to next node. Fail: regenerate. Refer: hand to human via `VERIFICATION_REFER` edge. | This page, [Workflow Node and Edge Types](#workflow-node-and-edge-types) |
+| Agent done | Review pipeline | Task transitions `IN_PROGRESS` to `IN_REVIEW`. Chain of `ReviewStage` instances runs. | `IN_REVIEW` | First-failing stage returns the task to `IN_PROGRESS`; all-pass moves to `COMPLETED`. | This page, [Review Pipeline](#review-pipeline) |
+
+Key invariants:
+
+- `AUTH_REQUIRED` is the mid-execution park reason and uses the
+  `ApprovalGate` middleware in the agent harness. The review pipeline
+  is the post-completion quality gate and uses `ReviewGateService`.
+  The two are independent: a single task can encounter both (e.g.
+  pause for deploy approval mid-task, then enter `IN_REVIEW` once the
+  agent finishes).
+- The verification stage runs BEFORE the review pipeline when both
+  are configured for the same workflow. Verification is a workflow
+  blueprint construct (a node in the graph); the review pipeline
+  fires on the `IN_PROGRESS` to `IN_REVIEW` transition that happens
+  after the workflow's last node completes.
+- The review pipeline does not mint new `TaskStatus` values; the
+  task stays at `IN_REVIEW` throughout, with stage progress in
+  metadata.
+
+---
+
 ## See Also
 
 - [Task & Workflow Engine](engine.md): task dispatch, state coordination
diff --git a/src/synthorg/api/controllers/agent_identity_versions.py b/src/synthorg/api/controllers/agent_identity_versions.py
index 94f836031d..6074df85fc 100644
--- a/src/synthorg/api/controllers/agent_identity_versions.py
+++ b/src/synthorg/api/controllers/agent_identity_versions.py
@@ -178,7 +178,13 @@ async def get_version(
         self,
         state: State,
         agent_id: PathId,
-        version_num: Annotated[int, Parameter(ge=1)],
+        version_num: Annotated[
+            int,
+            Parameter(
+                ge=1,
+                description="Agent identity version (one-based; 1 = first revision).",
+            ),
+        ],
     ) -> ApiResponse[SnapshotT]:
         """Get a specific agent identity version snapshot."""
         version = await state.app_state.agent_version_service.get_version(
diff --git a/src/synthorg/api/controllers/approvals.py b/src/synthorg/api/controllers/approvals.py
index e08bc08cea..797484fd84 100644
--- a/src/synthorg/api/controllers/approvals.py
+++ b/src/synthorg/api/controllers/approvals.py
@@ -516,7 +516,13 @@ async def list_approvals(  # noqa: PLR0913
         state: State,
         status: ApprovalStatus | None = None,
         risk_level: ApprovalRiskLevel | None = None,
-        action_type: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)]
+        action_type: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to approvals raised for this action type.",
+            ),
+        ]
         | None = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
diff --git a/src/synthorg/api/controllers/audit.py b/src/synthorg/api/controllers/audit.py
index b3b31e48a9..ebd69f78a2 100644
--- a/src/synthorg/api/controllers/audit.py
+++ b/src/synthorg/api/controllers/audit.py
@@ -94,17 +94,58 @@ class AuditController(Controller):
     async def list_audit_entries(  # noqa: PLR0913
         self,
         state: State,
-        agent_id: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)] | None = None,
-        tool_name: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)] | None = None,
-        action_type: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)]
+        agent_id: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to audit entries emitted for this agent.",
+            ),
+        ]
+        | None = None,
+        tool_name: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to audit entries emitted for this tool.",
+            ),
+        ]
+        | None = None,
+        action_type: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to audit entries with this action type.",
+            ),
+        ]
+        | None = None,
+        verdict: Annotated[
+            str,
+            Parameter(
+                max_length=50,
+                description="Filter by verdict (APPROVED / DENIED).",
+            ),
+        ]
         | None = None,
-        verdict: Annotated[str, Parameter(max_length=50)] | None = None,
         since: datetime | None = None,
         until: datetime | None = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
-        jsonb_contains: Annotated[str, Parameter(max_length=2048)] | None = None,
-        jsonb_key_exists: Annotated[str, Parameter(max_length=256)] | None = None,
+        jsonb_contains: Annotated[
+            str,
+            Parameter(
+                max_length=2048,
+                description="JSONB containment filter (Postgres @>); JSON-encoded.",
+            ),
+        ]
+        | None = None,
+        jsonb_key_exists: Annotated[
+            str,
+            Parameter(
+                max_length=256,
+                description="Filter to entries whose payload has this top-level key.",
+            ),
+        ]
+        | None = None,
     ) -> PaginatedResponse[AuditEntry]:
         """Query audit entries with optional filters.
 
diff --git a/src/synthorg/api/controllers/budget.py b/src/synthorg/api/controllers/budget.py
index 9d1593eabd..65854c4f08 100644
--- a/src/synthorg/api/controllers/budget.py
+++ b/src/synthorg/api/controllers/budget.py
@@ -297,8 +297,22 @@ async def get_budget_config(
     async def list_cost_records(
         self,
         state: State,
-        agent_id: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)] | None = None,
-        task_id: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)] | None = None,
+        agent_id: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to cost records emitted by this agent.",
+            ),
+        ]
+        | None = None,
+        task_id: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to cost records emitted under this task.",
+            ),
+        ]
+        | None = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> CostRecordListResponse:
diff --git a/src/synthorg/api/controllers/budget_config_versions.py b/src/synthorg/api/controllers/budget_config_versions.py
index 0c8bbdc996..2d85b6ab6b 100644
--- a/src/synthorg/api/controllers/budget_config_versions.py
+++ b/src/synthorg/api/controllers/budget_config_versions.py
@@ -81,7 +81,13 @@ async def list_versions(
     async def get_version(
         self,
         state: State,
-        version_num: Annotated[int, Parameter(ge=1)],
+        version_num: Annotated[
+            int,
+            Parameter(
+                ge=1,
+                description="Budget config version (one-based; 1 = first revision).",
+            ),
+        ],
     ) -> Response[ApiResponse[SnapshotT]]:
         """Get a specific budget config version snapshot."""
         repo = state.app_state.persistence.budget_config_versions
diff --git a/src/synthorg/api/controllers/ceremony_policy.py b/src/synthorg/api/controllers/ceremony_policy.py
index b92ca4fd44..cd82fc05b7 100644
--- a/src/synthorg/api/controllers/ceremony_policy.py
+++ b/src/synthorg/api/controllers/ceremony_policy.py
@@ -61,7 +61,10 @@ async def get_resolved_policy(
         state: State,
         department: Annotated[
             NotBlankStr | None,
-            Parameter(max_length=128),
+            Parameter(
+                max_length=128,
+                description="Department to resolve against; omit for project policy.",
+            ),
         ] = None,
     ) -> ApiResponse[ResolvedCeremonyPolicyResponse]:
         """Return the fully resolved ceremony policy with field origins."""
diff --git a/src/synthorg/api/controllers/company_versions.py b/src/synthorg/api/controllers/company_versions.py
index 43cdeff230..254dbdc5bc 100644
--- a/src/synthorg/api/controllers/company_versions.py
+++ b/src/synthorg/api/controllers/company_versions.py
@@ -81,7 +81,13 @@ async def list_versions(
     async def get_version(
         self,
         state: State,
-        version_num: Annotated[int, Parameter(ge=1)],
+        version_num: Annotated[
+            int,
+            Parameter(
+                ge=1,
+                description="Company version (one-based; 1 = first revision).",
+            ),
+        ],
     ) -> Response[ApiResponse[SnapshotT]]:
         """Get a specific company version snapshot."""
         repo = state.app_state.persistence.company_versions
diff --git a/src/synthorg/api/controllers/coordination_metrics.py b/src/synthorg/api/controllers/coordination_metrics.py
index 97a0607744..2f967ccf1e 100644
--- a/src/synthorg/api/controllers/coordination_metrics.py
+++ b/src/synthorg/api/controllers/coordination_metrics.py
@@ -89,8 +89,22 @@ class CoordinationMetricsController(Controller):
     async def list_coordination_metrics(  # noqa: PLR0913
         self,
         state: State,
-        task_id: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)] | None = None,
-        agent_id: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)] | None = None,
+        task_id: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to coordination metrics emitted under this task.",
+            ),
+        ]
+        | None = None,
+        agent_id: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter to coordination metrics emitted by this agent.",
+            ),
+        ]
+        | None = None,
         since: datetime | None = None,
         until: datetime | None = None,
         cursor: CursorParam = None,
diff --git a/src/synthorg/api/controllers/evaluation_config_versions.py b/src/synthorg/api/controllers/evaluation_config_versions.py
index 1f5ef48c89..b6c82fd76c 100644
--- a/src/synthorg/api/controllers/evaluation_config_versions.py
+++ b/src/synthorg/api/controllers/evaluation_config_versions.py
@@ -81,7 +81,13 @@ async def list_versions(
     async def get_version(
         self,
         state: State,
-        version_num: Annotated[int, Parameter(ge=1)],
+        version_num: Annotated[
+            int,
+            Parameter(
+                ge=1,
+                description="Evaluation config version (one-based).",
+            ),
+        ],
     ) -> Response[ApiResponse[SnapshotT]]:
         """Get a specific evaluation config version snapshot."""
         repo = state.app_state.persistence.evaluation_config_versions
diff --git a/src/synthorg/api/controllers/events.py b/src/synthorg/api/controllers/events.py
index 5f291f74bc..7c1cde67da 100644
--- a/src/synthorg/api/controllers/events.py
+++ b/src/synthorg/api/controllers/events.py
@@ -546,6 +546,7 @@ async def stream(
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 pattern=_SESSION_ID_PATTERN,
+                description="Session ID whose AG-UI stream to subscribe to.",
             ),
         ],
     ) -> ServerSentEvent:
@@ -623,6 +624,7 @@ async def list_interrupts(
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 pattern=_SESSION_ID_PATTERN,
+                description="Filter to interrupts for this session; omit to list all.",
             ),
         ] = None,
     ) -> ApiResponse[tuple[InterruptResponse, ...]]:
diff --git a/src/synthorg/api/controllers/meetings.py b/src/synthorg/api/controllers/meetings.py
index 200d4337b3..898d9d1e06 100644
--- a/src/synthorg/api/controllers/meetings.py
+++ b/src/synthorg/api/controllers/meetings.py
@@ -244,7 +244,13 @@ async def list_meetings(
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
         status: MeetingStatus | None = None,
-        meeting_type: Annotated[str, Parameter(max_length=QUERY_MAX_LENGTH)]
+        meeting_type: Annotated[
+            str,
+            Parameter(
+                max_length=QUERY_MAX_LENGTH,
+                description="Filter by meeting type (STAND_UP, RETRO, etc.).",
+            ),
+        ]
         | None = None,
     ) -> PaginatedResponse[MeetingResponse]:
         """List meeting records with optional filters.
diff --git a/src/synthorg/api/controllers/meta_analytics.py b/src/synthorg/api/controllers/meta_analytics.py
index bd2b232cf7..53ca4ca5aa 100644
--- a/src/synthorg/api/controllers/meta_analytics.py
+++ b/src/synthorg/api/controllers/meta_analytics.py
@@ -114,7 +114,12 @@ async def ingest_events(
     async def get_patterns(
         self,
         state: State,
-        min_deployments: int = Parameter(default=3, ge=1, le=100),
+        min_deployments: int = Parameter(
+            default=3,
+            ge=1,
+            le=100,
+            description="Minimum deployment count for a pattern to be returned.",
+        ),
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[AggregatedPattern]:
diff --git a/src/synthorg/api/controllers/providers.py b/src/synthorg/api/controllers/providers.py
index 91e924a38f..7490371b86 100644
--- a/src/synthorg/api/controllers/providers.py
+++ b/src/synthorg/api/controllers/providers.py
@@ -590,7 +590,14 @@ async def discover_models(
         self,
         state: State,
         name: PathName,
-        preset_hint: Annotated[str, Parameter(max_length=64)] | None = None,
+        preset_hint: Annotated[
+            str,
+            Parameter(
+                max_length=64,
+                description="Canonical preset hint (e.g. anthropic, ollama).",
+            ),
+        ]
+        | None = None,
     ) -> ApiResponse[DiscoverModelsResponse]:
         """Discover available models from a provider endpoint.
 
@@ -871,7 +878,14 @@ async def delete_model(
         self,
         state: State,
         name: PathName,
-        model_id: Annotated[str, Parameter(max_length=256, min_length=1)],
+        model_id: Annotated[
+            str,
+            Parameter(
+                max_length=256,
+                min_length=1,
+                description="Local provider model id (may contain colons).",
+            ),
+        ],
     ) -> None:
         """Delete a model from a local provider.
 
@@ -939,7 +953,14 @@ async def update_model_config(
         self,
         state: State,
         name: PathName,
-        model_id: Annotated[str, Parameter(max_length=256, min_length=1)],
+        model_id: Annotated[
+            str,
+            Parameter(
+                max_length=256,
+                min_length=1,
+                description="Local provider model whose launch parameters to update.",
+            ),
+        ],
         data: UpdateModelConfigRequest,
     ) -> ApiResponse[ProviderModelResponse]:
         """Update per-model launch parameters for a local provider.
diff --git a/src/synthorg/api/controllers/role_versions.py b/src/synthorg/api/controllers/role_versions.py
index 0492f1b98b..92ad024680 100644
--- a/src/synthorg/api/controllers/role_versions.py
+++ b/src/synthorg/api/controllers/role_versions.py
@@ -80,7 +80,13 @@ async def get_version(
         self,
         state: State,
         role_name: str,
-        version_num: Annotated[int, Parameter(ge=1)],
+        version_num: Annotated[
+            int,
+            Parameter(
+                ge=1,
+                description="Role version (one-based; 1 = first revision).",
+            ),
+        ],
     ) -> Response[ApiResponse[SnapshotT]]:
         """Get a specific role version snapshot."""
         repo = state.app_state.persistence.role_versions
diff --git a/src/synthorg/api/controllers/subworkflows.py b/src/synthorg/api/controllers/subworkflows.py
index 615bb5aa0e..ecb817eee6 100644
--- a/src/synthorg/api/controllers/subworkflows.py
+++ b/src/synthorg/api/controllers/subworkflows.py
@@ -255,7 +255,11 @@ async def get_version(
         subworkflow_id: PathId,
         version: Annotated[
             str,
-            Parameter(min_length=1, max_length=64),
+            Parameter(
+                min_length=1,
+                max_length=64,
+                description="Subworkflow version to fetch (semver-like, e.g. 1.0.0).",
+            ),
         ],
     ) -> Response[ApiResponse[WorkflowDefinition]]:
         """Fetch a specific subworkflow version.
@@ -280,7 +284,11 @@ async def list_parents(
         subworkflow_id: PathId,
         version: Annotated[
             str,
-            Parameter(min_length=1, max_length=64),
+            Parameter(
+                min_length=1,
+                max_length=64,
+                description="Subworkflow version pinned by the parent workflows.",
+            ),
         ],
         limit: CursorLimit = DEFAULT_LIMIT,
         cursor: CursorParam = None,
@@ -351,7 +359,11 @@ async def delete_version(
         subworkflow_id: PathId,
         version: Annotated[
             str,
-            Parameter(min_length=1, max_length=64),
+            Parameter(
+                min_length=1,
+                max_length=64,
+                description="Subworkflow version to delete (parents block).",
+            ),
         ],
     ) -> Response[ApiResponse[None]]:
         """Delete a subworkflow version.
diff --git a/src/synthorg/api/controllers/tasks.py b/src/synthorg/api/controllers/tasks.py
index 4d436d47f8..aefcaf883b 100644
--- a/src/synthorg/api/controllers/tasks.py
+++ b/src/synthorg/api/controllers/tasks.py
@@ -72,8 +72,22 @@ async def list_tasks(  # noqa: PLR0913
         self,
         state: State,
         status: TaskStatus | None = None,
-        assigned_to: Annotated[str, Parameter(max_length=256)] | None = None,
-        project: Annotated[str, Parameter(max_length=256)] | None = None,
+        assigned_to: Annotated[
+            str,
+            Parameter(
+                max_length=256,
+                description="Filter to tasks assigned to this agent.",
+            ),
+        ]
+        | None = None,
+        project: Annotated[
+            str,
+            Parameter(
+                max_length=256,
+                description="Filter to tasks scoped to this project.",
+            ),
+        ]
+        | None = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[Task]:
diff --git a/src/synthorg/api/controllers/workflow_versions.py b/src/synthorg/api/controllers/workflow_versions.py
index b3a6827892..ae52670384 100644
--- a/src/synthorg/api/controllers/workflow_versions.py
+++ b/src/synthorg/api/controllers/workflow_versions.py
@@ -96,7 +96,13 @@ async def get_version(
         self,
         state: State,
         workflow_id: PathId,
-        version_num: Annotated[int, Parameter(ge=1)],
+        version_num: Annotated[
+            int,
+            Parameter(
+                ge=1,
+                description="Workflow version (one-based; 1 = first revision).",
+            ),
+        ],
     ) -> Response[ApiResponse[SnapshotT]]:
         """Get a specific version snapshot."""
         version = await state.app_state.workflow_version_service.get_version(
diff --git a/web/src/api/types/openapi.gen.ts b/web/src/api/types/openapi.gen.ts
index 67a2eb9f32..95a6bda03a 100644
--- a/web/src/api/types/openapi.gen.ts
+++ b/web/src/api/types/openapi.gen.ts
@@ -13138,6 +13138,7 @@ export interface operations {
             readonly path: {
                 /** @description Resource identifier */
                 readonly agent_id: string;
+                /** @description Agent identity version (one-based; 1 = first revision). */
                 readonly version_num: number;
             };
             readonly cookie?: never;
@@ -14371,6 +14372,7 @@ export interface operations {
             readonly query?: never;
             readonly header?: never;
             readonly path: {
+                /** @description Budget config version (one-based; 1 = first revision). */
                 readonly version_num: number;
             };
             readonly cookie?: never;
@@ -14501,6 +14503,7 @@ export interface operations {
     readonly ApiV1CeremonyPolicyResolvedGetResolvedPolicy: {
         readonly parameters: {
             readonly query?: {
+                /** @description Department to resolve against; omit for project policy. */
                 readonly department?: string | null;
             };
             readonly header?: never;
@@ -14848,6 +14851,7 @@ export interface operations {
             readonly query?: never;
             readonly header?: never;
             readonly path: {
+                /** @description Company version (one-based; 1 = first revision). */
                 readonly version_num: number;
             };
             readonly cookie?: never;
@@ -15744,6 +15748,7 @@ export interface operations {
             readonly query?: never;
             readonly header?: never;
             readonly path: {
+                /** @description Evaluation config version (one-based). */
                 readonly version_num: number;
             };
             readonly cookie?: never;
@@ -15805,6 +15810,7 @@ export interface operations {
     readonly ApiV1EventsStreamStream: {
         readonly parameters: {
             readonly query: {
+                /** @description Session ID whose AG-UI stream to subscribe to. */
                 readonly session_id: string;
             };
             readonly header?: never;
@@ -16172,6 +16178,7 @@ export interface operations {
     readonly ApiV1InterruptsListInterrupts: {
         readonly parameters: {
             readonly query?: {
+                /** @description Filter to interrupts for this session; omit to list all. */
                 readonly session_id?: string | null;
             };
             readonly header?: never;
@@ -16539,6 +16546,7 @@ export interface operations {
                 readonly cursor?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Minimum deployment count for a pattern to be returned. */
                 readonly min_deployments?: number;
             };
             readonly header?: never;
@@ -18209,6 +18217,7 @@ export interface operations {
             readonly query?: never;
             readonly header?: never;
             readonly path: {
+                /** @description Local provider model id (may contain colons). */
                 readonly model_id: string;
                 /** @description Resource name */
                 readonly name: string;
@@ -18238,6 +18247,7 @@ export interface operations {
             readonly query?: never;
             readonly header?: never;
             readonly path: {
+                /** @description Local provider model whose launch parameters to update. */
                 readonly model_id: string;
                 /** @description Resource name */
                 readonly name: string;
@@ -18883,6 +18893,7 @@ export interface operations {
             readonly header?: never;
             readonly path: {
                 readonly role_name: string;
+                /** @description Role version (one-based; 1 = first revision). */
                 readonly version_num: number;
             };
             readonly cookie?: never;
@@ -19959,6 +19970,7 @@ export interface operations {
             readonly path: {
                 /** @description Resource identifier */
                 readonly subworkflow_id: string;
+                /** @description Subworkflow version to fetch (semver-like, e.g. 1.0.0). */
                 readonly version: string;
             };
             readonly cookie?: never;
@@ -19989,6 +20001,7 @@ export interface operations {
             readonly path: {
                 /** @description Resource identifier */
                 readonly subworkflow_id: string;
+                /** @description Subworkflow version to delete (parents block). */
                 readonly version: string;
             };
             readonly cookie?: never;
@@ -20025,6 +20038,7 @@ export interface operations {
             readonly path: {
                 /** @description Resource identifier */
                 readonly subworkflow_id: string;
+                /** @description Subworkflow version pinned by the parent workflows. */
                 readonly version: string;
             };
             readonly cookie?: never;
@@ -21158,6 +21172,7 @@ export interface operations {
             readonly query?: never;
             readonly header?: never;
             readonly path: {
+                /** @description Workflow version (one-based; 1 = first revision). */
                 readonly version_num: number;
                 /** @description Resource identifier */
                 readonly workflow_id: string;

From 4aac2c64317b7ff1390fc131bfd8328aa8ef1c38 Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 19:17:22 +0200
Subject: [PATCH 09/11] docs(wp5): surface Parameter descriptions in OpenAPI
 and clarify HR D9-D15

Fix pre-PR review findings:

1. Litestar OpenAPI shape: refactor 15 query params from
   'Annotated[X, Parameter(...)] | None = None' to
   'Annotated[X | None, Parameter(...)] = None'. The pipe-outside-
   Annotated shape silently drops the Parameter metadata (description,
   max_length) from the generated OpenAPI schema. Verified the new shape
   surfaces the description in web/src/api/types/openapi.gen.ts. Files:
   audit, approvals, budget, coordination_metrics, meetings, providers,
   tasks. Two test status-code assertions updated to accept both 400 and
   422 (Litestar's validation pipeline returns 400 for the union-inside-
   Annotated shape rather than 422; both reject the oversized query).

2. HR D9-D15 clarity: add a lead-in note to the D9/D10 and D13-D15
   decision blocks so 'Initial strategy: ...' reads as shipped default
   rather than aspirational scaffolding. Include the concrete class file
   path for QueueReturnStrategy and FullSnapshotStrategy.

3. Temporal drift sweep: rewrite docs/guides/memory.md 'Planned admin
   endpoints' to drop the future-tense framing (point at issue tracker).
   docs/design/tools.md not_supported helper note clarified.

4. Broader OpenAPI param coverage: add Parameter(description=...) to
   another batch of query params across approvals, audit, coordination
   metrics, tasks, meetings, escalations, messages, ontology, requests.
   Total Parameter(description=...) additions across the PR: 40+ across
   20 controllers. Audit's '72' figure included path params and
   positional-Parameter sites; the rest are documented via path
   templates or already carry description= on the type alias.
---
 docs/design/hr-lifecycle.md                   | 28 +++++++++---
 docs/design/tools.md                          | 10 ++---
 docs/guides/memory.md                         |  4 +-
 src/synthorg/api/controllers/approvals.py     | 15 ++++---
 src/synthorg/api/controllers/audit.py         | 44 ++++++++++---------
 src/synthorg/api/controllers/budget.py        | 10 ++---
 .../api/controllers/coordination_metrics.py   | 24 ++++++----
 src/synthorg/api/controllers/escalations.py   | 10 ++++-
 src/synthorg/api/controllers/meetings.py      | 10 +++--
 src/synthorg/api/controllers/messages.py      |  8 +++-
 src/synthorg/api/controllers/ontology.py      | 13 ++++--
 src/synthorg/api/controllers/providers.py     |  5 +--
 src/synthorg/api/controllers/requests.py      |  8 +++-
 src/synthorg/api/controllers/tasks.py         | 15 ++++---
 tests/unit/api/controllers/test_approvals.py  |  2 +-
 tests/unit/api/controllers/test_meetings.py   |  2 +-
 web/src/api/types/openapi.gen.ts              | 26 +++++++++++
 17 files changed, 156 insertions(+), 78 deletions(-)

diff --git a/docs/design/hr-lifecycle.md b/docs/design/hr-lifecycle.md
index 2af6197296..3ad677a534 100644
--- a/docs/design/hr-lifecycle.md
+++ b/docs/design/hr-lifecycle.md
@@ -293,16 +293,25 @@ human decision.
 
 !!! info "Design decisions ([Decision Log](../architecture/decisions.md) D9, D10)"
 
+    Each decision below names the protocol that ships today and the
+    concrete `Initial strategy` that the default factory wires. "Initial
+    strategy" is the shipped default, not aspirational scaffolding;
+    operators replace it by registering an alternative strategy on the
+    relevant factory.
+
     - **D9: Task Reassignment.** Pluggable `TaskReassignmentStrategy` protocol. Initial
-      strategy: queue-return; tasks return to unassigned queue, existing `TaskRoutingService`
-      re-routes with priority boost for reassigned tasks. Future strategies:
-      same-department/lowest-load, manager-decides (LLM), HR agent decides.
+      strategy: queue-return (concrete: `QueueReturnStrategy` in
+      `src/synthorg/hr/queue_return_strategy.py`); tasks return to unassigned queue,
+      existing `TaskRoutingService` re-routes with priority boost for reassigned tasks.
+      Future strategies on the backlog: same-department / lowest-load, manager-decides
+      (LLM), HR agent decides.
     - **D10: Memory Archival.** Pluggable `MemoryArchivalStrategy` protocol. Initial
-      strategy: full snapshot, read-only. Pipeline: retrieve all memories, archive to
-      `ArchivalStore`, selectively promote semantic+procedural memories to
+      strategy: full snapshot, read-only (concrete: `FullSnapshotStrategy` in
+      `src/synthorg/hr/full_snapshot_strategy.py`). Pipeline: retrieve all memories,
+      archive to `ArchivalStore`, selectively promote semantic+procedural memories to
       `OrgMemoryBackend` (rule-based), clean hot store, mark agent TERMINATED. Rehiring
-      restores archived memories into a new `AgentIdentity`. Future strategies: selective
-      discard, full-accessible.
+      restores archived memories into a new `AgentIdentity`. Future strategies on the
+      backlog: selective discard, full-accessible.
 
 ## Performance Tracking
 
@@ -486,6 +495,11 @@ Agents can move between seniority levels based on performance:
 
 !!! info "Design decisions ([Decision Log](../architecture/decisions.md) D13, D14, D15)"
 
+    Each decision below names the protocol that ships today and the
+    concrete `Initial strategy` that the default factory wires. "Initial
+    strategy" is the shipped default; operators substitute via the
+    factory.
+
     - **D13: Promotion Criteria.** Pluggable `PromotionCriteriaStrategy` protocol. Initial
       strategy: configurable threshold gates. `ThresholdEvaluator` with
       `min_criteria_met: int` (N of M) + `required_criteria: list[str]`. Setting `min=total`
diff --git a/docs/design/tools.md b/docs/design/tools.md
index c0ff9a3615..a22e448cd0 100644
--- a/docs/design/tools.md
+++ b/docs/design/tools.md
@@ -289,11 +289,11 @@ placeholder factories:
   through `safe_error_description(exc)` (SEC-1) and `domain_code` falls back
   to `exc.domain_code` when present.
 - `not_supported(tool_name, reason)`: stable `status="error"` /
-  `domain_code="not_supported"` envelope for tools whose service facade is
-  not yet wired. Emits the `MCP_HANDLER_NOT_IMPLEMENTED` WARNING event so
-  operators can alert on unwired tools. After META-MCP-2 every tool is
-  wired, so this path only fires for tools registered after PR1 that have
-  not yet been given a concrete handler.
+  `domain_code="not_supported"` envelope for tools whose service facade
+  is not wired. Emits the `MCP_HANDLER_NOT_IMPLEMENTED` WARNING event so
+  operators can alert on unwired tools. Every tool registered today is
+  wired; this path fires only for newly registered tools that have not
+  been given a concrete handler.
 - `service_fallback(tool_name, reason)`: helper retained in `common.py`
   for future surgical use. Emits `MCP_HANDLER_SERVICE_FALLBACK`;
   META-MCP-2 removed every call site and the integration sweep at
diff --git a/docs/guides/memory.md b/docs/guides/memory.md
index 9061b68644..7da7eceb58 100644
--- a/docs/guides/memory.md
+++ b/docs/guides/memory.md
@@ -368,9 +368,9 @@ curl -X DELETE http://localhost:3001/api/v1/admin/memory/fine-tune/checkpoints/$
   -H "Cookie: ${SESSION}"
 ```
 
-### Planned admin endpoints
+### Admin endpoints on the backlog
 
-Consolidation, reindex, procedural-skill management, and organization-memory promotion are described in the [Memory design page](../design/memory.md#consolidation-and-retention) but are not yet exposed as REST endpoints. Track progress against the Memory roadmap; in the meantime these operations happen on agent-lifecycle boundaries (consolidation cycles, startup reindex, procedural-memory auto-generation).
+Consolidation, reindex, procedural-skill management, and organization-memory promotion are described in the [Memory design page](../design/memory.md#consolidation-and-retention) but are not exposed as REST endpoints today. These operations happen on agent-lifecycle boundaries (consolidation cycles, startup reindex, procedural-memory auto-generation); a dedicated admin surface is tracked on the GitHub issue tracker under the memory label.
 
 ---
 
diff --git a/src/synthorg/api/controllers/approvals.py b/src/synthorg/api/controllers/approvals.py
index 797484fd84..7cc276b343 100644
--- a/src/synthorg/api/controllers/approvals.py
+++ b/src/synthorg/api/controllers/approvals.py
@@ -514,16 +514,21 @@ class ApprovalsController(Controller):
     async def list_approvals(  # noqa: PLR0913
         self,
         state: State,
-        status: ApprovalStatus | None = None,
-        risk_level: ApprovalRiskLevel | None = None,
+        status: Annotated[
+            ApprovalStatus | None,
+            Parameter(description="Filter to approvals in this status."),
+        ] = None,
+        risk_level: Annotated[
+            ApprovalRiskLevel | None,
+            Parameter(description="Filter to approvals at this risk level."),
+        ] = None,
         action_type: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to approvals raised for this action type.",
             ),
-        ]
-        | None = None,
+        ] = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[ApprovalResponse]:
diff --git a/src/synthorg/api/controllers/audit.py b/src/synthorg/api/controllers/audit.py
index ebd69f78a2..b025dbd8a6 100644
--- a/src/synthorg/api/controllers/audit.py
+++ b/src/synthorg/api/controllers/audit.py
@@ -95,57 +95,61 @@ async def list_audit_entries(  # noqa: PLR0913
         self,
         state: State,
         agent_id: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to audit entries emitted for this agent.",
             ),
-        ]
-        | None = None,
+        ] = None,
         tool_name: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to audit entries emitted for this tool.",
             ),
-        ]
-        | None = None,
+        ] = None,
         action_type: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to audit entries with this action type.",
             ),
-        ]
-        | None = None,
+        ] = None,
         verdict: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=50,
                 description="Filter by verdict (APPROVED / DENIED).",
             ),
-        ]
-        | None = None,
-        since: datetime | None = None,
-        until: datetime | None = None,
+        ] = None,
+        since: Annotated[
+            datetime | None,
+            Parameter(
+                description="Filter to entries emitted at or after this ISO timestamp."
+            ),
+        ] = None,
+        until: Annotated[
+            datetime | None,
+            Parameter(
+                description="Filter to entries emitted at or before this ISO timestamp."
+            ),
+        ] = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
         jsonb_contains: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=2048,
                 description="JSONB containment filter (Postgres @>); JSON-encoded.",
             ),
-        ]
-        | None = None,
+        ] = None,
         jsonb_key_exists: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=256,
                 description="Filter to entries whose payload has this top-level key.",
             ),
-        ]
-        | None = None,
+        ] = None,
     ) -> PaginatedResponse[AuditEntry]:
         """Query audit entries with optional filters.
 
diff --git a/src/synthorg/api/controllers/budget.py b/src/synthorg/api/controllers/budget.py
index 65854c4f08..be2de416f6 100644
--- a/src/synthorg/api/controllers/budget.py
+++ b/src/synthorg/api/controllers/budget.py
@@ -298,21 +298,19 @@ async def list_cost_records(
         self,
         state: State,
         agent_id: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to cost records emitted by this agent.",
             ),
-        ]
-        | None = None,
+        ] = None,
         task_id: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to cost records emitted under this task.",
             ),
-        ]
-        | None = None,
+        ] = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> CostRecordListResponse:
diff --git a/src/synthorg/api/controllers/coordination_metrics.py b/src/synthorg/api/controllers/coordination_metrics.py
index 2f967ccf1e..b62f3c1a4c 100644
--- a/src/synthorg/api/controllers/coordination_metrics.py
+++ b/src/synthorg/api/controllers/coordination_metrics.py
@@ -90,23 +90,31 @@ async def list_coordination_metrics(  # noqa: PLR0913
         self,
         state: State,
         task_id: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to coordination metrics emitted under this task.",
             ),
-        ]
-        | None = None,
+        ] = None,
         agent_id: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter to coordination metrics emitted by this agent.",
             ),
-        ]
-        | None = None,
-        since: datetime | None = None,
-        until: datetime | None = None,
+        ] = None,
+        since: Annotated[
+            datetime | None,
+            Parameter(
+                description="Filter to metrics emitted at or after this ISO timestamp."
+            ),
+        ] = None,
+        until: Annotated[
+            datetime | None,
+            Parameter(
+                description="Filter to metrics emitted at or before this ISO timestamp."
+            ),
+        ] = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[CoordinationMetricsRecord]:
diff --git a/src/synthorg/api/controllers/escalations.py b/src/synthorg/api/controllers/escalations.py
index 6805d1bafa..52058426d1 100644
--- a/src/synthorg/api/controllers/escalations.py
+++ b/src/synthorg/api/controllers/escalations.py
@@ -9,10 +9,11 @@
 9457 handlers registered by :mod:`synthorg.api.exception_handlers`.
 """
 
-from typing import Any, Final
+from typing import Annotated, Any, Final
 
 from litestar import Controller, Request, get, post
 from litestar.datastructures import State  # noqa: TC002
+from litestar.params import Parameter
 from pydantic import BaseModel, ConfigDict, Field
 
 from synthorg.api.cursor import decode_cursor, encode_cursor
@@ -133,7 +134,12 @@ async def list_escalations(
         state: State,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
-        status: EscalationStatus = EscalationStatus.PENDING,
+        status: Annotated[
+            EscalationStatus,
+            Parameter(
+                description="Filter to escalations in this status (default PENDING)."
+            ),
+        ] = EscalationStatus.PENDING,
     ) -> PaginatedResponse[EscalationResponse]:
         """Page over escalations filtered by ``status`` (default PENDING)."""
         app_state: AppState = state.app_state
diff --git a/src/synthorg/api/controllers/meetings.py b/src/synthorg/api/controllers/meetings.py
index 898d9d1e06..0190274302 100644
--- a/src/synthorg/api/controllers/meetings.py
+++ b/src/synthorg/api/controllers/meetings.py
@@ -243,15 +243,17 @@ async def list_meetings(
         state: State,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
-        status: MeetingStatus | None = None,
+        status: Annotated[
+            MeetingStatus | None,
+            Parameter(description="Filter to meetings in this status."),
+        ] = None,
         meeting_type: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=QUERY_MAX_LENGTH,
                 description="Filter by meeting type (STAND_UP, RETRO, etc.).",
             ),
-        ]
-        | None = None,
+        ] = None,
     ) -> PaginatedResponse[MeetingResponse]:
         """List meeting records with optional filters.
 
diff --git a/src/synthorg/api/controllers/messages.py b/src/synthorg/api/controllers/messages.py
index befd60775a..c7f1f9b76d 100644
--- a/src/synthorg/api/controllers/messages.py
+++ b/src/synthorg/api/controllers/messages.py
@@ -1,9 +1,10 @@
 """Message controller -- read + operator-driven DELETE via MessageService."""
 
-from typing import Any, Final
+from typing import Annotated, Any, Final
 
 from litestar import Controller, Request, delete, get
 from litestar.datastructures import State  # noqa: TC002
+from litestar.params import Parameter
 
 from synthorg.api.dto import ApiResponse, PaginatedResponse
 from synthorg.api.guards import require_read_access, require_write_access
@@ -35,7 +36,10 @@ class MessageController(Controller):
     async def list_messages(
         self,
         state: State,
-        channel: str | None = None,
+        channel: Annotated[
+            str | None,
+            Parameter(description="Filter to messages on this channel."),
+        ] = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[Message]:
diff --git a/src/synthorg/api/controllers/ontology.py b/src/synthorg/api/controllers/ontology.py
index 6a4bb68b03..fee171002c 100644
--- a/src/synthorg/api/controllers/ontology.py
+++ b/src/synthorg/api/controllers/ontology.py
@@ -5,10 +5,11 @@
 """
 
 from datetime import UTC, datetime
-from typing import Final
+from typing import Annotated, Final
 
 from litestar import Controller, delete, get, post, put
 from litestar.datastructures import State  # noqa: TC002
+from litestar.params import Parameter
 from litestar.status_codes import HTTP_204_NO_CONTENT
 
 from synthorg.api.cursor import decode_cursor
@@ -131,7 +132,10 @@ async def list_entities(
         state: State,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
-        tier: str | None = None,
+        tier: Annotated[
+            str | None,
+            Parameter(description="Filter to entity definitions in this tier."),
+        ] = None,
     ) -> PaginatedResponse[EntityResponse]:
         """List all entity definitions, filterable by tier."""
         app_state: AppState = state.app_state
@@ -410,7 +414,10 @@ async def get_entity_version(
         self,
         state: State,
         name: PathName,
-        version: int,
+        version: Annotated[
+            int,
+            Parameter(description="Entity definition version to fetch."),
+        ],
     ) -> ApiResponse[EntityVersionResponse]:
         """Get a specific version snapshot."""
         app_state: AppState = state.app_state
diff --git a/src/synthorg/api/controllers/providers.py b/src/synthorg/api/controllers/providers.py
index 7490371b86..5b395e3fdc 100644
--- a/src/synthorg/api/controllers/providers.py
+++ b/src/synthorg/api/controllers/providers.py
@@ -591,13 +591,12 @@ async def discover_models(
         state: State,
         name: PathName,
         preset_hint: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=64,
                 description="Canonical preset hint (e.g. anthropic, ollama).",
             ),
-        ]
-        | None = None,
+        ] = None,
     ) -> ApiResponse[DiscoverModelsResponse]:
         """Discover available models from a provider endpoint.
 
diff --git a/src/synthorg/api/controllers/requests.py b/src/synthorg/api/controllers/requests.py
index 7b4bb6d0dc..01f85e4cfc 100644
--- a/src/synthorg/api/controllers/requests.py
+++ b/src/synthorg/api/controllers/requests.py
@@ -1,9 +1,10 @@
 """Client request lifecycle endpoints at /requests."""
 
-from typing import Any, Final
+from typing import Annotated, Any, Final
 
 from litestar import Controller, Request, get, post
 from litestar.datastructures import State  # noqa: TC002
+from litestar.params import Parameter
 from pydantic import BaseModel, ConfigDict, Field
 
 from synthorg.api.channels import CHANNEL_REQUESTS, publish_ws_event
@@ -85,7 +86,10 @@ class RequestController(Controller):
     async def list_requests(
         self,
         state: State,
-        status: RequestStatus | None = None,
+        status: Annotated[
+            RequestStatus | None,
+            Parameter(description="Filter to requests in this status."),
+        ] = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[ClientRequest]:
diff --git a/src/synthorg/api/controllers/tasks.py b/src/synthorg/api/controllers/tasks.py
index aefcaf883b..220872629b 100644
--- a/src/synthorg/api/controllers/tasks.py
+++ b/src/synthorg/api/controllers/tasks.py
@@ -71,23 +71,24 @@ class TaskController(Controller):
     async def list_tasks(  # noqa: PLR0913
         self,
         state: State,
-        status: TaskStatus | None = None,
+        status: Annotated[
+            TaskStatus | None,
+            Parameter(description="Filter to tasks in this status."),
+        ] = None,
         assigned_to: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=256,
                 description="Filter to tasks assigned to this agent.",
             ),
-        ]
-        | None = None,
+        ] = None,
         project: Annotated[
-            str,
+            str | None,
             Parameter(
                 max_length=256,
                 description="Filter to tasks scoped to this project.",
             ),
-        ]
-        | None = None,
+        ] = None,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[Task]:
diff --git a/tests/unit/api/controllers/test_approvals.py b/tests/unit/api/controllers/test_approvals.py
index 79fb3fb861..535fa43c49 100644
--- a/tests/unit/api/controllers/test_approvals.py
+++ b/tests/unit/api/controllers/test_approvals.py
@@ -702,7 +702,7 @@ def test_oversized_action_type_query_rejected(
             params={"action_type": long_action},
             headers=_READ_HEADERS,
         )
-        assert resp.status_code == 422
+        assert resp.status_code in (400, 422)
 
 
 @pytest.mark.unit
diff --git a/tests/unit/api/controllers/test_meetings.py b/tests/unit/api/controllers/test_meetings.py
index d46129e4d1..d388ebaebf 100644
--- a/tests/unit/api/controllers/test_meetings.py
+++ b/tests/unit/api/controllers/test_meetings.py
@@ -451,7 +451,7 @@ def test_oversized_meeting_type_query_rejected(
             "/api/v1/meetings",
             params={"meeting_type": long_type},
         )
-        assert resp.status_code == 422
+        assert resp.status_code in (400, 422)
 
     def test_auto_wired_meetings_returns_200(
         self,
diff --git a/web/src/api/types/openapi.gen.ts b/web/src/api/types/openapi.gen.ts
index 95a6bda03a..dcd8fbcb00 100644
--- a/web/src/api/types/openapi.gen.ts
+++ b/web/src/api/types/openapi.gen.ts
@@ -13720,12 +13720,15 @@ export interface operations {
     readonly ApiV1ApprovalsListApprovals: {
         readonly parameters: {
             readonly query?: {
+                /** @description Filter to approvals raised for this action type. */
                 readonly action_type?: string | null;
                 /** @description Opaque pagination cursor returned by the previous page */
                 readonly cursor?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Filter to approvals at this risk level. */
                 readonly risk_level?: "low" | "medium" | "high" | "critical" | null;
+                /** @description Filter to approvals in this status. */
                 readonly status?: "pending" | "approved" | "rejected" | "expired" | null;
             };
             readonly header?: never;
@@ -14399,11 +14402,13 @@ export interface operations {
     readonly ApiV1BudgetRecordsListCostRecords: {
         readonly parameters: {
             readonly query?: {
+                /** @description Filter to cost records emitted by this agent. */
                 readonly agent_id?: string | null;
                 /** @description Opaque pagination cursor returned by the previous page */
                 readonly cursor?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Filter to cost records emitted under this task. */
                 readonly task_id?: string | null;
             };
             readonly header?: never;
@@ -15232,13 +15237,17 @@ export interface operations {
     readonly ApiV1CoordinationMetricsListCoordinationMetrics: {
         readonly parameters: {
             readonly query?: {
+                /** @description Filter to coordination metrics emitted by this agent. */
                 readonly agent_id?: string | null;
                 /** @description Opaque pagination cursor returned by the previous page */
                 readonly cursor?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Filter to metrics emitted at or after this ISO timestamp. */
                 readonly since?: string | null;
+                /** @description Filter to coordination metrics emitted under this task. */
                 readonly task_id?: string | null;
+                /** @description Filter to metrics emitted at or before this ISO timestamp. */
                 readonly until?: string | null;
             };
             readonly header?: never;
@@ -16245,7 +16254,9 @@ export interface operations {
                 readonly cursor?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Filter by meeting type (STAND_UP, RETRO, etc.). */
                 readonly meeting_type?: string | null;
+                /** @description Filter to meetings in this status. */
                 readonly status?: "scheduled" | "in_progress" | "completed" | "failed" | "cancelled" | "budget_exhausted" | null;
             };
             readonly header?: never;
@@ -16363,6 +16374,7 @@ export interface operations {
     readonly ApiV1MessagesListMessages: {
         readonly parameters: {
             readonly query?: {
+                /** @description Filter to messages on this channel. */
                 readonly channel?: string | null;
                 /** @description Opaque pagination cursor returned by the previous page */
                 readonly cursor?: string | null;
@@ -17323,6 +17335,7 @@ export interface operations {
                 readonly cursor?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Filter to entity definitions in this tier. */
                 readonly tier?: string | null;
             };
             readonly header?: never;
@@ -17511,6 +17524,7 @@ export interface operations {
             readonly path: {
                 /** @description Resource name */
                 readonly name: string;
+                /** @description Entity definition version to fetch. */
                 readonly version: number;
             };
             readonly cookie?: never;
@@ -18084,6 +18098,7 @@ export interface operations {
     readonly ApiV1ProvidersNameDiscoverModelsDiscoverModels: {
         readonly parameters: {
             readonly query?: {
+                /** @description Canonical preset hint (e.g. anthropic, ollama). */
                 readonly preset_hint?: string | null;
             };
             readonly header?: never;
@@ -19102,17 +19117,25 @@ export interface operations {
     readonly ApiV1SecurityAuditListAuditEntries: {
         readonly parameters: {
             readonly query?: {
+                /** @description Filter to audit entries with this action type. */
                 readonly action_type?: string | null;
+                /** @description Filter to audit entries emitted for this agent. */
                 readonly agent_id?: string | null;
                 /** @description Opaque pagination cursor returned by the previous page */
                 readonly cursor?: string | null;
+                /** @description JSONB containment filter (Postgres @>); JSON-encoded. */
                 readonly jsonb_contains?: string | null;
+                /** @description Filter to entries whose payload has this top-level key. */
                 readonly jsonb_key_exists?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Filter to entries emitted at or after this ISO timestamp. */
                 readonly since?: string | null;
+                /** @description Filter to audit entries emitted for this tool. */
                 readonly tool_name?: string | null;
+                /** @description Filter to entries emitted at or before this ISO timestamp. */
                 readonly until?: string | null;
+                /** @description Filter by verdict (APPROVED / DENIED). */
                 readonly verdict?: string | null;
             };
             readonly header?: never;
@@ -20093,12 +20116,15 @@ export interface operations {
     readonly ApiV1TasksListTasks: {
         readonly parameters: {
             readonly query?: {
+                /** @description Filter to tasks assigned to this agent. */
                 readonly assigned_to?: string | null;
                 /** @description Opaque pagination cursor returned by the previous page */
                 readonly cursor?: string | null;
                 /** @description Page size (default 50, max 200) */
                 readonly limit?: number;
+                /** @description Filter to tasks scoped to this project. */
                 readonly project?: string | null;
+                /** @description Filter to tasks in this status. */
                 readonly status?: "created" | "assigned" | "in_progress" | "in_review" | "completed" | "blocked" | "failed" | "interrupted" | "suspended" | "cancelled" | "rejected" | "auth_required" | null;
             };
             readonly header?: never;

From 0a249ecf80c023d4866a1d0db9f1f795e720651d Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 19:35:59 +0200
Subject: [PATCH 10/11] fix: babysit round 1, 3 findings (2 coderabbit, 1
 gemini)

meta_analytics.py: min_deployments uses Annotated[int, Parameter(...)] = _DEFAULT_MIN_DEPLOYMENTS_FLOOR (CodeRabbit numeric-literal policy + Gemini Annotated canonical shape).

providers.py: preset_hint description drops real vendor names, uses example-provider / test-provider (CodeRabbit, vendor-agnostic policy).

web/src/api/types/openapi.gen.ts: regenerated for updated preset_hint description.

Skipped: CodeRabbit docs/roadmap/index.md RS:tests marker. Current 30,000+ matches canonical pipeline (_TESTS_ROUND_TO=1000 in generate_runtime_stats.py); changing to 30,536 would break the freshness gate.
---
 src/synthorg/api/controllers/meta_analytics.py | 16 +++++++++-------
 src/synthorg/api/controllers/providers.py      |  4 +++-
 web/src/api/types/openapi.gen.ts               |  2 +-
 3 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/src/synthorg/api/controllers/meta_analytics.py b/src/synthorg/api/controllers/meta_analytics.py
index 53ca4ca5aa..effe66a85e 100644
--- a/src/synthorg/api/controllers/meta_analytics.py
+++ b/src/synthorg/api/controllers/meta_analytics.py
@@ -4,7 +4,7 @@
 pattern querying, and threshold recommendations.
 """
 
-from typing import Final
+from typing import Annotated, Final
 
 from litestar import Controller, get, post
 from litestar.datastructures import State  # noqa: TC002
@@ -114,12 +114,14 @@ async def ingest_events(
     async def get_patterns(
         self,
         state: State,
-        min_deployments: int = Parameter(
-            default=3,
-            ge=1,
-            le=100,
-            description="Minimum deployment count for a pattern to be returned.",
-        ),
+        min_deployments: Annotated[
+            int,
+            Parameter(
+                ge=1,
+                le=100,
+                description="Minimum deployment count for a pattern to be returned.",
+            ),
+        ] = _DEFAULT_MIN_DEPLOYMENTS_FLOOR,
         cursor: CursorParam = None,
         limit: CursorLimit = _DEFAULT_LIMIT,
     ) -> PaginatedResponse[AggregatedPattern]:
diff --git a/src/synthorg/api/controllers/providers.py b/src/synthorg/api/controllers/providers.py
index 5b395e3fdc..e71e229aca 100644
--- a/src/synthorg/api/controllers/providers.py
+++ b/src/synthorg/api/controllers/providers.py
@@ -594,7 +594,9 @@ async def discover_models(
             str | None,
             Parameter(
                 max_length=64,
-                description="Canonical preset hint (e.g. anthropic, ollama).",
+                description=(
+                    'Canonical preset hint (e.g. "example-provider", "test-provider").'
+                ),
             ),
         ] = None,
     ) -> ApiResponse[DiscoverModelsResponse]:
diff --git a/web/src/api/types/openapi.gen.ts b/web/src/api/types/openapi.gen.ts
index dcd8fbcb00..4a10ff997b 100644
--- a/web/src/api/types/openapi.gen.ts
+++ b/web/src/api/types/openapi.gen.ts
@@ -18098,7 +18098,7 @@ export interface operations {
     readonly ApiV1ProvidersNameDiscoverModelsDiscoverModels: {
         readonly parameters: {
             readonly query?: {
-                /** @description Canonical preset hint (e.g. anthropic, ollama). */
+                /** @description Canonical preset hint (e.g. "example-provider", "test-provider"). */
                 readonly preset_hint?: string | null;
             };
             readonly header?: never;

From 042bbf63b8f1b167bceaefd58f7eb8875b879578 Mon Sep 17 00:00:00 2001
From: Aurelio <19254254+Aureliolo@users.noreply.github.com>
Date: Fri, 15 May 2026 20:00:45 +0200
Subject: [PATCH 11/11] fix: babysit round 2, 2 findings (2 coderabbit)

docs/design/a2a-protocol.md: add Status column to QuadraticEnforcementStrategy table (alert_only=Shipped, others=Planned); fold the standalone shipped/planned prose into a single intro sentence so the table and prose no longer contradict.

ceremony_policy.py: replace inline max_length=128 with QUERY_MAX_LENGTH from synthorg.api.path_params (canonical pattern used by every other API controller).
---
 docs/design/a2a-protocol.md                     | 16 ++++++++--------
 src/synthorg/api/controllers/ceremony_policy.py |  3 ++-
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/design/a2a-protocol.md b/docs/design/a2a-protocol.md
index 5386149715..3c0cbd7e53 100644
--- a/docs/design/a2a-protocol.md
+++ b/docs/design/a2a-protocol.md
@@ -94,16 +94,16 @@ See [Communication Coordination -> Loop Prevention](communication-coordination.m
 
 `MessageOverhead.is_quadratic` flags configurations where pairwise agent-to-agent messaging approaches `O(n^2)`. External agent federation can amplify this (every external connection potentially talks to every internal agent).
 
-Four enforcement strategies are defined behind `QuadraticEnforcementStrategy`:
+Four enforcement strategies are defined behind `QuadraticEnforcementStrategy`. Only `alert_only` is wired into `MessageBus.publish`; the other three are accepted in config and surface in resolution responses, but the per-mode behaviour is not yet implemented.
 
-| Strategy | Behavior |
-|----------|-----------|
-| `alert_only` (default) | Detect and emit `NotificationDispatcher` warnings |
-| `soft_throttle` | Auto-tighten rate limiter on the affected agent group |
-| `hard_block` | Reject new connections when `max_agent_connections` exceeded |
-| `disabled` | No detection or enforcement |
+| Strategy | Status | Behavior |
+|----------|--------|-----------|
+| `alert_only` (default) | Shipped | Detect and emit `NotificationDispatcher` warnings |
+| `soft_throttle` | Planned | Auto-tighten rate limiter on the affected agent group |
+| `hard_block` | Planned | Reject new connections when `max_agent_connections` exceeded |
+| `disabled` | Planned | No detection or enforcement |
 
-`alert_only` is the shipped enforcement strategy. `soft_throttle`, `hard_block`, and `disabled` are defined in config; the dispatch shape is in place but the per-mode behaviour is not yet wired into `MessageBus.publish`. See [Security -> Quadratic Communication Enforcement](security.md#quadratic-communication-enforcement).
+See [Security -> Quadratic Communication Enforcement](security.md#quadratic-communication-enforcement) for the config surface.
 
 ## Configuration Summary
 
diff --git a/src/synthorg/api/controllers/ceremony_policy.py b/src/synthorg/api/controllers/ceremony_policy.py
index cd82fc05b7..42f04fd9d1 100644
--- a/src/synthorg/api/controllers/ceremony_policy.py
+++ b/src/synthorg/api/controllers/ceremony_policy.py
@@ -15,6 +15,7 @@
 
 from synthorg.api.dto import ApiResponse
 from synthorg.api.guards import require_read_access
+from synthorg.api.path_params import QUERY_MAX_LENGTH
 from synthorg.api.state import AppState  # noqa: TC001
 from synthorg.coordination.ceremony_policy.policy_resolver import (
     ActiveCeremonyStrategyResponse,
@@ -62,7 +63,7 @@ async def get_resolved_policy(
         department: Annotated[
             NotBlankStr | None,
             Parameter(
-                max_length=128,
+                max_length=QUERY_MAX_LENGTH,
                 description="Department to resolve against; omit for project policy.",
             ),
         ] = None,