LightconeResearch · aboucaud · May 13, 2026 · May 7, 2026 · May 7, 2026 · May 8, 2026
diff --git a/docs/cli/build.md b/docs/cli/build.md
@@ -5,7 +5,7 @@ images so `lc run` can use `--pull=never`).
 
 ## Synopsis
 
-```
+```text
 lc build [OPTIONS]
 ```
 
@@ -35,7 +35,7 @@ nothing to build.
 
 ## Tag computation
 
-```
+```text
 lc-<sanitized-project-name>-<sha256[:12]>
 ```
 

diff --git a/docs/cli/export.md b/docs/cli/export.md
@@ -6,7 +6,7 @@ future formats without breaking the CLI surface.
 
 ## Synopsis
 
-```
+```text
 lc export wrroc [OPTIONS]
 ```
 
@@ -53,15 +53,15 @@ lc export wrroc --license https://opensource.org/licenses/MIT
 
 ### Output
 
-```
+```text
 ✓ Wrote WRROC directory: ./wrroc
   Captured 7 runs across universes: baseline, alt_method
 ```
 
 If no materialized outputs are found, the bundle still writes — but only
 contains the workflow definition, and a warning is printed:
 
-```
+```text
 ✓ Wrote WRROC directory: ./wrroc
 Warning: no materialized outputs were found — the bundle contains only
   the workflow definition.

diff --git a/docs/cli/index.md b/docs/cli/index.md
@@ -24,7 +24,7 @@ Code skills, with the CLI as the durable, scriptable backstop.
 
 ## Global options
 
-```
+```text
 lc [OPTIONS] COMMAND [ARGS]...
 
 Options:

diff --git a/docs/cli/init.md b/docs/cli/init.md
@@ -4,7 +4,7 @@ Scaffold a new ASTRA project with Claude Code integration.
 
 ## Synopsis
 
-```
+```text
 lc init [OPTIONS] [DIRECTORY]
 ```
 
@@ -14,7 +14,7 @@ lc init [OPTIONS] [DIRECTORY]
 
 Inside `DIRECTORY` (creating it if needed):
 
-```
+```text
 astra.yaml                    # tiny boilerplate spec with one example output
 CLAUDE.md                     # short note pointing future agents at the project
 .gitignore                    # Python + lightcone state

diff --git a/docs/cli/run.md b/docs/cli/run.md
@@ -5,7 +5,7 @@ and dispatches through Snakemake on a Dask cluster.
 
 ## Synopsis
 
-```
+```text
 lc run [OPTIONS] [OUTPUTS]...
 ```
 

diff --git a/docs/cli/status.md b/docs/cli/status.md
@@ -5,7 +5,7 @@ Manifest-driven status report for every output declared in
 
 ## Synopsis
 
-```
+```text
 lc status [OPTIONS]
 ```
 

diff --git a/docs/cli/verify.md b/docs/cli/verify.md
@@ -5,7 +5,7 @@ input chain. Catches tampering, drift, and forged manifests.
 
 ## Synopsis
 
-```
+```text
 lc verify [OPTIONS]
 ```
 

diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md
@@ -77,7 +77,7 @@ relative to the repo root.
 
 ## Repo layout
 
-```
+```text
 src/lightcone/                       # main namespace (PEP 420; no __init__.py at the package root)
 src/snakemake_executor_plugin_dask/  # Snakemake → Dask executor plugin
 claude/lightcone/                    # Claude Code plugin (force-included into the wheel)

diff --git a/docs/contributing/testing.md b/docs/contributing/testing.md
@@ -2,7 +2,7 @@
 
 ## Test layout
 
-```
+```text
 tests/
 ├── conftest.py             # shared fixtures
 ├── test_cli.py             # Click CliRunner integration tests

diff --git a/docs/index.md b/docs/index.md
@@ -13,6 +13,22 @@ This site has two halves.
 Start at the [User Guide](user/index.md). Friendly, step-by-step, with
 worked examples. You will not need to read any Python.
 
