autofab 0.2.0__tar.gz

autofab-0.2.0/.gitignore

@@ -0,0 +1,34 @@
+/bazel-*
+/agent_loop.log*
+/staging/
+/testing/
+__pycache__/
+*.py[cod]
+*$py.class
+.update_with_ai.textproto
+.update_with_ai.proto
+/.mcp.active*
+/.cleanroom/
+/.autofab/
+.pytest_cache/
+.ruff_cache/
+.hypothesis/
+.mcp.worker_sessions.json
+.DS_Store
+/.cleanroom_workspaces.json
+/.cleanroom_blame_buffer.json
+/.autofab_workspaces.json
+/.autofab_blame_buffer.json
+*.bak
+*.bak/
+/logs/
+*.cleanroom.log*
+*.autofab.log*
+/benchmark_*
+scratch/
+.coverage*
+autofab_role_workspaces/
+role_workspaces/
+dist/
+build/
+*.egg-info/

autofab-0.2.0/.python-version

@@ -0,0 +1 @@
+3.12.0

autofab-0.2.0/.vscode/settings.json

@@ -0,0 +1,33 @@
+{
+  "python.analysis.extraPaths": [
+    "${workspaceFolder}/update_with_ai",
+    "${workspaceFolder}/update_with_ai/lib",
+    "${workspaceFolder}/update_with_ai/specs/grounding_pyi"
+  ],
+  "editor.inlineSuggest.enabled": false,
+  "editor.quickSuggestions": {
+    "other": "off",
+    "comments": "off",
+    "strings": "off"
+  },
+  "editor.suggestOnTriggerCharacters": false,
+  "editor.acceptSuggestionOnEnter": "off",
+  "editor.tabCompletion": "off",
+  "editor.wordBasedSuggestions": "off",
+  "editor.snippetSuggestions": "none",
+  "editor.parameterHints.enabled": false,
+  "[markdown]": {
+    "editor.quickSuggestions": {
+      "other": "off",
+      "comments": "off",
+      "strings": "off"
+    },
+    "editor.suggestOnTriggerCharacters": false,
+    "editor.wordBasedSuggestions": "off",
+    "editor.inlineSuggest.enabled": false
+  },
+  "editor.wordWrap": "on",
+  "files.associations": {
+    "*.gt": "prolog"
+  }
+}

autofab-0.2.0/AGENTS.md

