# Operations

The canonical commands below operate the promoted image-only vNext workflow.

## Environment

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
```

## Install current Codex

Chartsmith requires an official Codex CLI with GPT-5.6 and built-in image
generation support. Install it to an isolated user cache:

```powershell
$codexBin = .\scripts\bootstrap_codex.ps1 | Select-Object -Last 1
```

The bootstrap downloads the latest official Windows release from OpenAI's GitHub
release, verifies the published SHA256 digest when present, and does not replace
the global `codex` command.

## Validate and run

```powershell
.\.venv\Scripts\python.exe scripts\chartsmith_vnext.py validate
.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py"
.\.venv\Scripts\python.exe scripts\chartsmith_vnext.py run <image> --codex-bin $codexBin
```

The input contract is one chart image and no required context, data, or design
prompt. The default output root is `runs/build_week/vnext/`.

Validate an accepted run:

```powershell
.\.venv\Scripts\python.exe scripts\chartsmith_vnext.py validate-run <run-dir>
```

Resume a recorded image-generation failure or an interrupted recovery after a
bound increase:

```powershell
.\.venv\Scripts\python.exe scripts\chartsmith_vnext.py resume <run-dir> --codex-bin $codexBin
```

The Codex-native GPT Image backend requires no API key. The hosted Responses API
route remains optional:

```powershell
$env:OPENAI_API_KEY = "<key>"
.\.venv\Scripts\python.exe scripts\chartsmith_vnext.py run <image> --backend responses-api
```

The fixed Milestone 2 inputs remain in
`config/experiments/build_week_vnext/cases.yaml`. The active ten-example
portfolio is declared in
`config/experiments/build_week_vnext/milestone4_portfolio.yaml`.

Regenerate, schedule, curate, and validate the portfolio:

```powershell
.\.venv\Scripts\python.exe scripts\generate_milestone4_sources.py
.\.venv\Scripts\python.exe scripts\run_milestone4_portfolio.py --codex-bin $codexBin
.\.venv\Scripts\python.exe scripts\curate_milestone4_portfolio.py
.\.venv\Scripts\python.exe scripts\validate_milestone4_portfolio.py
```

The scheduler is capped at two concurrent runs and never overwrites an existing
run. The validator requires ten distinct sources, accepted manifests, complete
evidence, all five final gates, and explicit source-rights metadata.

## Judge-facing product

Install the web dependencies once:

```powershell
cd app\web
$env:NODE_OPTIONS = "--use-system-ca"
npm ci
cd ..\..
```

Start the complete local product from the repository root:

```powershell
.\.venv\Scripts\python.exe scripts\start_chartsmith_app.py
```

Open `http://localhost:3000/`. The command refreshes the accepted example
journeys, resolves the supported Codex executable, starts the durable local run
service, and starts the product UI. Press `Ctrl+C` once to stop both services.

The examples remain available when the live engine is offline. A genuine upload
requires both services and creates canonical output under
`runs/build_week/vnext/`.

Validate the product surfaces:

```powershell
.\.venv\Scripts\python.exe -m unittest discover -s tests -p "test_*.py"
cd app\web
npm test
cd ..\..
.\.venv\Scripts\python.exe scripts\validate_repo_state.py
```

Rebuild the static example presentations after changing a projector or accepted
example:

```powershell
.\.venv\Scripts\python.exe scripts\chartsmith_web.py build-examples
```

The Sites project is registered but public deployment is intentionally deferred.
See `milestone_3_architecture.md` for the local-versus-hosted execution boundary.

## v2.6 rollback baseline

The former generated workflow remains runnable for comparison:

```powershell
.\.venv\Scripts\python.exe scripts\render_workflow_scripts.py
.\.venv\Scripts\python.exe scripts\generated_chart_workflow.py validate --workflow config\chart_redesign_workflow.yaml
```

## Evaluation

```powershell
.\.venv\Scripts\python.exe scripts\chartsmith_evaluator.py list-tiers
.\.venv\Scripts\python.exe scripts\chartsmith_evaluator.py run --tier smoke --experiment-id <id>
```

Start with smoke or screening. Treat usage-limit failures separately from workflow
and quality failures.

## NodeBench

```powershell
.\.venv\Scripts\python.exe scripts\nodebench.py list-nodes
.\.venv\Scripts\python.exe scripts\nodebench.py validate-pack --node design_proposition
.\.venv\Scripts\python.exe scripts\nodebench.py dry-run --node design_proposition --run-id validation-dry-run
```

## Manifests

```powershell
.\.venv\Scripts\python.exe scripts\build_repo_manifests.py --snapshot-id <id> --publish-run-manifest
```

Full manifests hash files and can take several minutes because the historical run
lake is large. Scan errors from inaccessible legacy OneDrive entries are retained
as evidence rather than hidden.