+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
+    ```
+
+=== "pip"
+    ```bash
+    pip install lightcone-cli
+    lc init my-analysis && cd my-analysis
+    claude                               # then, inside Claude Code: /lc-new
+    ```
+
 ## I work on lightcone-cli
 
 Welcome — keep reading. The rest of this page is a fast tour for
@@ -34,11 +50,11 @@ spec itself (validation, paper management, evidence verification); the
 
 ## Repository at a glance
 
-```
+```text
 src/lightcone/                  # PEP 420 namespace package — NO __init__.py
 ├── cli/                        # Click surface
 │   ├── __init__.py             # exposes main()
-│   ├── commands.py             # init, run, status, verify, build, setup
+│   ├── commands.py             # init, run, status, verify, build, export
 │   └── plugin.py               # plugin source-dir discovery
 ├── engine/                     # execution substrate
 │   ├── manifest.py             # write_manifest, sha256_dir, code_version
@@ -74,7 +90,7 @@ regular package and break coexistence with future sibling distributions
 
 ## Execution flow
 
-```
+```text
 astra.yaml ── snakefile.generate() ──► .lightcone/Snakefile + .lightcone/snakefile-config.json
                                               │
                                        snakemake -s … -d … --executor dask

diff --git a/docs/skills/authoring.md b/docs/skills/authoring.md
@@ -7,7 +7,7 @@ Skills are markdown files with YAML frontmatter. Each one lives in
 
 ## File layout
 
-```
+```text
 claude/lightcone/skills/
 └── my-skill/
     ├── SKILL.md

diff --git a/docs/skills/index.md b/docs/skills/index.md
@@ -5,7 +5,7 @@ plugin. They give the agent a structured, phase-by-phase workflow for
 the most common research operations.
 
 If you're a researcher trying to *use* these, the
-[Claude Code Workflow](../user/claude-workflow.md) page in the user
+[Claude Code Workflow](../user/agent-workflow.md) page in the user
 guide is the friendly version. This page is for maintainers.
 
 ## Available skills
@@ -41,7 +41,7 @@ files, anti-patterns. The skill bundles its own helper scripts under
 
 ## Plugin layout
 
-```
+```text
 claude/lightcone/
 ├── skills/
 │   ├── lc-new/SKILL.md

diff --git a/docs/skills/lc-build.md b/docs/skills/lc-build.md
@@ -11,7 +11,7 @@ Defaults: universe `baseline`, max-iterations `25`.
 
 ## Allowed tools
 
-```
+```text
 Read, Write, Edit, Glob, Grep,
 Bash(astra:*), Bash(lc:*), Bash(python:*), Bash(git:*), Bash(pip:*), Bash(mkdir:*),
 Bash(setup-lc-build:*),

diff --git a/docs/skills/lc-feedback.md b/docs/skills/lc-feedback.md
@@ -10,7 +10,7 @@ Argument hint: `<what went wrong>`.
 
 ## Allowed tools
 
-```
+```text
 Bash(gh:*), Bash(python:*), Bash(uname:*), AskUserQuestion
 ```
 