@@ -0,0 +1,96 @@
+# Autofab Behavioral Constraints & Guide References
+
+## Workspace Boundaries & File Locations
+
+- **NEVER modify or rely on the `staging/` directory**: The `staging/` directory is an ephemeral test consumer directory that can be deleted or wiped at any time. Running `bin/sync_staging.sh` counts as modifying the `staging/` directory.
+- **Canonical Codebase**: All production specifications, library implementations, and builds live exclusively in:
+  - `autofab/`
+  - `autofab_python/`
+  - `pretense/`
+
+## Strict Prohibition on Hardcoding Specific Paths, Directory Names, and Role Names
+
+- **NO Hardcoded Directory Names or Paths**: Specific directory names, package scopes, or ephemeral workspace paths (such as `staging`, `autofab`, `autofab_python`, `pretense`, `autofab_role_workspaces`, `role_workspaces`, or temporary directories) must NEVER be hardcoded into tools, linters, runners, verifiers, test assertions, or library implementations.
+- **NO Hardcoded Role Names**: Role names (such as `high`, `planning`, `low`, `spec_qa`, `lib`, `test`, `qa`, `coverage`, `scenario`, `pretense`, `pretense_qa`, `pretense_coverage`, etc.) must NEVER be hardcoded into core tools, workspace provisioners, runners, orchestrators, or library logic. Roles must be discovered dynamically from the active methodology configuration (e.g., `autofab_roles.toml`, `cleanroom_roles.toml`, `autofab.toml`, `cleanroom.toml`) and target definitions.
+- **Dynamic Scoping and Target Derivation**: Package scopes, workspace roots, role definitions, and directory paths must always be derived dynamically from the target address (e.g., `//<scope>/parts/...#<role>`), active configuration files (e.g., `autofab.toml`, `autofab_roles.toml`), environment variables (e.g., `BUILD_WORKSPACE_DIRECTORY`), or passed explicitly as arguments without hardcoded directory or role defaults.
+- **Agnostic Linters, Runners, and Verifiers**: Linters, runners, and verification tools must verify imports, package structures, and role execution relative to the active target's resolved package root, methodology manifest, and declared dependencies, rather than asserting against hardcoded directory strings or static role enumerations.
+
+## Mandatory Specification-First (HLS-First) Rule
+
+- **ALWAYS start with HLS changes when changing code in a parts directory**: Never make stealth changes to library code (`lib/*.py`) or unit tests (`tests/*_test.py`) without first authoring and aligning the corresponding High-Level Specification (`high/*.md`).
+- **Every Bug or Defect is a Specification Defect**: Do NOT treat bug fixing, troubleshooting, or runtime failures as an excuse to jump directly to patching `lib/*.py` or `tests/*_test.py`. If code behaved incorrectly, determine what high-level behavioral contract was omitted or violated, author the change in `high/*.md` first, and cascade down.
+- **Automatic Downstream Alignment**: Whenever changes are made to HLS files (`high/*.md`), immediately and automatically cascade alignment across the entire downstream pipeline: `HLS` (`high/*.md`) $\to$ `Planning` (`planning/*.md`) $\to$ `Scenarios` (`scenarios/*.md`) $\to$ `Low` (`low/*.pyi`) $\to$ `Spec QA` $\to$ `Library` (`lib/*.py`) $\to$ `Unit Tests` (`tests/*_test.py`). Do not stop after editing HLS files or wait for separate prompts to complete downstream alignment.
+- **Pre-Edit Gate (STOP before touching `lib/` or `tests/`)**: Before editing any file under `parts/*/lib/` or `parts/*/tests/`, verify:
+  1. Has the corresponding `high/*.md` been authored first, with planning, scenarios, and low specifications aligned?
+  2. Or are you specifically dealing with preexisting uncontracted code?
+  If neither, **STOP**. Author the HLS change first.
+
+## Handling Uncontracted Code
+
+- **Permitted to Delete**: When specifically discovering preexisting uncontracted code in `lib/` or `tests/`, you are fully permitted to delete it if it is unneeded, redundant, or uncontracted fallback logic.
+- **Retrofitting Contracts is Discouraged but Permitted**: Retrofitting contracts backwards from code to spec is discouraged, but is sometimes the only way to deal with essential uncontracted code that must be preserved. When retrofitting, author the missing contracts up the ladder (`low/`, `scenarios/`, `planning/`, `high/`) so the functionality is no longer uncontracted. Once retrofitted, all subsequent changes must follow the strict HLS-first rule.
+
+## Semantic Analysis Over Syntactic Checking (Anti-Mechanistic Rule)
+
+- **Mechanistic Checking is Only 1%**: Passing linters, type checkers, or verifiers with zero errors is merely a baseline mechanical sanity check. It does NOT mean the specification or implementation is correct or meaningful. Stop treating tasks as syntactic constraint-satisfaction games.
+- **Mandatory Deep Semantic Analysis**: Every specification, implementation, contract, and test must be derived by analyzing the actual behavioral semantics and contracts in upstream artifacts rather than shallow mechanistic checks.
+
+## Standard Terminology: Step vs Round (Strict Prohibition on "Turn")
+
+- **STRICT PROHIBITION ON "TURN"**: The term "turn" is ambiguous (historically conflated between a single tool-call step and a full role dispatch wave) and is strictly deprecated and prohibited in documentation, guides, design docs, specifications, prompts, and code. Use **step** or **round** explicitly.
+- **Step**: A single prompt $\leftrightarrow$ tool-call interaction cycle between an agent/model and the runtime/harness (e.g., model prompt $\to$ internal reasoning $\to$ tool call(s) $\to$ tool response).
+- **Round**: A full Autofab role dispatch wave or execution pass across assigned targets (from role dispatch into a role workspace until completion, submission, blame, or exhaustion). A round encompasses all model steps executed within that role dispatch pass. Re-entry of a role (e.g. after downstream rejection or loop propagation) initiates a subsequent round.
+
+## Mandatory Tool Execution and Round Conclusion (Prohibition on Conversational Halting)
+
+- **Ground Truth First (Anti-Speculation Rule)**: Always run `bin/check_files <target>` immediately as the first action after `bin/get_work` to obtain deterministic error diagnostics. Never guess, infer, or speculate about defects from reading prose before checking the actual oracle output.
+- **Continuous Tool Execution While Work Remains**: While ready targets remain unresolved, role workers operate exclusively via tool execution. Producing conversational commentary, explanations, or announcing actions in prose (such as ending a message with a colon or promising a tool call) without invoking tools in the same step is strictly prohibited and causes runtime harnesses to terminate rounds prematurely.
+- **Targeted Reads Over Repeated Dumps**: Never repeatedly read entire files when output is pruned. Use grep to locate symbols, or read narrow line ranges with offset and limit.
+- **Mandatory Round Conclusion When Work is Done**: When a role worker has no outstanding work to do and `bin/get_work` does not give it more work to do (all assigned ready targets have been resolved via `bin/check_files <target>` followed by `bin/submit`, `bin/blame`, or `bin/fail`, or only blocked targets remain), the worker can and MUST conclude the round immediately. The worker must output its concise summary text WITHOUT invoking any further tools (`ls`, `bin/get_work`, dummy commands). Delivering text with zero tool calls is the expected mechanism that cleanly concludes the round in autonomous harnesses. Leaving assigned targets unresolved without tool execution triggers coordinator reminders and trips the impasse circuit breaker.
+
+## Guide Editing & Meta-Rules
+
+- **Editing Guides**: ALWAYS read and maintain in context `autofab/guides/meta_guide.md` before creating, updating, or editing any guide.
+
+## Required Guides for Alignments & Tasks
+
+Always read and maintain in context the relevant guide from `autofab_python/guides/` when modifying specs, implementations, tests, or doing alignments:
+
+- **High-Level Specs (HLS)**: `autofab_python/guides/high_level_spec.md`
+- **HLS to Planning Alignment**: `autofab_python/guides/high_to_planning.md`
+- **Planning to Low Alignment**: `autofab_python/guides/planning_to_low.md`
+- **Spec QA Arbiter**: `autofab_python/guides/spec_qa.md`
+- **Low-Level Specification to Library Code Alignment**: `autofab_python/guides/low_to_lib.md`
+- **Low-Level Specification to Unit Tests Alignment**: `autofab_python/guides/low_to_test.md`
+- **QA Verification**: `autofab_python/guides/qa.md`
+- **Coverage Arbiter**: `autofab_python/guides/coverage.md`
+
+## Test Execution (bin/test)
+
+- **Required Test Runner**: Use `bin/test` to run repo verification and tests cleanly.
+
+## Local Python Linter Invocations (test_lint.py)
+
+- **Required PYTHONPATH**: When running `test_lint.py` directly (such as during dry-run collection verification), ensure `PYTHONPATH` includes `autofab_python`, `pretense`, and all constituent library directories (`autofab/parts/*/lib`, `pretense/parts/*/lib`, or package roots) to prevent cross-package `ModuleNotFoundError` during test module dry runs.
+
+## DO NOT EDIT pyrightconfig.json to fix type problems!
+
+If a test doesn't matter, don't run the test! Do not edit pyrightconfig.json to make the test not matter anymore. If you have a type error that you can't fix, don't edit pyrightconfig.json to make the type error go away. Etc...
+
+## Direct Command Execution
+
+- **Immediate Execution of Explicit Shell Commands**: When the user provides an explicit shell command to run (e.g., `uv run ...`, `bin/...`, `pytest ...`), execute `run_command` immediately in the very first step. Do NOT inspect source code, read files, second-guess, or perform pre-flight research before running the command.
+
+## Git Operations
+
+- **NO Unprompted Commits or Pushes**: NEVER commit or push to git unless explicitly directed to do so by the user.
+
+## Autonomous Orchestration Antigravity Execution
+
+- **Immediate Coordinator Invocation on orchestrate & benchmarks (Antigravity Only)**: When running under the Google Antigravity agent, if any command resolving to the Antigravity harness (such as `uv run autofab orchestrate ...`, `uv run autofab clean ...`, `uv run autofab benchmark ...`, or `uv run bin/evaluate_model_efficiency.py ...`) is executed (or emits the `AUTONOMOUS ANTIGRAVITY COORDINATION DIRECTIVE`):
+  1. If `agentapi send-message` reactive wakeup message is received in the chat, use the target scope specified directly in the message.
+  2. If the command runs as a background task and no message arrived, immediately inspect the task log (`.system_generated/tasks/task-X.log`) or `logs/*_runner.log` to extract the scope name (`benchmarks_flight_*` or target scope). Do NOT wait for the background command to finish before launching the coordinator—the command is waiting for the coordinator to converge the DAG.
+  3. Immediately invoke:
+     `invoke_subagent(TypeName="autofab_coordinator", Role="Autofab Coordinator", Prompt="Clean all dirty nodes in <scope> using autofab_coordinator")`
+  In other environments (such as DeepSeek Harness / DSH Desktop), run `uv run autofab clean <scope> [target_role]` directly via the terminal tool (configured with a model using the `dsh` harness in `model_configs.toml`).
+  For autonomous DAG convergence under Antigravity, run `uv run autofab clean <target>` with a model using the `antigravity` harness.

