Docs rewrite 3/5: the CLI reference

[EiffL]

Third pass — docs/cli/ rebuilt around the five verbs that exist, in the frozen pages' structure (Synopsis / semantics / options table / JSON / examples).

What's in it

• Overview (cli/index.md): the three global behaviors (current directory is the project — no walk-up, no global config; nothing waits on a human; refusals carry their remedy) and the exit-code contract, including lc run's proxying and the --check gate semantics.
• lc init: the four convergence classes (created / repaired / blocked / warned — with blocked counting against convergence and warnings never affecting exit), the real scaffold tree, what it deliberately doesn't create (src/, dependencies), and the deliberately bare flag surface.
• lc materialize (new page): target grammar (fit vs robust/fit, matching-nothing is an error), the remake rules (stale vs behind vs current under --refresh), the run's contract (clean in/clean out, fetches declared inputs, commits as it goes, reports every independent failure, converges the crate), check mode's dirty-tree exemption, the absent-flags rationale (--jobs, --force), and the JSON report with ok/up_to_date called out as the branching keys.
• lc status: the header facts, the commit column as the verb's reason to exist, the three states, the report-vs-gate split, and the JSON shape including foreign_write.
• lc run: the probe — same environment and sandbox as a recipe, environment converge first, exit-code proxying (128+N), denial notes, works on any uv project, no sandbox opt-out.
• lc build: the system-layer-only image, the closed declaration key set, the committed docker-archive as the store (id-pinned, no registry), the arch refusal, the clean-tree requirement, and the JSON result (action: built | present).
• verify.md and export.md deleted with their verbs; nav updated (materialize added, order follows the workflow).

Verification

• All --help texts, the init/materialize/status JSON shapes, and the console blocks were captured from the current CLI against a real project.
• The build JSON keys and action values were read from commands.py/container.py, and the tag format corrected against image.py (lc-env-<16 hex> — my first draft had the pre-rebuild lc-<project>-<hash> spelling).
• zensical build: no new warnings; the two remaining are in frozen pages PR 4 replaces.

Next: (4) developer corner, (5) nav + workflow refresh + final reconciliation.

🤖 Generated with Claude Code

https://claude.ai/code/session_01DJzmp2MUhwiNHR94cB91dx

[EiffL]

LGTM

[github-actions]

✅ Eval

Metric	Value
Outputs check	success
Agent run	success
Turns	47
Tool calls	44
Cost	$1.33
Agent wall time	4m15s
Model	claude-sonnet-5

lc status

  mode:    direct
  sandbox: landlock (fs: declared, network: allowed)
  crate:   up to date with the outputs

  · current  baseline/best_fit        badf604
  · current  baseline/hubble_diagram  badf604
  · current  baseline/residuals       badf604

3 current

Confusion & pain points (Claude analysis)

Confusion & pain points

• astra spec subcommand rejected valid-looking type names. The agent tried uvx astra-tools@0.2.13 spec metric and spec figure, both of which failed with "Unknown term" — the schema apparently has no Metric or Figure type, forcing a guess-and-check pass over spec Recipe/spec Decision before landing on real terms. This suggests the ASTRA skill (or --help/spec list) should surface the valid term list up front instead of making the agent discover it by trial and error.
• L-BFGS-B's unconstrained gradient stepped outside the physical domain. Testing fit.py under lc run with the l_bfgs_b optimizer produced NaN chi-squared because the finite-difference gradient pushed Omega_L past 1, driving E(z)^2 negative — a real bug in the agent's own script, not the CLI, caught only because it proactively smoke-tested both optimizer decisions via lc run before committing to a full lc materialize.
• Every sandboxed run printed a recurring ignored ambient UV_PYTHON notice. This is expected behavior per the harness's env-scrubbing design, but it showed up as noise on nearly every lc run/lc materialize invocation with no way to silence it — worth confirming this is intentional attestation-of-scrub messaging rather than something an eval harness should suppress for signal-to-noise.
• Minor detour resolving the systematic-error model from data alone. The agent had to awk-inspect the raw SCPUnion2.1_mu_vs_z.txt header and column value distributions (mode counts, uniq -c) to reverse-engineer how error_model: stat_and_sys should be computed, since the spec's decision only names it without defining the derivation — not a CLI/harness issue, but a place where the astra.yaml scaffold left the semantics underspecified for the agent to infer from the dataset itself.
• Otherwise the run was clean: validation, lc run probes, lc materialize, and the final --check/crate gates all passed on the first real attempt with no CLI errors or misunderstandings of the sandbox/execution model.

Full trace: agent-trace artifact on this run.