Docs rewrite 1/5: README, landing page, install, getting started - #185
Open
EiffL wants to merge 1 commit into
Open
Docs rewrite 1/5: README, landing page, install, getting started#185EiffL wants to merge 1 commit into
EiffL wants to merge 1 commit into
Conversation
First pass of the post-rebuild documentation rewrite, covering the entry points: the README, the docs landing page, the user-guide welcome, install, and a new getting-started walkthrough. Every claim tracks the rebuilt CLI: `lc materialize` is the build verb, states are current/behind/stale, the environment is the project's own lock managed with `uv add`, builds start from a clean tree and commit every output with its manifest and run record, and a declared license turns on the RO-Crate publication view. The install page states the real prerequisites (uv + git; git-annex arrives as a wheel and sets the platform floor), the git-identity requirement, and the detected-never-configured container runtime — the old global config file is gone. The walkthrough is a new worked example — a line fit sweeping an outlier-handling decision across two universes, ending published as a crate — and every command block was executed against the current `lc` before landing, including the fresh-clone story (`lc init` rebuilds the .venv and the annex; the up-to-date verdict needs no annex content). Console outputs quoted in the guide are captured from the real run. Style follows the previous docs: tabs, admonitions, numbered steps, "a few things to notice" asides, and a "what just happened" recap. The remaining user-guide pages (cluster, troubleshooting, glossary), the reference, and the developer corner land in the next passes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DJzmp2MUhwiNHR94cB91dx
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First pass of the post-rebuild documentation rewrite — the entry points:
README.md,docs/index.md,docs/user/{index,install,getting-started}.md. Style deliberately follows the previous versions (tabs, admonitions, numbered steps, the "what just happened" recap); the content is brought to the rebuilt CLI.What changed
init→ spec + scripts →uv add→ commit →materialize); the Capabilities section replaceslc verify/lc export wrroc/ Snakemake with what exists — multiverse materialization, provenance by construction (manifests + run records, annex-carried bytes), locked sandboxed execution, derived containerized mode + SLURM, and the license-derived RO-Crate view.~/.lightcone/config.yamlno longer exists. Upgrade section notes an engine upgrade never invalidates results.baselineandrobustuniverses, ending with the license declaration and the auto-committedro-crate-metadata.json. It walks through the scaffold, declared inputs and the annex, the dependency contract and placeholders,uv add, the clean-tree rule, reallc materialize/lc statusoutput, incremental rebuilds, and the fresh-clone story.Verification
lcbefore landing; the quoted console output is captured from that run (slope numbers included).lc init+lc materializereports up to date with no annex content fetched — the guide says exactly that.zensical buildpasses; the two remaining link warnings are in frozen pages (api/snakefile.md,hpc/targets.md) that later passes replace.Next passes: (2) core concepts + cluster/troubleshooting/glossary, (3) CLI + JSON reference, (4) developer corner, (5) nav + workflow refresh.
Two cosmetic engine warts observed while verifying, deliberately not touched here: Rich markup swallows the literal
[project]in the license hint (renders as "no .license in pyproject.toml"), and a stray Dask teardownTimeoutErrorline can appear on stderr after a run.🤖 Generated with Claude Code
https://claude.ai/code/session_01DJzmp2MUhwiNHR94cB91dx