autofab-0.2.0/PKG-INFO

@@ -0,0 +1,340 @@
+Metadata-Version: 2.5
+Name: autofab
+Version: 0.2.0
+Summary: Literate, specification-driven software engineering framework for autonomous AI pair-programming
+Author-email: Sean McDirmid <mcdirmid@outlook.com>
+License: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: coverage>=7.0.0
+Requires-Dist: hypothesis>=6.100.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyright>=1.1.350
+Requires-Dist: pytest-cov>=5.0.0
+Requires-Dist: pytest-timeout>=2.3.0
+Requires-Dist: pytest>=8.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tqdm>=4.66.0
+Requires-Dist: typing-extensions>=4.8.0
+Description-Content-Type: text/markdown
+
+# Autofab CLI Reference & Invocation Guide
+
+Autofab (formerly Cleanroom) is a literate, specification-driven software engineering framework for autonomous AI pair programming, double-blind verification, and deterministic DAG convergence.
+
+All workspace lifecycle, inspection, submission, and execution operations in the canonical repository are invoked via **`uv run autofab`** (or `./bin/autofab` as a convenience wrapper, with `cleanroom` preserved as a backwards-compatible alias).
+
+---
+
+## 1. Quick Start
+
+### Autonomous Loop Execution (`--loop`)
+To execute in-process autonomous DAG cleaning using an LLM without setting up external subagent processes, pass `--loop`:
+
+```bash
+# Clean an entire package scope across all roles in topological order
+uv run cleanroom orchestrate staging --loop
+
+# Clean a package scope up to a specific role boundary (e.g., up to planning or lib)
+uv run cleanroom orchestrate staging#planning --loop
+uv run cleanroom orchestrate staging#lib --loop
+
+# Clean a specific component target node or implementation file
+uv run cleanroom orchestrate //staging/parts/agent:agent_config#lib --loop
+uv run cleanroom staging/parts/agent/lib/agent_config.py --loop
+
+# Equivalent shorthand syntax for cleaning a target or scope
+uv run cleanroom clean staging
+uv run cleanroom clean staging#lib
+uv run cleanroom clean //staging/parts/agent:agent_config#lib
+
+# Specify a custom model configuration label or model name
+uv run cleanroom orchestrate staging --loop --model default
+```
+
+### Multi-Agent Subagent Orchestration
+To orchestrate multi-agent DAG convergence across isolated, double-blind role workspaces:
+
+```bash
+# Antigravity interactive pair-programming pre-flight (prints DAG state & directives)
+uv run cleanroom orchestrate staging
+
+# Orchestrate up to a specific role boundary
+uv run cleanroom orchestrate staging#qa
+
+# Headless multi-agent execution via DeepSeek Harness (DSH)
+uv run cleanroom orchestrate staging --harness dsh
+
+# Headless simulation run (useful for verification and test assertions)
+uv run cleanroom orchestrate staging --harness simulation
+```
+
+---
+
+## 2. Command Reference
+
+### `orchestrate`
+Orchestrates multi-agent convergence across topological waves until the DAG evaluates clean.
+
+```bash
+uv run cleanroom orchestrate <scope_or_target> [options]
+```
+
+Examples:
+```bash
+# Orchestrate full scope
+uv run cleanroom orchestrate staging
+
+# Orchestrate up to and including role boundary (e.g. qa)
+uv run cleanroom orchestrate staging#qa
+```
+
+**Options:**
+- `--loop`: Run autonomous in-process loop execution rather than an external subagent harness.
+- `--harness <name>`: Subagent execution platform (`antigravity`, `dsh`, `simulation`, `loop`). Default: `antigravity`.
+- `--model <name>`: Model profile or configuration name (e.g. `default`, `deepseek-v41-flash`, `gemini-3.8-flash`).
+- `--max-waves <n>`: Maximum execution waves before stopping (default: `50`).
+- `--batch-size <n>`: Maximum targets dispatched per role wave.
+- `--timeout <seconds>`: Subprocess execution timeout in seconds.
+- `--headless`: Run in headless mode without interactive prompting (used in automated CI environments; `--harness dsh` and `--loop` run headlessly by default).
+
+---
+
+### `work-queue` (alias: `queue`)
+Inspects the dependency DAG and prints ready vs. blocked tasks for a scope or role.
+
+```bash
+# Inspect all ready and blocked nodes across a scope
+uv run cleanroom work-queue staging
+
+# Inspect work queue for a specific role boundary
+uv run cleanroom work-queue staging#lib
+uv run cleanroom work-queue staging#qa
+
+# Output JSON structured task metadata (used by agent coordinators)
+uv run cleanroom work-queue staging --json
+```
+
+---
+
+### `mark-clean`
+Marks target nodes or entire directory scopes clean in metadata and DAG storage without invoking the generative LLM loop.
+
+```bash
+# Mark all nodes in a scope clean
+uv run cleanroom mark-clean staging
+
+# Mark a specific role within a scope clean
+uv run cleanroom mark-clean staging/parts/agent/lib
+
+# Mark a specific target or file clean
+uv run cleanroom mark-clean staging/parts/agent/lib/agent_config.py
+uv run cleanroom mark-clean //staging/parts/agent:agent_config#lib
+```
+
+---
+
+### `dirty`
+Marks target nodes or directory scopes dirty in DAG storage, recording an optional diagnostic reason.
+
+```bash
+# Mark a scope dirty with default reason
+uv run cleanroom dirty staging
+
+# Mark a specific target dirty with an actionable reason
+uv run cleanroom dirty staging/parts/agent/lib/agent_config.py "Type signature mismatch with low spec"
+uv run cleanroom dirty //staging/parts/agent:agent_config#lib -m "Unit test regression"
+```
+
+---
+
+### `submit`
+Verifies and submits changes for a file to the canonical repository with in-band metadata updates (`LAST_CLEANED`, `LAST_CHANGED`, and `CODE_HASH`).
+
+```bash
+# Submit an updated implementation with verification checks
+uv run cleanroom submit staging/parts/agent/lib/agent_config.py "Implement timeout property"
+
+# Bypass verification checks during rapid authoring
+uv run cleanroom submit --no-verify staging/parts/agent/high/agent_config.md "Author HLS"
+```
+
+---
+
+### `feedback` (alias: `blame`)
+Attributes an actionable defect critique or feedback to an upstream culprit contract, specification file, or DAG target node, triggering upstream invalidation and recording diagnostic feedback.
+
+Supports both positional critique syntax and `-m / --message` flags:
+
+```bash
+# Deliver blame feedback to an upstream contract or specification file (in-band metadata mutation)
+uv run cleanroom feedback staging/parts/agent/low/agent_config.pyi "Contract missing parameter 'timeout'"
+uv run cleanroom feedback staging/parts/agent/low/agent_config.pyi -m "Contract missing parameter 'timeout'"
+
+# Deliver feedback to a target node in the DAG
+uv run cleanroom feedback //staging/parts/agent:agent_config#low "Contract missing parameter 'timeout'"
+uv run cleanroom feedback //staging/parts/agent:agent_config#low -m "Contract missing parameter 'timeout'"
+
+# 'blame' is supported as a direct alias
+uv run cleanroom blame staging/parts/agent/low/agent_config.pyi "Contract missing parameter 'timeout'"
+```
+
+---
+
+### `fail`
+Records a verification failure for a target, forcing it into a dirty state with captured diagnostic failure logs.
+
+```bash
+uv run cleanroom fail staging/parts/agent/lib/agent_config.py "Abstract method resolution error in pytest"
+```
+
+---
+
+### `check_files` (alias: `check-files`)
+Runs role-specific deterministic verification checks (HLS prose linter, Planning epistemic linter, Low Pyright type checks, or unit test runners).
+
+```bash
+# Run verification checks on a specific target
+uv run cleanroom check_files staging/parts/agent/lib/agent_config.py
+
+# Run checks across pending work in the active scope
+uv run cleanroom check_files
+```
+
+---
+
+### `coverage`
+Evaluates statement test coverage between an implementation and its double-blind test suite.
+
+```bash
+# Assert 100% test coverage on a module
+uv run cleanroom coverage --impl staging/parts/agent/lib/agent_config.py --test staging/parts/agent/tests/agent_config_test.py -t 100.0
+
+# Output coverage metrics in JSON
+uv run cleanroom coverage staging/parts/agent:agent_config --json
+```
+
+---
+
+### `change` & `prompt`
+```bash
+# Record an explicit manual change description on a target
+uv run cleanroom change staging/parts/agent/lib/agent_config.py "Refactored timeout helper"
+
+# Print the task prompt and contract instructions for a target
+uv run cleanroom prompt //staging/parts/agent:agent_config#lib
+```
+
+---
+
+### `commission` & `decommission`
+Manages isolated, double-blind role workspaces (`role_workspaces/<scope>_<role>/`).
+
+`commission` provisions and initializes role workspaces—binding model configurations, configuring harness-specific agent instructions (`AGENTS.md` and overlay patches), copying system files, and deploying role guides and tool wrappers—**without executing the subagent or running any LLM loop**:
+
+```bash
+# Initialize all declared role workspaces for a scope bound to a specific model profile without executing
+uv run cleanroom commission --all staging --model deepseek-v41-flash
+
+# Initialize role workspaces tailored for DeepSeek Harness (DSH)
+uv run cleanroom commission --all staging --harness dsh --model deepseek-v41-flash
+
+# Initialize a single role workspace bound to a specific model and harness
+uv run cleanroom commission staging#lib --harness antigravity --model deepseek-v41-flash
+uv run cleanroom commission staging#qa --harness dsh --model deepseek-v41-flash
+
+# Reset an existing role workspace back to a clean state
+uv run cleanroom commission staging#lib --reset
+
+# Decommission and delete provisioned workspaces for a scope (or up to a role)
+uv run cleanroom decommission staging
+uv run cleanroom decommission staging#lib
+```
+
+---
+
+### `refresh-sys`
+Synchronizes system tools, linters, methodology configs (`cleanroom_roles.toml`), and guides from canonical roots to provisioned role workspaces.
+
+```bash
+uv run cleanroom refresh-sys
+```
+
+---
+
+### `install-plugin`
+Installs or refreshes the Cleanroom Antigravity extension, subagent role definitions, and coordinator tools into `~/.gemini/antigravity`.
+
+```bash
+uv run cleanroom install-plugin
+```
+
+---
+
+## 3. Target Addressing Syntax
+
+Cleanroom targets can be addressed using multiple canonical notations:
+
+| Format | Example | Description |
+| :--- | :--- | :--- |
+| **Fully Qualified Target** | `//staging/parts/agent:agent_config#lib` | Exact unit and role address |
+| **File Path** | `staging/parts/agent/lib/agent_config.py` | Automatically resolved to target address |
+| **Role Partition** | `staging/parts/agent/lib` or `staging#lib` | All units under the `lib` role |
+| **Part Directory** | `staging/parts/agent` | All roles and units under `agent` part |
+| **Scope Directory** | `staging` | Entire directory scope across all parts & roles |
+
+---
+
+## 4. Test Suite Execution
+
+To run repository verification checks, static type checks, and pytest suites cleanly:
+
+```bash
+bin/test
+```
+
+---
+
+## 5. Model Configuration Schema (`model_configs.toml`)
+
+Cleanroom resolves model definitions, capability tiers, and financial rate cards from:
+1. Explicit CLI flag: `--model-config <path>` or `CLEANROOM_MODEL_CONFIG_FILE` environment override
+2. Local repository candidate: `./model_configs.toml`
+3. Canonical user configuration: `~/.config/cleanroom/model_configs.toml`
+4. Canonical starter template: [`update_python_with_ai/templates/model_configs.toml`](update_python_with_ai/templates/model_configs.toml)
+
+Run `uv run cleanroom configure` to scaffold `~/.config/cleanroom/model_configs.toml` and credentials templates.
+
+### TOML Schema Reference
+
+```toml
+# Top-Level Harness Defaults
+default = "qwen-moe-q6"                  # Default model profile name
+loop_default = "qwen-moe-q6"             # Default for autonomous loop harness
+antigravity_default = "gemini-4-argon"   # Default for Antigravity harness
+dsh_default = "deepseek-v41-flash"       # Default for DeepSeek Harness (DSH)
+max_unproductive_rounds = 5              # Global circuit-breaker round limit
+
+# Model Profiles: [models.<profile-name>]
+# IMPORTANT: Model keys containing dots must be quoted in TOML, e.g. [models."gemini-3.8-flash"]
+
+[models.deepseek-v41-flash]
+model = "deepseek-flash"                 # Model identifier sent to provider API
+provider = "deepseek"                    # Protocol adapter ("deepseek", "google", "openai", "anthropic", "mlx", "omlx")
+tier = 2                                 # Capability tier (1=Local, 2=Budget, 3=Mid-Tier, 4=Frontier)
+tier_label = "Budget API"                # Descriptive capability label
+rate_uncached_in = 0.15                  # USD per 1,000,000 uncached input tokens
+rate_cached_in = 0.003                   # USD per 1,000,000 cached input tokens (prompt cache hit)
+rate_out = 0.60                          # USD per 1,000,000 output tokens (including reasoning tokens)
+default_harness = "dsh"                  # Recommended runtime harness ("dsh", "antigravity", "loop")
+base_url = "https://api.deepseek.com/v1" # HTTP base endpoint
+api_key_env = "DEEPSEEK_API_KEY"         # Environment variable holding the API key
+max_tokens = 8192                        # Max completion tokens per request
+subagent_batch_size = 10                 # Maximum concurrent role subagent dispatches
+conversation_max_tokens = 256000         # Context window compaction threshold in tokens
+max_feedback_chars = 4000                # Max feedback buffer length preserved across rounds
+max_unproductive_rounds = 5              # Profile-level circuit breaker
+temperature = 0.7                        # Generation temperature
+timeout_seconds = 120.0                  # Request/process timeout in seconds
+```
+