diff --git a/components/mdx.tsx b/components/mdx.tsx
index a640575..8f3d8de 100644
--- a/components/mdx.tsx
+++ b/components/mdx.tsx
@@ -1,9 +1,17 @@
import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { Step, Steps } from 'fumadocs-ui/components/steps';
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
import type { MDXComponents } from 'mdx/types';
+import { StackLayers } from '@/components/stack-layers';
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultMdxComponents,
+ Step,
+ Steps,
+ Tab,
+ Tabs,
+ StackLayers,
...components,
} satisfies MDXComponents;
}
diff --git a/components/stack-layers.tsx b/components/stack-layers.tsx
new file mode 100644
index 0000000..3a1ec7c
--- /dev/null
+++ b/components/stack-layers.tsx
@@ -0,0 +1,75 @@
+import Link from 'fumadocs-core/link';
+
+// The layers of the stack, drawn with the brand's colours so the diagram
+// follows the light and dark schemes. ASTRA is the foundation the others
+// read from and write to.
+const layers = [
+ {
+ name: 'Agent Skills',
+ role: 'Work with your agent',
+ text: 'Teach Claude Code or Codex to scope, build, run and report on the analysis with you.',
+ href: '/agent-skills',
+ color: 'var(--lc-color-slate-blue)',
+ },
+ {
+ name: 'Lightcone Lab',
+ role: 'Explore',
+ text: 'A JupyterLab workbench for the project: its inventory, pipeline, provenance and report.',
+ href: '/lightcone-lab',
+ color: 'var(--lc-color-vert-de-gris)',
+ },
+ {
+ name: 'MySTRA',
+ role: 'Communicate',
+ text: 'A report that references the analysis by path, so it stays in step with it.',
+ href: '/mystra',
+ color: 'var(--lc-color-wax-red)',
+ },
+ {
+ name: 'Lightcone CLI',
+ role: 'Execute',
+ text: 'Runs every recipe in a sandbox and records the provenance of every output.',
+ href: '/lightcone-cli',
+ color: 'var(--lc-color-blue-ink)',
+ },
+ {
+ name: 'ASTRA',
+ role: 'Describe',
+ text: 'The specification: the inputs, outputs, decisions and evidence of the analysis, in astra.yaml.',
+ href: '/astra',
+ color: 'var(--lc-color-antique-gold)',
+ base: true,
+ },
+];
+
+export function StackLayers() {
+ return (
+
+
+ {layers.map((layer) => (
+
+ {layer.name}
+ {layer.role}
+
+ {layer.text}
+
+ ))}
+
+
+ Everything builds on ASTRA: the layers above read from and write to the analysis's
+ single source of truth.
+
+
+ );
+}
diff --git a/content/docs/(stack)/astra.mdx b/content/docs/(stack)/astra.mdx
new file mode 100644
index 0000000..c06366e
--- /dev/null
+++ b/content/docs/(stack)/astra.mdx
@@ -0,0 +1,123 @@
+---
+title: ASTRA
+description: The open specification every Lightcone project is written in.
+---
+
+ASTRA, the Agentic Schema for Transparent Research Analysis, is an open specification for describing
+a research analysis in a YAML file, `astra.yaml`. Code captures how an analysis runs, but not its
+structure: `astra.yaml` records its inputs, outputs, methodological choices and evidence, so that the
+work is easier to review, reproduce and extend.
+
+ASTRA doesn't depend on any tool: agents, workflow runners and people can all read the same file.
+It has its own documentation, schema and releases at [astra-spec.org](https://astra-spec.org/latest/);
+this page covers what you need to know to use it with the Lightcone Stack.
+
+## What an analysis records
+
+| Element | What you record |
+| -------------- | ------------------------------------------------------------------------ |
+| Inputs | The datasets, files and upstream analyses you use |
+| Outputs | The metrics, figures, tables and other artifacts you intend to produce |
+| Recipes | The command that produces each output from its declared inputs and choices |
+| Decisions | Methodological choices, their alternatives, and the reasons for them |
+| Universes | A selection of one option per decision, to run together |
+| Prior insights | Existing knowledge, with its evidence, that informs the approach |
+| Findings | Claims supported by the analysis's outputs |
+
+## Decisions and universes
+
+Results depend on choices: which data to include, how to treat outliers, which prior to assume. In
+ordinary research code those choices are scattered across scripts, notebooks and memory. ASTRA gives
+each one an explicit place: a **decision** names the options that were considered and why one might
+choose each.
+
+```yaml title="astra.yaml (excerpt)"
+outputs:
+ - id: fit_params
+ type: table
+ format: csv
+ description: Slope, intercept and scatter for the fitted relation.
+ inputs: [catalog_data]
+ decisions: [fit_method]
+ recipe:
+ command: >-
+ python src/fit_period_luminosity.py
+ --catalog {inputs.catalog_data}
+ --method {decisions.fit_method}
+ --out {output}
+
+decisions:
+ fit_method:
+ label: Fitting method
+ rationale: The fitting method determines how outliers influence the inferred relation.
+ default: ordinary_least_squares
+ options:
+ ordinary_least_squares:
+ label: Ordinary least squares
+ robust_linear:
+ label: Robust linear fit
+```
+
+Picking one option per decision gives a **universe**, a single runnable configuration. A universe is
+just a small YAML file:
+
+```yaml title="universes/baseline.yaml"
+id: baseline
+description: Default configuration for the period-luminosity fit.
+
+decisions:
+ fit_method: ordinary_least_squares
+```
+
+The set of all universes is the analysis's **multiverse**. Running several of them shows whether a
+result holds when you change a method, a model or a prior.
+
+## Evidence
+
+Knowledge comes into an analysis as **prior insights** and goes out as **findings**. Both carry
+their evidence: for a published result, the paper's identifier and the exact quote it rests on.
+ASTRA's tools fetch the paper and check that the quote is really there, so a citation can't be
+invented.
+
+## How the stack uses it
+
+- **[Agent Skills](/agent-skills)**: the `astra` skill teaches your agent the format, so it writes and
+ revises `astra.yaml` with you. A hook validates the file each time the agent saves it.
+- **[Lightcone CLI](/lightcone-cli)**: `lc` executes the recipes. Each output that `lc` runs needs a
+ `format`, a `recipe`, and its `inputs` and `decisions` declared; its file lands at
+ `results//.`, next to a manifest that records how it was made.
+- **[MySTRA](/mystra)**: the report refers to outputs, decisions and values by their path in
+ `astra.yaml`, rather than copying them.
+- **[Lightcone Lab](/lightcone-lab)**: the workbench shows the analysis as an inventory and a
+ pipeline.
+
+Keep the `version:` field that `lc init` writes: it is the version of the ASTRA schema, separate from
+the version of any tool.
+
+## The `astra` command
+
+[astra-tools](https://github.com/LightconeResearch/astra-tools) provides the `astra` command, which
+validates and inspects a specification. You don't need to install it: `uvx` fetches it on first use.
+Run it from your project directory, with the version the current Lightcone CLI expects:
+
+```bash
+uvx astra-tools@0.2.18 validate
+uvx astra-tools@0.2.18 info
+```
+
+With no file name, `validate` checks the project's specification and universe files. Add
+`--verify-evidence` to check quotes against their sources:
+
+```bash
+uvx astra-tools@0.2.18 validate astra.yaml --verify-evidence
+```
+
+The agent plugin runs the same command with its own pinned version, so you only need it to check
+things yourself.
+
+## Learn more
+
+- [Getting started with ASTRA](https://astra-spec.org/latest/getting-started/): the format on its
+ own, without Lightcone.
+- [Specification reference](https://astra-spec.org/latest/specification/): every element and field.
+- [CLI reference](https://astra-spec.org/latest/cli/): validation, universes, and paper tools.
diff --git a/content/docs/(stack)/comparisons.mdx b/content/docs/(stack)/comparisons.mdx
new file mode 100644
index 0000000..d6c463b
--- /dev/null
+++ b/content/docs/(stack)/comparisons.mdx
@@ -0,0 +1,73 @@
+---
+title: Comparisons
+description: How the Lightcone Stack relates to other tools for AI-assisted research.
+---
+
+Many tools now help researchers work with AI agents. What sets the Lightcone Stack apart is the
+record it keeps: the analysis is declared in an open specification before anything runs, its choices
+and their alternatives are explicit, and every result is traced back to them in files you own. This
+page compares it with the tools you are most likely to weigh it against. It was last reviewed in
+September 2026; the other tools move quickly, so check their own documentation too.
+
+## Claude Science
+
+[Claude Science](https://www.anthropic.com/news/claude-science-ai-workbench) is Anthropic's desktop
+"AI workbench for scientists", in beta since June 2026. Claude writes and runs Python, R or shell code
+in a sandbox on your machine, can send jobs to remote servers, draws on data sources through
+connectors, and saves versioned artifacts. Each saved artifact keeps the
+[code, execution log and environment](https://claude.com/docs/claude-science/artifacts) that produced
+it, and a reviewer agent checks claims against what actually ran.
+
+It is a polished, well-supported application, and it already records a great deal. The difference
+lies in what the record is and who owns it:
+
+| | Claude Science | Lightcone Stack |
+| -------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| **The analysis** | Reconstructed from what the agent did: code, logs and environment | Declared up front in `astra.yaml`: inputs, outputs, decisions, evidence |
+| **Analysis choices** | Fork a session to compare approaches | Named decisions with their alternatives, run side by side as universes |
+| **Evidence** | A reviewer agent checks claims and citations against what ran | Quotes recorded in the specification and checked against the source paper |
+| **Where the record lives** | The app's data folder, on one computer | A git repository, with data and results in git-annex |
+| **Sharing** | Manuscripts, figures and code exports | An RO-Crate, and a MySTRA report tied to the analysis |
+| **Agents and models** | Claude, in the Claude Science app, on a paid Claude plan | Claude Code or Codex |
+| **Compute** | Local, remote Linux servers, Slurm, and cloud GPUs through Modal | Local, or Slurm clusters |
+| **Openness** | Proprietary | Open source (BSD 3-Clause), open specification |
+
+Where Claude Science is ahead: a graphical interface with built-in viewers (for example for protein
+structures and genome tracks), more than sixty connectors and skills with a strong life-sciences
+focus, cloud GPUs, and Anthropic's support.
+
+Where the Lightcone Stack is ahead:
+
+- **The analysis is declared, not reconstructed.** The specification is written, with you, before
+ anything runs; it states the intent, not only the steps that happened to run.
+- **Choices are first-class.** A decision records the alternatives and the reasons, and the multiverse
+ shows whether a result survives changing them.
+- **Claims carry checkable evidence.** Findings and prior insights cite the exact text they rest on,
+ and the tools verify it against the source.
+- **The record is open and portable.** It lives in a repository you own, in open formats that other
+ tools and other agents can read, without any particular application.
+
+The two can also work together: the Lightcone Stack runs inside Claude Code, so you can keep using
+Claude while keeping your analysis in an open, portable record.
+
+## Workflow managers
+
+[Snakemake](https://snakemake.readthedocs.io/), [Nextflow](https://www.nextflow.io/) and
+[DVC](https://dvc.org/) are mature tools for running pipelines and versioning data. The Lightcone CLI
+covers similar ground (running recipes, tracking what is up to date, recording provenance), but its
+input is the scientific structure of the analysis: the decisions and their alternatives, the evidence
+and the findings. And it is built to be driven by an agent: it never prompts, and it reports in JSON.
+
+## Notebooks
+
+Jupyter notebooks are the most common way to explore data interactively, but their hidden state and
+their mix of code, output and prose make an analysis hard to re-run or review.
+[Lightcone Lab](/lightcone-lab) keeps what is good about JupyterLab and adds the project around it:
+the inventory, the pipeline and the provenance of each result.
+
+## Autonomous research agents
+
+Systems such as [Kosmos](https://labs.edisonscientific.com/research/announcing-kosmos/) carry out
+research end to end and hand back a report. The Lightcone Stack takes the opposite approach: the
+agent does the work, but you make the scientific choices, and the specification records them where
+you and your readers can see them.
diff --git a/content/docs/(stack)/guides/first-analysis.mdx b/content/docs/(stack)/guides/first-analysis.mdx
new file mode 100644
index 0000000..5e90a41
--- /dev/null
+++ b/content/docs/(stack)/guides/first-analysis.mdx
@@ -0,0 +1,208 @@
+---
+title: Your first analysis
+description: A complete analysis with an agent, from a research question to a report.
+---
+
+This guide works through a classic cosmology problem with your agent: using the brightness and
+redshifts of supernovae to estimate the dark energy content of the universe. We fit the standard ΛCDM
+model of cosmology to 580 Type Ia supernovae from
+[Suzuki et al. 2012](https://arxiv.org/abs/1105.3470). Mechanically, it is a least-squares fit with a
+single free parameter, ΩΛ , which runs in seconds on a laptop.
+
+You need the stack installed, as in the [Quick Start](/): uv, git, the Lightcone CLI and the
+`lightcone` plugin.
+
+
+ Everything in a `text` block is a prompt: paste it into your agent, not into your shell. Shell
+ commands appear only where you are meant to look at something yourself. Your agent's answers will
+ vary in the details; what matters is what ends up in the project.
+
+
+## 1. Start the project
+
+Make a directory and start your agent in it:
+
+```bash
+mkdir sn-cosmology && cd sn-cosmology
+claude # or: codex
+```
+
+Then describe the analysis:
+
+```text
+I want to start a new analysis. I'd like to fit a flat LCDM model to the Union2.1
+supernova compilation to recover Omega_Lambda, varying only Omega_Lambda and using
+the calibration given in the data file's header. The data is here:
+
+ https://supernova.lbl.gov/Union/figures/SCPUnion2.1_mu_vs_z.txt
+
+I want two outputs: the best fit, and a Hubble diagram figure with an absolute panel
+and a residuals panel.
+```
+
+The agent opens with a short interview about the question and the structure of the analysis; answer
+its questions. It sets up the project with `lc init`, then writes the analysis down in `astra.yaml`
+and shows you a summary. A hook validates the file each time it is saved. You should see something
+like this:
+
+```yaml title="astra.yaml (excerpt)"
+inputs:
+ - id: union21
+ type: data
+ source: data/SCPUnion2.1_mu_vs_z.txt
+ description: >
+ Union2.1 SN Ia compilation: 580 supernovae from z = 0.015 to 1.414. The distance
+ moduli assume h = 0.7, as given in the file's header.
+
+outputs:
+ - id: best_fit
+ type: metric
+ format: json
+ description: Best-fit Omega_Lambda with its uncertainty, chi-squared and degrees of freedom.
+ inputs: [union21]
+ recipe:
+ command: python src/fit.py --data {inputs.union21} --out {output}
+
+ - id: hubble_diagram
+ type: figure
+ format: png
+ description: Distance modulus with the best-fit curve, and residuals below it.
+ inputs: [union21, best_fit]
+ recipe:
+ command: >
+ python src/plot_hubble.py --data {inputs.union21}
+ --fit {inputs.best_fit} --out {output}
+```
+
+Nothing has run yet: this is the plan, and it is yours to question before any code exists.
+
+## 2. Produce the results
+
+```text
+Download the data file into data/. Then implement the analysis: write the scripts
+the recipes call, produce both outputs, and show me the Hubble diagram.
+```
+
+The agent starts a compute allocation on your machine, adds the packages it needs to the project's
+environment, and writes the scripts, trying them in the same sandbox the recipes run in. It commits
+its changes, then asks `lc` to produce the outputs. `lc` runs each recipe and commits each result,
+with a record of how it was made. You can look for yourself:
+
+```bash
+lc status
+ls results/baseline
+```
+
+Each output is a file in `results/baseline/`, named after its `id`, next to a manifest that records
+the recipe, the decisions, the code version and the hashes of everything that went in. One number
+comes back: **ΩΛ = 0.722 ± 0.013**.
+
+
+
+## 3. Check it against the paper
+
+Is this consistent with the original paper? Check it by quoting the paper, and let the tools verify
+the quote:
+
+```text
+The paper that published this catalogue is Suzuki et al. 2012, arXiv 1105.3470.
+Cache the paper, find their own Omega_Lambda from these supernovae, and verify the
+quote. Then record it in astra.yaml as a prior insight with the quote as evidence,
+and tell me how our constraint compares to theirs.
+```
+
+The agent finds the sentence in the paper and records it, with its location, as evidence:
+
+```yaml title="astra.yaml (excerpt)"
+prior_insights:
+ suzuki_2012_result:
+ label: "Union2.1's own dark-energy constraint"
+ claim: >
+ Suzuki et al. (2012) constrain the dark energy density from these supernovae alone,
+ in a flat universe, to Omega_Lambda = 0.705 (+0.040, -0.043) including systematic errors.
+ evidence:
+ - id: suzuki_2012_sne_alone_flat_lcdm
+ doi: "10.48550/arXiv.1105.3470"
+ quote:
+ exact: "In a flat Universe, SNe Ia alone constrain the dark-energy density, ΩΛ, to be ΩΛ = 0.705+0.040−0.043 including systematics"
+ location:
+ value: "page=17"
+```
+
+To run the check yourself:
+
+```bash
+uvx astra-tools@0.2.18 validate astra.yaml --verify-evidence
+```
+
+```text
+✓ Schema validation passed
+✓ Semantic validation passed
+
+Verifying evidence...
+✓ Evidence (prior_insights): 1/1 verified
+```
+
+The central values agree, but look at the error bars.
+
+## 4. Add a decision
+
+Ours are three times tighter: 0.722 ± 0.013 against their 0.705 ± 0.04, on the same 580 supernovae.
+Find out why:
+
+```text
+Let's understand why our error bars are so much tighter than theirs. The Union2.1
+covariance matrices are here:
+
+ https://supernova.lbl.gov/Union/figures/SCPUnion2.1_covmat_nosys.txt
+ https://supernova.lbl.gov/Union/figures/SCPUnion2.1_covmat_sys.txt
+
+Work out which one the main data file's error column corresponds to. Then add a
+decision to astra.yaml for which covariance to use, with a universe for each option,
+and produce the results in both.
+```
+
+The error column matches the covariance without systematics: the fit has been statistical only. The
+agent records that as a decision with two options, adds a universe for the new one, and asks `lc` for
+the results. `lc` reuses the outputs that are still up to date and runs only what the new universe
+needs:
+
+```bash
+lc status
+```
+
+| Result | ΩΛ |
+| --------------------------------------- | ---------------------- |
+| Ours, statistical only | 0.722 ± 0.013 |
+| Ours, statistical and systematic | **0.714 ± 0.030** |
+| Suzuki et al. 2012, published | 0.705 (+0.040, −0.043) |
+
+The value barely moves; the uncertainty more than doubles, and only then is it comparable with the
+paper's, which includes systematics too. A comparison of best-fit values alone would have ranked this
+decision as nearly irrelevant. It is the difference between a number that resembles theirs and a
+number you can put beside theirs.
+
+## 5. Write it up
+
+```text
+Write up the result in the report. Reference the outputs, the covariance decision and
+the paper's value from astra.yaml instead of copying numbers, and show me a preview.
+```
+
+The report is `index.md`, written in MyST Markdown. With [MySTRA](/mystra), it cites outputs,
+decisions and values by their path in `astra.yaml`, so when the analysis is re-run, the report
+follows. Previewing it needs Node.js and MyST; your agent asks before installing them.
+
+## Going further
+
+When you're done, ask your agent to release the compute allocation it started. Three more decisions
+are waiting in this analysis:
+
+- **The optimiser**: likely a null result, and worth recording as one.
+- **The redshift range**: the high-redshift supernovae give the longest lever arm, and the worst
+ systematics.
+- **The dark energy model**: assume w = −1, or fit it, at the cost of a strong degeneracy with
+ ΩΛ .
+
+Each is one more option, one more recipe argument, and one more reason written down. To explore the
+project in JupyterLab, add [Lightcone Lab](/lightcone-lab).
diff --git a/content/docs/(stack)/guides/hubble_two_panel.png b/content/docs/(stack)/guides/hubble_two_panel.png
new file mode 100644
index 0000000..5af6fe0
Binary files /dev/null and b/content/docs/(stack)/guides/hubble_two_panel.png differ
diff --git a/content/docs/(stack)/guides/meta.json b/content/docs/(stack)/guides/meta.json
new file mode 100644
index 0000000..4796799
--- /dev/null
+++ b/content/docs/(stack)/guides/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Guides",
+ "defaultOpen": true,
+ "pages": ["first-analysis"]
+}
diff --git a/content/docs/(stack)/index.mdx b/content/docs/(stack)/index.mdx
index 9df0783..6ffb510 100644
--- a/content/docs/(stack)/index.mdx
+++ b/content/docs/(stack)/index.mdx
@@ -1,38 +1,161 @@
---
-title: Introduction
-description: From research question to reproducible result.
+title: Quick Start
+description: Start a reproducible research analysis with your coding agent.
---
import { Bot, FlaskConical, PenLine, Terminal } from 'lucide-react';
-The Lightcone Research Stack is Lightcone Research's tooling for research analyses described
-with [ASTRA](https://astra-spec.org/latest/). You describe an analysis in an `astra.yaml`
-specification; the stack runs it, keeps every result tied to the choices that produced it, and
-carries it through to a written report.
+The Lightcone Research Stack is a set of open-source tools for research you can inspect, reproduce
+and build on. You work through your coding agent: it interviews you about your question, writes the
+analysis down as an [ASTRA](/astra) specification, and runs it with the Lightcone CLI, which records
+how every result was produced. The scientific choices stay yours.
-
- This site is being reorganised around the whole stack. A quickstart and guides are on their way;
- until then, each component's section links to its current documentation.
+
+
+
+
+ Read [What is the Lightcone Stack](/what-is-lightcone) for the ideas behind it.
-## Components
+## Install
+
+You need Linux or macOS (on Windows, use WSL) and a coding agent: Claude Code or Codex.
+[Installation](/installation) covers each step in more detail.
+
+
+
+
+### Install uv and git
+
+[uv](https://docs.astral.sh/uv/) installs everything else, Python included:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+git comes with macOS; on Linux, install it with your package manager. Every result is committed,
+so git needs to know who you are:
+
+```bash
+git config --global user.name "Ada Lovelace"
+git config --global user.email "ada@example.org"
+```
+
+
+
+
+### Install the Lightcone CLI
+
+```bash
+uv tool install lightcone-cli==0.5.0rc5
+```
+
+Keep the exact version: while the current release is a pre-release, a plain
+`uv tool install lightcone-cli` installs an older one.
+
+
+
+
+### Add the plugin to your agent
+
+Register the Lightcone marketplace, then install the `lightcone` plugin. It includes the `astra`
+plugin, so there is nothing else to add.
-Choose a component from the selector at the top of the sidebar, or start here:
+
+
+
+```bash
+claude plugin marketplace add LightconeResearch/agent-skills
+claude plugin install lightcone@lightcone-research
+```
+
+
+
+
+```bash
+codex plugin marketplace add LightconeResearch/agent-skills
+codex plugin add lightcone@lightcone-research
+```
+
+
+
+
+Open **Customize → Plugins → Add → Add marketplace → Add from repo** and paste
+`https://github.com/LightconeResearch/agent-skills`. Then choose **lightcone** from the
+`lightcone-research` marketplace.
+
+
+
+
+Open **Plugins** from the arrow beside **Create** and add the `LightconeResearch/agent-skills`
+marketplace. Then search for **lightcone** and install it.
+
+
+
+
+
+
+
+## Start your first analysis
+
+Make a directory for the project and start your agent in it:
+
+```bash
+mkdir my-analysis && cd my-analysis
+claude # or: codex
+```
+
+Then tell it what you want to find out:
+
+```text
+I want to start a new analysis:
+```
+
+You can also call the skill by name: `/lightcone:lightcone` in Claude, `$lightcone:lightcone` in
+Codex. From there, the agent:
+
+1. **Interviews you** about the research question and the structure of the analysis, before it
+ writes any code.
+2. **Sets up the project** with `lc init`: the specification (`astra.yaml`), a uv environment, a git
+ repository whose data and results are stored with git-annex, and a MyST report.
+3. **Writes the analysis down** in `astra.yaml` (its inputs, outputs, decisions and evidence), which
+ is validated each time it is saved, and shows you a summary.
+4. **Implements and runs it** once you agree, with the Lightcone CLI: each step runs in a sandbox, and
+ each output is committed with a record of how it was made.
+
+For a worked example, follow [Your first analysis](/guides/first-analysis).
+
+## Optional: Lightcone Lab
+
+If you work in JupyterLab, [Lightcone Lab](/lightcone-lab) adds a workbench for your project: its
+inventory, its pipeline, the provenance of each result, and the report. See
+[Installation](/installation#lightcone-lab) to add it.
+
+## Learn more
-
+ Why the stack exists, and how its pieces fit together.
-
+ The specification every Lightcone project is written in.
-
+ How the stack relates to other tools for AI-assisted research.
-
+ A complete analysis with an agent, from a question to a report.
-
-The ASTRA specification and the `astra` command have their own documentation at
-[astra-spec.org](https://astra-spec.org/latest/).
diff --git a/content/docs/(stack)/installation.mdx b/content/docs/(stack)/installation.mdx
new file mode 100644
index 0000000..9746423
--- /dev/null
+++ b/content/docs/(stack)/installation.mdx
@@ -0,0 +1,159 @@
+---
+title: Installation
+description: Set up the Lightcone Stack on your machine, step by step.
+---
+
+You need two things on your machine, [uv](https://docs.astral.sh/uv/) and git, plus a coding agent:
+Claude Code or Codex, in the terminal or as a desktop app. Everything else, Python included, is
+installed by uv or ships with the Lightcone CLI.
+
+
+ Linux (glibc 2.34 or newer, x86_64 or aarch64) and macOS (14 or newer on Apple silicon, 15 or newer
+ on Intel). On Windows, use WSL.
+
+
+## 1. uv and git
+
+uv manages the Python environments of your projects, and the interpreters themselves, so there is no
+separate Python to install:
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+git comes with macOS; on Linux, install it with your package manager (`apt install git`,
+`dnf install git`, and so on).
+
+
+ uv installs into your home directory, so the same command works on clusters that don't provide it,
+ such as NERSC's Perlmutter. Make sure `~/.local/bin` is on your `PATH`.
+
+
+## 2. Tell git who you are
+
+The Lightcone CLI commits every output it makes, so git needs an identity before the first run:
+
+```bash
+git config --global user.name "Ada Lovelace"
+git config --global user.email "ada@example.org"
+```
+
+If you already commit from this machine, you're done.
+
+## 3. The Lightcone CLI
+
+The package is `lightcone-cli` on PyPI; the command it provides is `lc`. Install it with its exact
+version:
+
+```bash
+uv tool install lightcone-cli==0.5.0rc5
+lc --version
+```
+
+The version matters while the current release is a pre-release: without it, uv installs an older
+stable release that the agent plugin doesn't support. The CLI also brings git-annex, which stores the
+data and results of your projects.
+
+
+ If your shell already has an alias named `lc` (some people bind it to `ls --color`), it hides the
+ new command. Rename the alias, or run `unalias lc`.
+
+
+## 4. The agent plugin
+
+The [Agent Skills](/agent-skills) are distributed as a plugin marketplace, registered under the name
+`lightcone-research`. Add the marketplace, then the `lightcone` plugin. It includes the `astra` plugin,
+so don't install that one alongside it.
+
+
+
+
+```bash
+claude plugin marketplace add LightconeResearch/agent-skills
+claude plugin install lightcone@lightcone-research
+```
+
+In a session, call the skill with `/lightcone:lightcone`, or just describe what you want to do.
+
+
+
+
+```bash
+codex plugin marketplace add LightconeResearch/agent-skills
+codex plugin add lightcone@lightcone-research
+```
+
+In a session, call the skill with `$lightcone:lightcone`, or just describe what you want to do.
+
+
+
+
+Open **Customize → Plugins → Add → Add marketplace → Add from repo** and paste
+`https://github.com/LightconeResearch/agent-skills`. Then, in **Customize → Plugins**, choose
+**lightcone** from the `lightcone-research` marketplace.
+
+
+
+
+Open **Plugins** from the arrow beside **Create** and add the `LightconeResearch/agent-skills`
+marketplace. Then search for **lightcone** and install it.
+
+
+
+
+When a session starts, the plugin checks that `lc` is installed at a version it supports. If it
+isn't, your agent offers to run the install command from step 3; in an interactive session, it never
+installs anything without asking. The plugin runs ASTRA's own `astra` command through `uvx`, which fetches it on first
+use.
+
+## Optional extras
+
+### Container runtime
+
+Only projects that opt into containers need [Podman](https://podman.io/) or
+[Docker](https://docs.docker.com/get-docker/). Until a project does, its recipes run directly on your
+machine, in the project's own locked environment. There is nothing to configure: `lc` uses whichever
+runtime it finds.
+
+### Report preview
+
+Each project comes with a MyST report. Previewing it needs [Node.js](https://nodejs.org/) 18 or newer
+and [MyST](https://mystmd.org/); your agent asks before installing them.
+
+### Lightcone Lab
+
+[Lightcone Lab](/lightcone-lab) is a JupyterLab extension, installed into the environment that runs
+JupyterLab 4.5.10 or newer. It comes in two forms:
+
+```bash tab="Browser only"
+pip install --user jupyterlab-lightcone
+```
+
+```bash tab="With server features"
+pip install "jupyterlab-lightcone[full]"
+```
+
+The browser-only form needs `lc` on the terminal's `PATH`. The full form also installs the Lightcone
+CLI and the tools the workbench runs on the server, and needs git and uv on the server's `PATH`. See
+the [Lightcone Lab](/lightcone-lab) section for its agents and other requirements.
+
+## Updating
+
+Install the new version by name; it replaces the one you have:
+
+```bash
+uv tool install lightcone-cli==
+```
+
+`uv tool upgrade` doesn't move to a pre-release, so name the version while the release is one. An
+update never invalidates your results: the CLI's version is recorded with every output, but it
+doesn't decide whether an output is up to date, so nothing is rebuilt just because `lc` changed.
+
+## Uninstalling
+
+```bash
+uv tool uninstall lightcone-cli
+```
+
+Your projects are untouched: everything the CLI knows about an analysis lives in the project's own
+repository.
diff --git a/content/docs/(stack)/meta.json b/content/docs/(stack)/meta.json
index 0fcddf0..c356f38 100644
--- a/content/docs/(stack)/meta.json
+++ b/content/docs/(stack)/meta.json
@@ -3,5 +3,5 @@
"description": "Quickstart and guides for the whole stack",
"icon": "Layers",
"root": true,
- "pages": ["index", "---Related---", "external:[ASTRA specification](https://astra-spec.org/latest/)"]
+ "pages": ["index", "what-is-lightcone", "astra", "comparisons", "installation", "guides"]
}
diff --git a/content/docs/(stack)/what-is-lightcone.mdx b/content/docs/(stack)/what-is-lightcone.mdx
new file mode 100644
index 0000000..3057741
--- /dev/null
+++ b/content/docs/(stack)/what-is-lightcone.mdx
@@ -0,0 +1,65 @@
+---
+title: What is the Lightcone Stack
+description: Infrastructure for research that others can verify, reproduce and build on.
+---
+
+## Why it exists
+
+AI agents are making research faster: an analysis that took weeks can now take an afternoon. But a
+gap is opening between what gets produced and what can be verified. Trust is needed at every step:
+
+- when a scientist reviews what their agent has just produced;
+- when a reviewer judges an analysis they did not run themselves;
+- when someone later sets out to reproduce the work, or to build on it.
+
+Neither of the usual records answers that. **Code** is executable but opaque: it buries its
+assumptions and says nothing of intent. **A paper** is legible but lossy: the analysis cannot be
+regenerated from it. What is missing between them is the record of the decisions, assumptions,
+evidence and provenance behind each result.
+
+## What it provides
+
+The Lightcone Stack keeps that record as the work happens, so that every result is:
+
+- **Traceable.** Every figure, number and claim ties back to the data, code and decisions that
+ produced it, and can be checked without re-running the analysis.
+- **Observable.** The whole analysis is recorded, including the choices that were made and the
+ alternatives they were weighed against, not just the path that was taken.
+- **Legible.** People and agents can both read the record: what was done, why, and on what
+ evidence.
+
+Each result then becomes a solid foundation for the next: science that compounds.
+
+## How it fits together
+
+