@@ -48,7 +48,7 @@ create`.
 
 ## Issue body template
 
-```
+```text
 ## What happened
 [1–3 sentences combining user description + session context]
 
@@ -77,7 +77,7 @@ Sections that don't apply are dropped.
 
 ## Notes for the maintainer who's looking
 
-The triage hint in the prompt currently says "lightcone-cli — `lc` CLI,
-**Dagster execution**, recipes, container builds, scaffolding, skills."
-That's stale — the Dagster mention should be replaced with
-"Snakemake/Dask execution." See the `SKILL.md` source.
+The triage hint in the skill prompt distinguishes ASTRA (schema, validation,
+`astra` CLI) from lightcone-cli (Snakemake/Dask execution, `lc` CLI,
+container builds, scaffolding, skills). When in doubt, the skill defaults
+to lightcone-cli. See the `SKILL.md` source for the exact wording.
diff --git a/docs/skills/lc-migrate.md b/docs/skills/lc-migrate.md
@@ -9,7 +9,7 @@ Source: [`claude/lightcone/skills/lc-migrate/SKILL.md`](https://github.com/Light
 
 ## Allowed tools
 
-```
+```text
 Read, Write, Edit, Glob, Grep,
 Bash(astra:*), Bash(lc:*), Bash(python:*), Bash(pip:*), Bash(git:*), Bash(mkdir:*), Bash(ls:*),
 Agent, AskUserQuestion

diff --git a/docs/skills/lc-new.md b/docs/skills/lc-new.md
@@ -8,7 +8,7 @@ Source: [`claude/lightcone/skills/lc-new/SKILL.md`](https://github.com/Lightcone
 
 ## Allowed tools
 
-```
+```text
 Read, Write(astra.yaml), Write(universes/*), Write(CLAUDE.md),
 Edit(astra.yaml), Edit(universes/*), Edit(CLAUDE.md),
 Glob, Grep, Bash(astra:*), Bash(lc:*), Bash(mkdir:*), Bash(echo:*),
@@ -34,7 +34,9 @@ arbitrary files. The lc-extractor subagent is invoked via `Task`.
    and write them to `astra.yaml`.
 4. **Finalize** — `astra validate astra.yaml`, `astra validate
    --verify-evidence` if quotes exist, `astra universe generate -n
-   baseline`, populate the `## Working Notes` section of `CLAUDE.md`
+   baseline`, populate the `narrative:` block in `astra.yaml` (`summary`,
+   `methods`, `inputs`, `outputs` — `findings` stays TODO until results
+   exist), then populate the `## Working Notes` section of `CLAUDE.md`
    with conversational context not captured in the spec.
 
 The skill writes to `astra.yaml` after each phase rather than in bulk

