diff --git a/docs/index.md b/docs/index.md
index f2d6400..3a5850b 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,82 +1,54 @@
# 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 site has two halves.
+## Choose your path to the documentation
-## 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 it out__ – :lucide-rocket:
-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
- ```
+ Installation instructions, step-by-step tutorial, and fast tour of the lightcone framework and its agentic and workflow capabilities.
-=== "pip"
- ```bash
- pip install lightcone-cli
- lc init my-analysis && cd my-analysis
- claude # then, inside Claude Code: /lc-new
- ```
+ [User Guide](user/index.md){ .md-button .md-button--primary }
-## I work on 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.
+
+ [Developer corner](maintainer.md){ .md-button .md-button--primary }
-## Two packages, one toolchain
+
+
+---
-| 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. |
+## Two libraries, one toolchain
-`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
+- __lightcone-cli__
-A sidecar `.lightcone-manifest.json` next to its data, recording:
+ 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.
-- `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`
+ [:fontawesome-brands-github: Repository][cli]{ .md-button }
-`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__
-## Development setup
+ 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).
-```bash
-just install # uv sync --all-groups
-just test # uv run pytest
-just lint # ruff + mypy
-just docs-serve # live docs preview
-```
+ [:fontawesome-brands-github: Repository][astra-tools]{ .md-button }
-## 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
+[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
diff --git a/docs/maintainer.md b/docs/maintainer.md
new file mode 100644
index 0000000..d7671c1
--- /dev/null
+++ b/docs/maintainer.md
@@ -0,0 +1,48 @@
+# Developer corner
+
+`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.
+
+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.
diff --git a/docs/user/index.md b/docs/user/index.md
index 0f56a41..5d7a64e 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*
@@ -56,4 +57,6 @@ unhurried version.
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/
diff --git a/zensical.toml b/zensical.toml
index 84f5020..3b24e08 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]
@@ -69,7 +71,6 @@ favicon = "assets/favicon.svg"
features = [
"navigation.tabs",
"navigation.sections",
- "navigation.expand",
"navigation.top",
"search.highlight",
"content.code.copy",