Write the stack section: quick start, overview, ASTRA, comparisons

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;
 }

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 (
+    <figure className="not-prose my-6">
+      <div className="flex flex-col gap-2">
+        {layers.map((layer) => (
+          <Link
+            key={layer.name}
+            href={layer.href}
+            className="grid gap-x-4 gap-y-0.5 rounded-lg border border-l-[3px] bg-fd-card px-4 py-3 transition-colors hover:bg-fd-accent sm:grid-cols-[9rem_1fr]"
+            style={{
+              borderLeftColor: layer.color,
+              background: layer.base
+                ? `color-mix(in srgb, ${layer.color} 10%, var(--color-fd-card))`
+                : undefined,
+            }}
+          >
+            <span className="font-medium text-fd-foreground">
+              {layer.name}
+              <span className="block text-xs text-fd-muted-foreground">{layer.role}</span>
+            </span>
+            <span className="text-sm text-fd-muted-foreground">{layer.text}</span>
+          </Link>
+        ))}
+      </div>
+      <figcaption className="mt-3 text-sm text-fd-muted-foreground">
+        Everything builds on ASTRA: the layers above read from and write to the analysis&apos;s
+        single source of truth.
+      </figcaption>
+    </figure>
+  );
+}

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/<universe>/<output>.<format>`, 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.

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.