Docs rewrite 4/5: the developer corner

[EiffL]

Fourth pass — the maintainer half of the site: maintainer.md, architecture.md, an Engine Internals section replacing the old Python API pages, and the contributing trio.

What's in it

• architecture.md: the CLI/engine/ASTRA split; the run pipeline as one annotated diagram (guards → converge → plan → fetch → venue → workers → driver loop → crate); identity (two hashes, three states, the one-classify-two-callers discipline); storage (DataLad model, run records, thin commits); the exec boundary (policy → argv rewrite → attestation); the container hatch; venues; the crate. This is CLAUDE.md's invariants translated for humans who didn't live the rebuild.
• maintainer.md: the welcome page in its old shape — what the corner covers, the three-command dev loop, and the house rules (no dead code/foreshadowing, no escape hatches, literal behavior, one implementation per rule, honest reporting).
• Engine Internals (docs/api/, 12 pages): an overview map plus one hand-written tour per module — project, dataset, identity, plan, assets, worker, materialize, venue, sandbox, image & container, crate. Each page: responsibility, key-symbols table, "what must stay true", and where its tests live. Hand-written rather than autodoc, deliberately: the engine is not a public API (projects don't depend on lightcone-cli), so contract beats signatures. The 17 old pages documented modules that no longer exist; all deleted.
• Contributing: setup.md (uv-only loop, the gated-suite table, docs/wheel builds, pre-PR checklist), testing.md (the tools/real_tools seam, a where-does-this-question-belong table, the enforcement suite's four properties, the mutation-check rule and its two traps), and a new extending.md (the change-map table plus the everywhere-rules and conventions).
• Deleted: docs/hpc/ (site-registry model), contributing/backends.md, contributing/hpc-sites.md. Nav updated (Python API → Engine Internals; Extending added).

Verification

• zensical build now reports zero issues — the two warnings that survived passes 1–3 lived in pages this one deletes.
• Module pages were anchored on the modules' own docstrings and CLAUDE.md's invariants; symbol names spot-checked against the source (e.g. runtime_for_run's (Runtime, "built"|"present") return, datalad_run_subject, _SITES).
• No remaining references to any deleted page anywhere in docs/.

Next and last: (5) final polish — check-docs.yml refresh and CLAUDE.md reconciliation (the docs-frozen rules, the design-doc pointer).

🤖 Generated with Claude Code

https://claude.ai/code/session_01DJzmp2MUhwiNHR94cB91dx

[github-actions]

✅ Eval

Metric	Value
Outputs check	success
Agent run	success
Turns	34
Tool calls	32
Cost	$0.90
Agent wall time	2m38s
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        8942e05
  · current  baseline/hubble_diagram  8942e05
  · current  baseline/residuals       8942e05

3 current

Confusion & pain points (Claude analysis)

Confusion & pain points

• Script test run failed with ModuleNotFoundError: No module named 'numpy' when invoking python3 directly instead of uv run python3. The agent's own memory ("run inside the project's venv") isn't reflected in any harness nudge — a first-time agent without that instinct would burn a cycle rediscovering that lc/uv projects require the uv run prefix for anything beyond the CLI itself.
• No real confusion or backtracking otherwise — the agent used the astra skill up front, read data/README.md for the input-declaration convention, validated with astra-tools before committing, and materialized cleanly on the first lc materialize after fixing the one dependency slip. This is a notably clean run.
• Minor detour probing dataset semantics: the agent ran an ad hoc Python one-liner to check whether the z_min_001 redshift cut was a no-op on this dataset (n with z<=0.01), which is reasonable data validation but shows the spec/decisions grammar (redshift_cut values) isn't self-documenting enough to know its effect without executing code — a decisions: description or comment in astra.yaml could have made this unnecessary.
• License/publication step was undocumented at spec time: the agent only added license = "CC-BY-4.0" to pyproject.toml after lc status proactively surfaced "crate: not maintained — declare .license to enable it." This is the system correctly guiding the agent rather than a pain point, but it's worth noting the agent had no way to know about the RO-Crate/license linkage except by reading that status line — nothing in the initial astra.yaml or scaffold docs mentioned it.

Full trace: agent-trace artifact on this run.

[EiffL]

LGTM