diff --git a/docs/skills/lc-verify.md b/docs/skills/lc-verify.md
@@ -7,7 +7,7 @@ Source: [`claude/lightcone/skills/lc-verify/SKILL.md`](https://github.com/Lightc
 
 ## Allowed tools
 
-```
+```text
 Read, Glob, Grep,
 Bash(astra:*), Bash(lc:*), Bash(python:*), Bash(ls:*),
 AskUserQuestion
@@ -32,7 +32,7 @@ No `Write`, no `Edit`. The skill cannot modify the project.
 
 ## Report format
 
-```
+```text
 | Check                    | Status |
 |--------------------------|--------|
 | Spec validation          | ✓/✗    |

diff --git a/docs/user/agent-workflow.md b/docs/user/agent-workflow.md
@@ -1,4 +1,4 @@
-# The Agent Workflow
+# The Agentic Workflow
 
 The agentic surface is five slash commands. Each one is a structured
 prompt — the agent follows a specific phased flow, not free-form chat.
@@ -34,8 +34,11 @@ The skill walks you through four phases:
    (methodological choices that could shift results). `→ astra.yaml`.
 4. **Finalize.** `astra validate astra.yaml` to make sure the spec is
    valid; `astra universe generate -n baseline` to seed a baseline
-   universe; the `## Working Notes` section of `CLAUDE.md` gets the
-   conversational context that wouldn't otherwise survive a `/clear`.
+   universe; the `narrative:` block in `astra.yaml` gets filled in
+   (`summary`, `methods`, `inputs`, `outputs` — `findings` stays TODO
+   until results exist); the `## Working Notes` section of `CLAUDE.md`
+   gets the conversational context that wouldn't otherwise survive a
+   `/clear`.
 
 You don't write any code or YAML during `/lc-new`. By the time it
 finishes, you have a precise specification. The agent enforces this:

diff --git a/docs/user/cluster.md b/docs/user/cluster.md
@@ -5,6 +5,11 @@ a SLURM HPC system. There's no separate configuration to learn — the
 same `lc run` command works inside an allocation, just with more
 hardware to spread across.
 
+> On NERSC Perlmutter, the filesystem layout (DVS-mounted home, Lustre
+> scratch) and the `module load conda` workflow add a few site-specific
+> considerations. See [NERSC (Perlmutter)](nersc.md) for a focused
+> walkthrough.
+
 ## The big picture
 
 `lc run` always dispatches through a Dask cluster. Three branches:

diff --git a/docs/user/getting-started.md b/docs/user/getting-started.md
@@ -8,27 +8,27 @@ Make sure you've finished the [install](install.md) first.
 
 ## 1. Create a project
 
-```bash
-lc init my-analysis
-cd my-analysis
-```
+    lc init my-analysis
+    cd my-analysis
 
 `lc init` is a one-shot setup. It creates a small, opinionated
 directory layout and stops; it doesn't ask any questions.
 
 ## 2. What you got
 
-```
-my-analysis/
-├── astra.yaml                  # the spec — this is where everything lives
-├── CLAUDE.md                   # short note for the agent (resumes context across sessions)
-├── .gitignore
-├── .venv/                      # Python virtual env (skip with --no-venv)
-├── .lightcone/                 # internal scratchpad — don't edit by hand
-├── .claude/                    # Claude Code plugin — skills, agents, hooks
-├── universes/                  # placeholder for now
-└── results/                    # placeholder for now
-```
+    my-analysis/
+    ├── astra.yaml                  # the spec — this is where everything lives
+    ├── CLAUDE.md                   # short note for the agent (resumes context across sessions)
+    ├── .gitignore
+    ├── .git                        # initialized git repository (skip with --no-git)
+    ├── .venv/                      # Python virtual env (skip with --no-venv)
+    ├── .claude/                    # Claude Code plugin — skills, agents, hooks
+    ├── .lightcone/                 # internal scratchpad — don't edit by hand
+    ├── Containerfile               # build instructions for a local testing container — don't edit by hand
+    ├── requirements.txt            # software dependencies — don't edit by hand
+    ├── universes/                  # 
+    ├── src/                        # placeholder directories for now
+    └── results/                    # 
 
 The two files you'll actually look at:
 
@@ -50,9 +50,7 @@ can edit it by hand whenever you want.
 
 ## 3. Open Claude Code
 
-```bash
-claude
-```
+    claude
 
 That opens an interactive session inside `my-analysis/`. Claude Code
 reads `astra.yaml` and `CLAUDE.md` so it has context.
@@ -69,7 +67,7 @@ Inside Claude Code:
 | `/lc-migrate` | You have an existing codebase you want wrapped in ASTRA. |
 | `/lc-feedback` | Something broke and you want to file a GitHub issue without leaving the session. |
 
-The next page, [The Claude Code Workflow](claude-workflow.md),
+The next page, [The Agentic Workflow](agent-workflow.md),
 explains each of these in more detail.
 
 ## 5. The four CLI commands you'll actually type
@@ -90,7 +88,7 @@ exact flags.
 
 ## 6. Read on
 
-- [The Claude Code Workflow](claude-workflow.md) — how each slash
+- [The Agentic Workflow](agent-workflow.md) — how each slash
   command actually flows.
 - [Tutorial: Your First Analysis](tutorial.md) — end-to-end, with the
   agent doing most of the typing.
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,7 +5,7 @@ images so `lc run` can use `--pull=never`). @@
     ## Synopsis
-    ```
+    ```text
     lc build [OPTIONS]
     ```
@@ Expand Down Expand Up / @@ -35,7 +35,7 @@ nothing to build. @@
     ## Tag computation
-    ```
+    ```text
     lc-<sanitized-project-name>-<sha256[:12]>
     ```
@@ Expand Down @@