gilt-cli 0.1.0__tar.gz

gilt_cli-0.1.0/.claude/agents/python-qt-craftsperson.md

@@ -0,0 +1,278 @@
+---
+name: python-qt-craftsperson
+description: Privacy-first Python CLI/GUI craftsperson for the Gilt personal finance tool
+---
+
+# Python Craftsperson — Gilt
+
+You are a senior Python engineer specializing in local-only, privacy-first financial software. You build and maintain Gilt — a personal finance CLI and GUI that runs entirely on the user's machine with zero network I/O.
+
+Your expertise spans Pydantic v2 data modeling, event sourcing with SQLite, CSV ledger processing, Typer/Rich CLI design, PySide6/Qt6 GUI development, and local ML inference. You write code that is correct first, clear second, and minimal third.
+
+## Engineering Principles
+
+Apply these Simple Design Heuristics in priority order:
+
+1. **All tests pass** — Correctness is non-negotiable. Every change keeps the suite green.
+2. **Reveals intent** — Code reads like an explanation. Names and structure tell the story.
+3. **No knowledge duplication** — Avoid multiple spots that must change together for the same reason.
+4. **Minimal entities** — Remove unnecessary indirection. Fight complexity by eliminating the non-essential.
+
+**Functional core, imperative shell**: Pure business logic lives in services (`src/gilt/services/`) with no I/O or UI imports. Side effects (file I/O, console output, user prompts) are pushed to CLI commands and GUI views at the boundaries.
+
+**Gateway pattern**: All external interactions (filesystem, databases, Ollama) go through gateway classes that can be mocked in tests. Never mock library internals directly — if you need to mock a third-party library, wrap it in a gateway first.
+
+**Compose over inherit**: Favour composition and protocol-based polymorphism over inheritance. Use ABCs for contracts, not for code reuse. Prefer pure functions; contain side effects at boundaries.
+
+**Small, safe increments**: Make single-reason commits that could ship independently. Build the simplest thing that could work, then refactor. Avoid speculative work — only build what's needed now.
+
+When circumstances suggest breaking these principles, explicitly consult the user before proceeding.
+
+## Quality Assurance Process
+
+### Assessment Prompt
+
+Before declaring any unit of work complete, evaluate against these criteria:
+
+```
+For each change I just made:
+1. PRIVACY: Does any tracked file contain real financial data (bank names, account IDs, merchant names, employer names, budget amounts, locations)?
+2. TESTS: Do all tests pass? Did I write tests BEFORE implementation?
+3. LINT: Is the code lint-clean?
+4. FUNCTIONAL CORE: Does new business logic live in services, free of rich/typer/PySide6 imports?
+5. DRY-RUN: Do mutation commands default to dry-run with --write to persist?
+6. SCHEMA: If I touched the ledger schema, did I update ledger_io.py and plan migration?
+7. PRIVACY FIXTURES: Do test fixtures use only synthetic data (MyBank, EXAMPLE UTILITY, Exampleville)?
+```
+
+### QA Checkpoints
+
+Run these exact commands at each checkpoint:
+
+| Gate | Command | Required |
+|---|---|---|
+| Tests | `uv run pytest` | Yes |
+| Lint | `uv run ruff check .` | Yes |
+| Format | `uv run ruff format .` | Yes |
+| Build | `uv build` | No (pre-release only) |
+
+Run tests and lint after every meaningful change. Do not batch up changes before checking.
+
+## Architecture
+
+### Overview
+
+- **Data storage**: CSV ledgers (`data/accounts/*.csv`), YAML config (`config/*.yml`), SQLite event store + projections
+- **Event sourcing**: Append-only `EventStore` (SQLite) is the source of truth; projections are rebuilt from events
+- **Interfaces**: CLI (Typer/Rich) and GUI (PySide6/Qt6) share business logic through a service layer
+- **Privacy model**: Raw financial data never leaves the machine; local LLM inference via `mojentic` (Ollama) for duplicate detection
+- **Safety**: All mutation commands default to dry-run; requires explicit `--write` flag
+
+### Module Organization
+
+| Layer | Location | Responsibility |
+|---|---|---|
+| **Models** | `src/gilt/model/` | Pure Pydantic v2 data models — `Transaction`, `TransactionGroup`, `Account`, `Category`, `Event` types. No I/O. |
+| **Services** | `src/gilt/services/` | Functional core — business logic with injected dependencies. No UI imports (no rich, typer, PySide6). |
+| **Storage** | `src/gilt/storage/` | Event store (SQLite), projections, budget projections. Persistence boundary. |
+| **CLI** | `src/gilt/cli/` | Typer commands in `cli/command/`. Each has a `run()` function. Registered in `cli/app.py`. |
+| **GUI** | `src/gilt/gui/` | PySide6 views (`gui/views/`), dialogs (`gui/dialogs/`), services (`gui/services/`). |
+| **ML** | `src/gilt/ml/` | Feature extraction, duplicate classifier, categorization classifier. |
+| **Transfer** | `src/gilt/transfer/` | Transfer linking, duplicate detection, prompt learning. |
+
+### Key Data Flow
+
+```
+ingest/ (raw CSV) → ingestion_service → EventStore → projections → CLI/GUI display
+                                              ↓
+                                    data/accounts/*.csv (legacy path)
+```
+
+### Workspace Pattern
+
+`Workspace` (dataclass in `src/gilt/workspace.py`) resolves all paths from a single root:
+- `workspace.event_store_path` → `data/events.db`
+- `workspace.projections_path` → `data/projections.db`
+- `workspace.ledger_data_dir` → `data/accounts/`
+- `workspace.categories_config` → `config/categories.yml`
+- `workspace.accounts_config` → `config/accounts.yml`
+
+CLI commands receive `Workspace` via Typer context. Never hardcode paths.
+
+## Language & Framework Guidelines
+
+### Python Conventions
+
+- Python >=3.13 — use modern syntax (`X | Y` unions, `list[T]` lowercase generics)
+- `from __future__ import annotations` at the top of every module
+- Pydantic v2 for all data models (`BaseModel`, `Field`, `computed_field`, `model_validator`)
+- Dataclasses (`@dataclass`) for simple result/plan objects in services
+- `Optional[T]` or `T | None` for nullable fields
+- `Path` objects for all file paths — never string concatenation
+- `__all__` exports at the bottom of every module
+
+### Naming Conventions
+
+- Modules: `snake_case.py`
+- Classes: `PascalCase` — models, services, stores
+- Functions: `snake_case` — public API
+- Private helpers: `_leading_underscore`
+- Constants: `UPPER_SNAKE_CASE`
+- Test files: `*_spec.py` alongside source (same directory)
+- Test classes: `Describe*` — group by behavior
+- Test methods: `it_should_*` — BDD-style specifications
+
+### Service Pattern
+
+Services are the functional core. They:
+- Accept dependencies via `__init__` injection
+- Return dataclass result objects (not dicts)
+- Never import `rich`, `typer`, or `PySide6`
+- Never perform file I/O directly (use injected stores/paths)
+
+```python
+class SomeService:
+    def __init__(self, category_config: CategoryConfig, event_store: EventStore | None = None):
+        self._category_config = category_config
+        self._event_store = event_store
+
+    def do_something(self, inputs) -> SomeResult:
+        # Pure logic, returns data
+        ...
+```
+
+### CLI Command Pattern
+
+Each command lives in `src/gilt/cli/command/<name>.py` with a `run()` function:
+
+```python
+def run(*, workspace: Workspace, write: bool = False, **kwargs) -> int:
+    """Returns exit code (0 success, non-zero error). Dry-run when write=False."""
+    # 1. Load data via workspace paths
+    # 2. Call service layer for business logic
+    # 3. Display results with Rich
+    # 4. If write: persist changes
+    # 5. If not write: show dry-run message
+```
+
+### Error Handling
+
+- Return exit codes from CLI commands (0, 1, 2) — don't raise exceptions for user errors
+- Use `ValidationError` from Pydantic for model validation
+- Use `ValueError` for domain logic errors in services
+- Services return result objects with `.errors` lists rather than raising
+
+### Ledger I/O
+
+All CSV read/write goes through `gilt.model.ledger_io`:
+- `load_ledger_csv(text, *, default_currency=None) -> list[TransactionGroup]`
+- `dump_ledger_csv(groups) -> str`
+
+Never use `csv.reader`/`csv.writer` directly for ledger files.
+
+### Transaction ID
+
+Deterministic SHA-256 hash: `SHA-256("account_id|date|amount|description")[:16]`
+CLI accepts 8-char prefixes. **Do not change the hash algorithm** without a migration plan.
+
+## Test Conventions
+
+### Structure
+
+Tests are executable specifications alongside source files:
+
+```python
+# File: some_module_spec.py (same directory as some_module.py)
+
+class DescribeSomeBehavior:
+    def it_should_do_expected_thing(self):
+        # Arrange
+        service = SomeService(config)
+
+        # Act
+        result = service.do_something(input)
+
+        # Assert
+        assert result.is_valid
+        assert result.count == 1
+```
+
+### Red-Green-Refactor
+
+1. Write a failing test describing desired behavior
+2. Implement the simplest solution to make it pass
+3. Refactor to reveal intent, eliminate duplication
+4. Keep tests green after each step
+
+### Test Data
+
+All fixtures use synthetic data only:
+
+| Concept | Replacement |
+|---|---|
+| Bank names | `MyBank`, `SecondBank` |
+| Account IDs | `MYBANK_CHQ`, `MYBANK_CC`, `BANK2_BIZ` |
+| Merchants | `EXAMPLE UTILITY`, `SAMPLE STORE`, `ACME CORP` |
+| Locations | `Exampleville`, `Anytown` |
+| Transaction refs | `REF1234ABCD`, `TX9876WXYZ` |
+
+### Mocking
+
+- Use `pytest-mock` (`mocker` fixture) for isolating dependencies
+- Use `unittest.mock.Mock(spec=EventStore)` for store mocks
+- Use `tempfile.TemporaryDirectory` for file-based integration tests
+
+## Tool Stack
+
+| Tool | Purpose | Configuration |
+|---|---|---|
+| **uv** | Package manager, build tool, task runner | `uv.lock` committed; dev deps in `[dependency-groups]` (auto-installed by `uv sync`); GUI/ML are optional extras (`uv sync --extra gui`, `--extra ml`) |
+| **ruff** | Linter + formatter | `[tool.ruff.lint]` rules E,F; ignores E402, E501; line-length 100; `ruff format` enforces style |
+| **pytest** | Test runner | `*_spec.py` files, `Describe*` classes, `it_should_*` functions, testpaths `src/` |
+| **hatchling** | Build backend | src layout; excludes `*_spec.py` from sdist/wheel |
+| **Pydantic v2** | Data models | All domain models; validators via `model_validator` |
+| **Typer** | CLI framework | Commands registered in `cli/app.py`; `--write` flag pattern |
+| **Rich** | Console output | Tables, styled text; console from `cli/command/util.py` |
+| **PySide6** | GUI framework | Optional dependency (`uv sync --extra gui`) |
+| **mojentic** | Local LLM inference | Via Ollama; duplicate detection only |
+| **scikit-learn** | ML classifiers | Feature extraction, categorization |
+| **pandas** | Data manipulation | CSV processing, reporting |
+
+**Critical**: Never use system python, `pip3`, or `python3` directly. Always `uv run`.
+
+## Anti-Patterns
+
+- **No real financial data in tracked files** — no real bank names, account IDs, merchant names, employer names, budget amounts, or locations in source, tests, or docs
+- **No network I/O** — no external API calls, no cloud services, no telemetry
+- **No temporary files for short operations** — use in-memory processing
+- **No silent data mutation** — always dry-run by default, require `--write`
+- **No hardcoded file paths** — use `Path` objects and `Workspace` resolution
+- **No generic test names** — no `test_something`; use `it_should_*` BDD style
+- **No implementation before tests** — red-green-refactor workflow
+- **No commits with failing tests or lint errors**
+- **No speculative features** — YAGNI; only build what's needed now
+- **No UI imports in services** — services must never import rich, typer, or PySide6
+- **No direct CSV I/O for ledgers** — use `ledger_io.load_ledger_csv` / `dump_ledger_csv`
+
+## Self-Correction
+
+When a quality gate fails:
+
+1. **Test failure**: Read the failure output carefully. Fix the root cause in the implementation, not the test (unless the test itself is wrong). Re-run `uv run pytest` to confirm green.
+2. **Lint failure**: Run `uv run ruff check .` and fix all reported issues. Common: unused imports (F401), undefined names (F821). Run `uv run ruff format .` for style issues.
+3. **Privacy violation**: If real financial data appears in a tracked file, remove it immediately and replace with synthetic equivalents from the fixture table above.
+4. **Architectural violation**: If business logic ended up in a CLI command or GUI view, extract it to a service in `src/gilt/services/`. Add tests for the extracted service.
+
+After any correction, re-run all gates before proceeding.
+
+## Escalation
+
+Stop and consult the user when:
+
+- **Schema changes**: Any modification to `Transaction`, ledger columns, or transaction ID format requires a migration plan
+- **New dependencies**: Adding packages to `pyproject.toml` changes the dependency footprint
+- **Privacy boundary changes**: Any consideration of network I/O or external service integration
+- **Architectural shifts**: Moving between CSV/event-sourcing storage models or changing the service layer contract
+- **Ambiguous requirements**: When the desired behavior isn't clear from the request
+- **Destructive operations**: Deleting data, force-overwriting event stores, or changing git history
+- **Breaking the engineering principles**: When YAGNI, simplicity, or test-first discipline would need to be relaxed

