From a01d4cf3941426f729b98c161c2b49f5b7addd80 Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 14:17:10 +0200 Subject: [PATCH 1/9] First landing page improvement --- docs/index.md | 73 +++++++++++++++------------------------------- docs/maintainer.md | 1 + 2 files changed, 24 insertions(+), 50 deletions(-) create mode 100644 docs/maintainer.md diff --git a/docs/index.md b/docs/index.md index f2d6400..3af37e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,72 +6,43 @@ the `lc` executable, a small set of Claude Code skills, and the provenance/integrity machinery that ties an `astra.yaml` spec to a tree of materialized outputs. -This site has two halves. +This documentation has two halves. -## I'm a researcher and I want to use this thing +
-Start at the [User Guide](user/index.md). Friendly, step-by-step, with -worked examples. You will not need to read any Python. +- __I want to try this out__ -The shortest possible path: + --- -=== "uv" - ```bash - uv tool install lightcone-cli - lc init my-analysis && cd my-analysis - claude # then, inside Claude Code: /lc-new - ``` + Start with a short installation guide followed by a step-by-step tutorial. Continue with instructions to continue on a computer cluster. Learn about the agentic framework a short, step-by-step, with + worked examples. You will not need to read any Python. -=== "pip" - ```bash - pip install lightcone-cli - lc init my-analysis && cd my-analysis - claude # then, inside Claude Code: /lc-new - ``` + [:lucide-rocket: User Guide](user/index.md){ .md-button .md-button--primary } -## I work on lightcone-cli +- __I want to contribute to lightcone-cli__ -Welcome — keep reading. The rest of this page is a fast tour for -contributors and maintainers; deep dives live in the sub-trees of the -nav. + --- ---- - -## Two packages, one toolchain + Welcome — keep reading. The rest of this page is a fast tour for + contributors and maintainers; deep dives live in the sub-trees of the + nav. -| Layer | Package | Role | -|-------|---------|------| -| **ASTRA** | `astra-tools` | Pure specification: schema, validation, prior insights & findings, evidence verification helpers, the `astra` CLI. | -| **lightcone-cli** | `lightcone-cli` | Agentic layer: project scaffolding, Snakemake-based execution, Dask cluster management, container builds, Claude Code skills. | + [:lucide-cog: Developer corner](maintainer.md){ .md-button .md-button--primary } -`lightcone-cli` depends on `astra-tools`. The `astra` CLI handles the -spec itself (validation, paper management, evidence verification); the -`lc` CLI handles execution and the agent surface. +
-## What every materialized output gets +--- -A sidecar `.lightcone-manifest.json` next to its data, recording: +## Two packages, one toolchain -- `code_version` = `sha256(recipe + container_image + decisions)` -- `data_version` = `sha256_dir(output_dir)` excluding the manifest itself -- `input_versions` for each declared input (chained data_version when the - input is another materialized output, `mtime-size` or `sha256` for - external files) -- `container_image`, `recipe`, `decisions`, `git_sha`, `lc_version`, - `host`, `slurm_job_id`, `finished_at` +**lightcone-cli** depends on [**astra-tools**][astra-tools], the SDK for working with ASTRA analysis specifications. -`lc verify` recomputes `data_version` and walks the chain. Failures -surface as `tampered_data`, `broken_chain`, or `missing_manifest`. `lc -status` reads only manifests — works offline, no Snakemake or DB needed. +[**astra-tools**][astra-tools] provides the `astra` CLI which handles the +whole ASTRA lifecycle and validation process (schema, validation, prior insights & findings, evidence verification helpers). -## Development setup +**lightcone-cli** provides the `lc` CLI which handle the agent surface (skills, plugins, guardrails) as well as the workflow execution layer. -```bash -just install # uv sync --all-groups -just test # uv run pytest -just lint # ruff + mypy -just docs-serve # live docs preview -``` +[:lucide-book-open: Read more on the ASTRA specification](https://astra-spec.org/latest/){ .md-button } ## Where to read next @@ -80,3 +51,5 @@ just docs-serve # live docs preview - [Python API](api/index.md) — the engine modules - [Skills](skills/index.md) — what each `/lc-*` skill does (including the `/lc-from-*` family) - [Contributing](contributing/setup.md) — getting the dev loop running + +[astra-tools]: https://github.com/LightconeResearch/astra-tools \ No newline at end of file diff --git a/docs/maintainer.md b/docs/maintainer.md new file mode 100644 index 0000000..d890003 --- /dev/null +++ b/docs/maintainer.md @@ -0,0 +1 @@ +# Developer corner From 5032b96b71710602fde3321c2d44d031fe2a29ec Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 14:17:19 +0200 Subject: [PATCH 2/9] Small tweaks --- zensical.toml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/zensical.toml b/zensical.toml index 84f5020..d7d178c 100644 --- a/zensical.toml +++ b/zensical.toml @@ -3,6 +3,7 @@ site_name = "lightcone-cli" site_description = "Agentic execution layer for ASTRA research pipelines" site_author = "Lightcone Research Team" repo_url = "https://github.com/LightconeResearch/lightcone-cli" +repo_name = "LightconeResearch/lightcone-cli" copyright = "© 2026 Lightcone Research" docs_dir = "docs" extra_css = ["stylesheets/extra.css"] @@ -60,6 +61,7 @@ nav = [ {"Authoring Skills" = "skills/authoring.md"}, ]}, ]}, + {"ASTRA docs" = "https://astra-spec.org/latest/"}, ] [project.theme] From 4636a64003482c774577a4bac7f97fa87bbd1e67 Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 15:08:08 +0200 Subject: [PATCH 3/9] Finalize landing page --- docs/index.md | 54 +++++++++++++++++++++++++-------------------------- 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3af37e0..ba4d8d7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,55 +1,55 @@ # lightcone-cli -**lightcone-cli** is Lightcone Research's agentic execution layer for -**ASTRA** (Agentic Schema for Transparent Research Analysis). It ships -the `lc` executable, a small set of Claude Code skills, and the -provenance/integrity machinery that ties an `astra.yaml` spec to a tree +**lightcone-cli** is [Lightcone Research][lr]'s agentic execution layer for +[**ASTRA**][astra] (Agentic Schema for Transparent Research Analysis). +It serves as the machinery that ties an analysis `astra.yaml` specification to a tree of materialized outputs. -This documentation has two halves. +## Choose your path to the documentation
-- __I want to try this out__ +- __I want to try it out__ – :lucide-rocket: --- - Start with a short installation guide followed by a step-by-step tutorial. Continue with instructions to continue on a computer cluster. Learn about the agentic framework a short, step-by-step, with - worked examples. You will not need to read any Python. + Installation instructions, step-by-step tutorial, and fast tour of the lightcone framework and its agentic and workflow capabilities. - [:lucide-rocket: User Guide](user/index.md){ .md-button .md-button--primary } + [User Guide](user/index.md){ .md-button .md-button--primary } -- __I want to contribute to lightcone-cli__ +- __I want to contribute__ – :lucide-cog: --- - Welcome — keep reading. The rest of this page is a fast tour for - contributors and maintainers; deep dives live in the sub-trees of the - nav. + In depth tour of the software architecture, agentic skills and API docs, as well as contribution instructions, aimed for + contributors and maintainers. - [:lucide-cog: Developer corner](maintainer.md){ .md-button .md-button--primary } + [Developer corner](maintainer.md){ .md-button .md-button--primary }
--- -## Two packages, one toolchain +## Two libraries, one toolchain -**lightcone-cli** depends on [**astra-tools**][astra-tools], the SDK for working with ASTRA analysis specifications. +
+ +- __lightcone-cli__ -[**astra-tools**][astra-tools] provides the `astra` CLI which handles the -whole ASTRA lifecycle and validation process (schema, validation, prior insights & findings, evidence verification helpers). + The library that ships the `lc` CLI which handle the agent surface (skills, plugins, guardrails) as well as the workflow execution layer. Depends on [**astra-tools**][astra-tools], the SDK for working with ASTRA analysis specifications. -**lightcone-cli** provides the `lc` CLI which handle the agent surface (skills, plugins, guardrails) as well as the workflow execution layer. + [:fontawesome-brands-github: Repository][cli]{ .md-button } -[:lucide-book-open: Read more on the ASTRA specification](https://astra-spec.org/latest/){ .md-button } +- __astra-tools__ -## Where to read next + The SDK for working with [**ASTRA**][astra] analysis specifications. + This library provides the `astra` CLI which handles the [**ASTRA**][astra] lifecycle and validation process (schema, prior insights & findings, evidence verification helpers). -- [Architecture](architecture.md) — the full execution and integrity story -- [CLI Reference](cli/index.md) — every command currently shipped -- [Python API](api/index.md) — the engine modules -- [Skills](skills/index.md) — what each `/lc-*` skill does (including the `/lc-from-*` family) -- [Contributing](contributing/setup.md) — getting the dev loop running + [:fontawesome-brands-github: Repository][astra-tools]{ .md-button } + +
-[astra-tools]: https://github.com/LightconeResearch/astra-tools \ No newline at end of file +[lr]: https://lightconeresearch.org/ +[astra]: https://astra-spec.org/latest/ +[astra-tools]: https://github.com/LightconeResearch/astra-tools +[cli]: https://github.com/LightconeResearch/lightcone-cli From c7d62b1ca5abf33860f4ee2f2f193fb0a1ac62ef Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 15:49:19 +0200 Subject: [PATCH 4/9] Update welcome page --- docs/user/index.md | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/docs/user/index.md b/docs/user/index.md index 0f56a41..dccbb0f 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -1,23 +1,22 @@ -# Welcome +# Welcome to the user guide `lightcone-cli` is a small toolchain that turns a research question into a reproducible analysis. You describe what you're trying to learn, a cli agent helps you turn that into a precise specification, and the `lc` command line keeps the resulting code, decisions, and outputs in -sync — forever. +sync thanks to the [**ASTRA**][astra] specification. -You don't need to write Python or YAML by hand. The agent handles the -implementation; **you stay in charge of the scientific choices**. +No need to write code by hand, **you stay in charge of the scientific choices**, the agent handles the implementation. ## What this guide covers -- [Install](install.md) — get `lc` and Claude Code running on your - machine. +- [Install](install.md) — get the `lc` command line and Claude Code running on your + machine or on a cluster. - [Getting Started](getting-started.md) — create your first project, run it end-to-end, and understand what each piece does. - [The Agentic Workflow](agent-workflow.md) — `/lc-new`, `/lc-from-code`, `/lc-from-paper`, and `/lc-feedback` — what each - one does and when to reach for it. + command does and when to reach for it. - [Running on a Cluster](cluster.md) — taking your analysis to a SLURM HPC system, including Perlmutter-specific notes. - [Troubleshooting](troubleshooting.md) — common issues and how to @@ -28,22 +27,24 @@ implementation; **you stay in charge of the scientific choices**. ## What you'll do, in three lines !!! tip "Quick start" + === "uv" ```bash uv tool install lightcone-cli lc init my-analysis && cd my-analysis - claude # then, inside Claude Code: /lc-new + claude + # then, inside Claude Code, run /lc-new ``` === "pip" ```bash pip install lightcone-cli lc init my-analysis && cd my-analysis - claude # then, inside Claude Code: /lc-new + claude + # then, inside Claude Code: /lc-new ``` -That's the shortest possible path. The rest of the guide is the -unhurried version. +That's the shortest possible path. The rest of the guide is the unhurried version. ## What lightcone-cli is *not* @@ -57,3 +58,5 @@ unhurried version. If you'd rather skim the design and architecture, the [maintainer docs](../index.md) are the other half of this site. + +[astra]: https://astra-spec.org/latest/ From cf5207406e5464f9b50715a93fd3c16dd836fd32 Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 15:49:28 +0200 Subject: [PATCH 5/9] Remove line break --- docs/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index ba4d8d7..3a5850b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -42,8 +42,7 @@ of materialized outputs. - __astra-tools__ - The SDK for working with [**ASTRA**][astra] analysis specifications. - This library provides the `astra` CLI which handles the [**ASTRA**][astra] lifecycle and validation process (schema, prior insights & findings, evidence verification helpers). + The SDK for working with [**ASTRA**][astra] analysis specifications. This library provides the `astra` CLI which handles the [**ASTRA**][astra] lifecycle and validation process (schema, prior insights & findings, evidence verification helpers). [:fontawesome-brands-github: Repository][astra-tools]{ .md-button } From 334cc9fb0262c6d09104265ad6896fd1975baf18 Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 15:49:45 +0200 Subject: [PATCH 6/9] Do not expand full nav tree --- zensical.toml | 1 - 1 file changed, 1 deletion(-) diff --git a/zensical.toml b/zensical.toml index d7d178c..3b24e08 100644 --- a/zensical.toml +++ b/zensical.toml @@ -71,7 +71,6 @@ favicon = "assets/favicon.svg" features = [ "navigation.tabs", "navigation.sections", - "navigation.expand", "navigation.top", "search.highlight", "content.code.copy", From 673c1a86e7a26b4ad00436e71c31a35cb0b01c02 Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 15:54:21 +0200 Subject: [PATCH 7/9] Add some links --- docs/maintainer.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/maintainer.md b/docs/maintainer.md index d890003..d33f1ae 100644 --- a/docs/maintainer.md +++ b/docs/maintainer.md @@ -1 +1,9 @@ # Developer corner + +## Where to read next + +- [Architecture](architecture.md) — the full execution and integrity story +- [CLI Reference](cli/index.md) — every command currently shipped +- [Python API](api/index.md) — the engine modules +- [Skills](skills/index.md) — what each `/lc-*` skill does (including the `/lc-from-*` family) +- [Contributing](contributing/setup.md) — getting the dev loop running From 6d0f9c9c216f3dfe5b3a879eaaad0994fd019755 Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 16:05:25 +0200 Subject: [PATCH 8/9] Fix link --- docs/user/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user/index.md b/docs/user/index.md index dccbb0f..5d7a64e 100644 --- a/docs/user/index.md +++ b/docs/user/index.md @@ -57,6 +57,6 @@ That's the shortest possible path. The rest of the guide is the unhurried versio inside the agent harness (Claude Code for now). If you'd rather skim the design and architecture, the -[maintainer docs](../index.md) are the other half of this site. +[maintainer docs](../maintainer.md) are the other half of this site. [astra]: https://astra-spec.org/latest/ From b3a172ad2271b73109db5e185adcf428f4c394bf Mon Sep 17 00:00:00 2001 From: Alexandre Boucaud Date: Thu, 14 May 2026 16:06:36 +0200 Subject: [PATCH 9/9] Add maintainer landing page --- docs/maintainer.md | 51 ++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/docs/maintainer.md b/docs/maintainer.md index d33f1ae..d7671c1 100644 --- a/docs/maintainer.md +++ b/docs/maintainer.md @@ -1,9 +1,48 @@ # Developer corner -## Where to read next +`lightcone-cli` is a thin shim over Snakemake that owns provenance. This guide +covers everything below the user surface: how the execution and integrity layers +work, what each engine module does, how the Claude Code plugin is structured, and +how to get a working dev loop. -- [Architecture](architecture.md) — the full execution and integrity story -- [CLI Reference](cli/index.md) — every command currently shipped -- [Python API](api/index.md) — the engine modules -- [Skills](skills/index.md) — what each `/lc-*` skill does (including the `/lc-from-*` family) -- [Contributing](contributing/setup.md) — getting the dev loop running +If you're looking for the user-facing docs, the +[user guide](user/index.md) is the other half of this site. + +## What this covers + +- [Architecture](architecture.md) — the three subsystems (Snakefile generation, + manifest layer, cluster management) and the invariants that hold them together. +- [CLI Reference](cli/index.md) — every `lc` command: flags, options, and the + exact Snakemake invocation each one triggers. +- [Python API](api/index.md) — the `lightcone.engine.*` modules: public + signatures, common entry points, and module responsibilities. +- [Skills](skills/index.md) — what each `/lc-*` Claude Code skill does, + including the full `/lc-from-paper` reproduction bundle. +- [HPC & SLURM](hpc/index.md) — how the Dask cluster manager adapts to local, + SLURM, and external schedulers. +- [Contributing](contributing/setup.md) — clone, install, run the test suite, + lint, and build the docs locally. + +## Get started in three commands + +!!! tip "Dev loop" + + ```bash + git clone https://github.com/LightconeResearch/lightcone-cli.git + cd lightcone-cli + just install # uv sync --all-groups + just test # pytest + ``` + + Run `just` with no arguments to see all available recipes. + +## What lightcone-cli *owns* + +The codebase is intentionally small. Snakemake handles DAG construction, +parallelism, cluster submission, staleness detection, locking, and log capture — +we do not replicate any of that. The parts that are ours: + +- **Snakefile generator** — translates `astra.yaml` into `.lightcone/Snakefile`. +- **Manifest layer** — writes and verifies `.lightcone-manifest.json` per output. +- **Cluster manager** — picks local / SLURM / external Dask shape at runtime. +- **Claude Code plugin** — skills, hooks, and agents bundled into the wheel.