Docs rewrite 1/5: README, landing page, install, getting started

README.md

@@ -5,22 +5,33 @@
 [![PyPI](https://img.shields.io/pypi/v/lightcone-cli?style=flat&color=f8f7f3)](https://pypi.org/project/lightcone-cli/)
 [![Tests](https://img.shields.io/github/actions/workflow/status/LightconeResearch/lightcone-cli/tests.yml?style=flat&color=darkgreen)](https://github.com/LightconeResearch/lightcone-cli/actions/workflows/tests.yml)
 
-<!-- [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) -->
-
 **lightcone-cli** (`lc`) is the execution layer for
 [ASTRA](https://astra-spec.org/latest/) (Agentic Schema for Transparent
 Research Analysis). Describe your analysis in an `astra.yaml`
-specification and `lc` takes care of the rest — execution and
-provenance.
+specification and `lc` takes care of the rest — execution, environments,
+and provenance.
 
 ## Quick Start
 
+**lightcone-cli** only requires you to have `uv` installed on your environment, and will take care of everything else. See how to install uv here: [https://docs.astral.sh/uv/getting-started/installation](https://docs.astral.sh/uv/getting-started/installation). 
+
+Then to install **lightcone-cli**:
+```bash
+uv tool install lightcone-cli
+```
+
+Once the CLI is installed, you can use it to create an ASTRA project and generate outputs like so:
+
 ```bash
-uv tool install lightcone-cli   # or: pip install lightcone-cli
 lc init my-analysis
 cd my-analysis
-# describe your analysis in astra.yaml, then:
-lc run
+# describe your analysis in astra.yaml, write your scripts,
+# declare what they import through normal uv interactions:
+uv add numpy
+# When you are done with your edits, commit:
+git add -A && git commit -m "First analysis"
+# Use the lightcone CLI to generate your outputs with full provenance tracking
+lc materialize
 ```
 
 ASTRA specs are plain, structured YAML — they work well hand-written or
@@ -30,10 +41,11 @@ drafted with any AI coding assistant.
 
 ## Capabilities
 
-- **Multiverse analysis** — define methodological decisions with multiple options; `lc` runs your analysis across all defensible paths automatically
-- **Provenance integrity** — every output gets a content-addressed manifest; `lc verify` detects tampering or broken chains
-- **HPC-ready execution** — Snakemake-backed DAG dispatch with SLURM and container support (Docker, Podman, Apptainer) out of the box
-- **Reproducible publishing** — `lc export wrroc` emits a [Workflow Run RO-Crate](https://www.researchobject.org/workflow-run-crate/) bundle ready for Zenodo or WorkflowHub
+- **Multiverse analysis** — declare methodological decisions with multiple defensible options; `lc` materializes your analysis across every universe you define
+- **Provenance by construction** — every output is committed to git together with a content-addressed manifest and a re-runnable run record; git-annex carries the bytes, so results travel with the repository
+- **Locked, isolated execution** — a project's environment is `pyproject.toml` + `uv.lock`; recipes run in it under a sandbox (Landlock on Linux, Seatbelt on macOS) that keeps undeclared files out and stray writes contained
+- **Containers and HPC** — declare `[tool.lightcone.image]` and recipes run in a content-addressed image archived in the repository itself; a SLURM allocation is detected and used automatically, every node included
+- **Publication view** — declare a license and `lc materialize` maintains an [RO-Crate](https://www.researchobject.org/ro-crate/) of the project and its provenance, ready to archive or deposit
 
 → [Full documentation](https://docs.lightconeresearch.org)
 

docs/index.md

@@ -6,7 +6,7 @@ It serves as the machinery that ties an analysis `astra.yaml` specification to a
 of materialized outputs.
 
 !!! warning "Alpha development"
-    lightcone-cli is in **early alpha**. The CLI, skills, and execution layer are all
+    lightcone-cli is in **early alpha**. The CLI and the execution layer are
     still moving — expect breaking changes between minor versions. Bug reports, design
     challenges, and use cases the tooling doesn't yet cover are exactly what we want to
     hear at this stage; please open an issue on the
@@ -43,7 +43,7 @@ of materialized outputs.
 
 -   __lightcone-cli__
 
-    The library that ships the `lc` CLI: the workflow execution layer and the provenance integrity layer. Depends on [**astra-tools**][astra-tools], the SDK for working with ASTRA analysis specifications.
+    The library that ships the `lc` CLI: project scaffolding, locked environments, sandboxed execution, and the provenance layer. Depends on [**astra-tools**][astra-tools], the SDK for working with ASTRA analysis specifications.
 
     [:fontawesome-brands-github: Repository][cli]{ .md-button }