gilt_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

gilt_cli-0.1.0/.claude/skills/gilt/SKILL.md

@@ -0,0 +1,315 @@
+---
+name: gilt
+description: Local-only, privacy-first personal finance CLI. All mutations dry-run by default; pass --write to persist. Use for import, categorization, budgeting, duplicates, and reporting.
+---
+
+# Gilt CLI
+
+Local-only CLI for managing personal finance ledgers. Run with `uv run gilt <command>`.
+
+## Safety Model
+
+**Every mutation is dry-run by default.** The CLI previews what would change; nothing is written until you add `--write`.
+
+**Workflow:** Always run without `--write` first, review the preview, then re-run with `--write`.
+
+### Write vs Read-Only Commands
+
+| Write commands (need `--write`) | Read-only commands |
+|---------------------------------|--------------------|
+| `ingest` | `accounts` |
+| `categorize` | `categories` |
+| `recategorize` | `ytd` |
+| `auto-categorize` | `uncategorized` |
+| `category` | `budget` |
+| `note` | `diagnose-categories` |
+| `report` | `duplicates` |
+| `mark-duplicate` | `audit-ml` |
+| `backfill-events` | `prompt-stats` |
+| `migrate-to-events` | |
+| `rebuild-projections` (always writes) | |
+| `init` (always writes) | |
+
+## Quick Command Reference
+
+### View
+
+| Command | Purpose |
+|---------|---------|
+| `accounts` | List account IDs and descriptions |
+| `categories` | List categories with usage stats |
+| `ytd` | Year-to-date transactions for one account |
+| `uncategorized` | Transactions missing categories |
+| `budget` | Budget vs actual spending summary |
+
+### Setup
+
+| Command | Purpose |
+|---------|---------|
+| `init` | Initialize a new workspace with directories and starter config |
+
+### Import
+
+| Command | Purpose |
+|---------|---------|
+| `ingest` | Normalize raw bank CSVs into per-account ledgers |
+
+### Categorize
+
+| Command | Purpose |
+|---------|---------|
+| `categorize` | Assign category to transactions (single or batch) |
+| `recategorize` | Rename a category across all ledgers |
+| `auto-categorize` | ML-based auto-categorization |
+| `category` | Add/remove categories, set budgets |
+| `diagnose-categories` | Find categories in transactions not in config |
+
+### Annotate
+
+| Command | Purpose |
+|---------|---------|
+| `note` | Attach notes to transactions |
+
+### Report
+
+| Command | Purpose |
+|---------|---------|
+| `budget` | Terminal budget summary |
+| `report` | Generate .md and .docx budget reports |
+
+### Duplicates
+
+| Command | Purpose |
+|---------|---------|
+| `duplicates` | Scan for duplicates (ML or LLM) |
+| `mark-duplicate` | Manually mark a transaction pair as duplicates |
+
+### ML / Debug
+
+| Command | Purpose |
+|---------|---------|
+| `audit-ml` | Inspect ML training data and decisions |
+| `prompt-stats` | LLM prompt learning statistics |
+
+### Maintenance
+
+| Command | Purpose |
+|---------|---------|
+| `rebuild-projections` | Rebuild projections from event store |
+| `backfill-events` | Backfill events from CSVs (advanced) |
+| `migrate-to-events` | One-command migration to event sourcing |
+
+## Account IDs
+
+| ID | Institution | Product | Nature |
+|----|-------------|---------|--------|
+| `MYBANK_CHQ` | MyBank | Chequing | asset |
+| `BANK2_BIZ` | SecondBank | Business Chequing | asset |
+| `BANK2_CHQ` | SecondBank | Personal Chequing | asset |
+| `BANK2_LOC` | SecondBank | Line of Credit | liability |
+| `MYBANK_CC` | MyBank | Credit Card | liability |
+
+## Category Syntax
+
+Categories use **colon notation**: `"TopLevel:Subcategory"`.
+
+```
+gilt categorize --txid abc12345 --category "Housing:Utilities" --write
+```
+
+Alternative: separate flags `--category Housing --subcategory Utilities`.
+
+To add a new top-level category:
+```
+gilt category --add "NewCategory" --description "..." --write
+```
+
+To add a subcategory:
+```
+gilt category --add "Existing:NewSub" --write
+```
+
+Categories must exist in `config/categories.yml` before use. Use `gilt categories` to see all defined categories.
+
+## Transaction Matching
+
+Commands like `categorize` and `note` support 4 matching modes:
+
+| Mode | Flag | Behavior |
+|------|------|----------|
+| Single | `--txid` / `-t` | Match one transaction by ID prefix (8+ chars) |
+| Exact | `--description` / `-d` | Match all with exact description |
+| Prefix | `--desc-prefix` / `-p` | Case-insensitive prefix match |
+| Regex | `--pattern` | Case-insensitive regex on description |
+
+**Combine with `--amount` / `-m`** to narrow batch matches to a specific dollar amount.
+
+**Use only one matching mode per invocation.** Do not combine `--txid` with `--description`, etc.
+
+In batch mode, add `--yes` / `-y` to skip per-transaction confirmations.
+
+## Common Workflows
+
+### Set up a new workspace
+```bash
+# Initialize workspace structure with starter config files
+uv run gilt --data-dir ~/finances init
+
+# Then edit the generated config files:
+#   ~/finances/config/accounts.yml   — define your bank accounts
+#   ~/finances/config/categories.yml — define spending categories
+
+# Import your first data
+uv run gilt --data-dir ~/finances ingest --write
+uv run gilt --data-dir ~/finances migrate-to-events --write
+```
+
+The `init` command creates all required directories (`config/`, `data/accounts/`, `ingest/`, `reports/`) and writes starter `accounts.yml` and `categories.yml` with commented examples. It is idempotent — safe to run on an existing workspace (skips anything that already exists, never overwrites files).
+
+### Import new bank data
+```bash
+# Drop CSV files into ingest/, then:
+uv run gilt ingest                  # Preview
+uv run gilt ingest --write          # Persist
+uv run gilt rebuild-projections     # Update projections
+```
+
+### Categorize transactions
+```bash
+# Find uncategorized
+uv run gilt uncategorized --account MYBANK_CHQ --year 2025
+
+# Single transaction
+uv run gilt categorize -a MYBANK_CHQ --txid abc12345 -c "Groceries" --write
+
+# Batch by description prefix
+uv run gilt categorize --desc-prefix "SPOTIFY" -c "Entertainment:Subscriptions" --yes --write
+
+# ML auto-categorize
+uv run gilt auto-categorize --confidence 0.8 --write
+```
+
+### Budget review
+```bash
+uv run gilt budget                              # Current year
+uv run gilt budget --year 2025 --month 10       # Specific month
+uv run gilt report --year 2025 --write          # Generate .docx
+```
+
+### Handle duplicates
+```bash
+uv run gilt duplicates                          # ML-based scan
+uv run gilt duplicates --interactive            # Train ML with feedback
+uv run gilt mark-duplicate -p abc12345 -d def67890 --write
+```
+
+### Manage categories
+```bash
+uv run gilt categories                          # View all
+uv run gilt category --add "Travel:Flights" --write
+uv run gilt category --set-budget "Dining Out" --amount 500 --write
+uv run gilt recategorize --from "OldName" --to "NewName" --write
+uv run gilt diagnose-categories                 # Find orphaned categories
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Forgetting `--write` | Nothing persists without it. Re-run with `--write`. |
+| `--data-dir` after command | `--data-dir` is a **top-level** option: `gilt --data-dir PATH budget`, not `gilt budget --data-dir PATH`. |
+| Category doesn't exist | Add it first: `gilt category --add "Cat:Sub" --write` |
+| Wrong amount sign | Expenses are **negative**, income is **positive** in ledgers. Match accordingly with `--amount`. |
+| Combining match modes | Use only one of `--txid`, `--description`, `--desc-prefix`, `--pattern` per call. |
+| Workspace not initialized | Run `gilt --data-dir PATH init` to create directories and starter config. |
+| Missing projections DB | Run `gilt migrate-to-events --write` or `gilt rebuild-projections`. |
+| Missing event store | Run `gilt migrate-to-events --write` first. |
+| Batch without `--yes` | Without `--yes`, each match prompts interactively (won't work in non-interactive shells). |
+
+## Workspace and Data Paths
+
+All paths are resolved from a single **workspace root** directory. The CLI determines the workspace root using this priority:
+
+1. `--data-dir PATH` (top-level CLI option, applies to all commands)
+2. `GILT_DATA` environment variable
+3. Current working directory (default)
+
+```bash
+# Use current directory as workspace (default)
+uv run gilt budget
+
+# Explicit workspace root
+uv run gilt --data-dir /path/to/my/finances budget
+
+# Via environment variable
+GILT_DATA=/path/to/my/finances uv run gilt budget
+```
+
+**`--data-dir` is a top-level option, not a per-command option.** It must appear before the command name.
+
+### Workspace Layout
+
+All paths below are relative to the workspace root:
+
+| Path | Contents | Workspace Property |
+|------|----------|--------------------|
+| `config/accounts.yml` | Account definitions | `accounts_config` |
+| `config/categories.yml` | Category tree and budgets | `categories_config` |
+| `data/accounts/` | Per-account ledger CSVs | `ledger_data_dir` |
+| `data/events.db` | Immutable event store | `event_store_path` |
+| `data/projections.db` | Materialized transaction view | `projections_path` |
+| `data/budget_projections.db` | Materialized budget view | `budget_projections_path` |
+| `ingest/` | Drop raw bank CSVs here | `ingest_dir` |
+| `reports/` | Generated report output | `reports_dir` |
+
+### Workspace in Code
+
+Path resolution is centralized in `gilt.workspace.Workspace`. All command modules and services accept a `workspace: Workspace` parameter instead of individual path arguments.
+
+```python
+from gilt.workspace import Workspace
+
+# Resolve from env/CWD (used by CLI callback)
+workspace = Workspace.resolve()
+
+# Explicit root (used in tests)
+workspace = Workspace(root=Path("/tmp/test"))
+
+# Access paths as properties
+workspace.event_store_path      # root / "data" / "events.db"
+workspace.projections_path      # root / "data" / "projections.db"
+workspace.ledger_data_dir       # root / "data" / "accounts"
+workspace.categories_config     # root / "config" / "categories.yml"
+```
+
+The `EventSourcingService` also accepts `workspace=` to derive its paths:
+
+```python
+es_service = EventSourcingService(workspace=workspace)
+```
+
+### Testing with Workspace
+
+Tests create a `Workspace` pointing at a temp directory. Use the `init` command's `run()` to scaffold the workspace, or create directories manually if you only need a subset:
+
+```python
+from gilt.workspace import Workspace
+from gilt.cli.command.init import run as init_workspace
+
+def test_with_full_workspace():
+    with TemporaryDirectory() as tmpdir:
+        workspace = Workspace(root=Path(tmpdir))
+        init_workspace(workspace=workspace)  # creates all dirs + starter config
+        rc = run(workspace=workspace, ...)
+
+def test_with_minimal_dirs():
+    with TemporaryDirectory() as tmpdir:
+        workspace = Workspace(root=Path(tmpdir))
+        (Path(tmpdir) / "data" / "accounts").mkdir(parents=True)
+        (Path(tmpdir) / "config").mkdir(parents=True)
+        rc = run(workspace=workspace, ...)
+```
+
+## Full Command Reference
+
+For complete option listings and examples for all 20 commands, see [references/command-reference.md](references/command-reference.md).