Publish the site as the Lightcone Research Stack docs

.github/workflows/docs.yml

@@ -0,0 +1,58 @@
+name: Docs
+
+# Builds the site in strict mode on every PR, so a broken link or a nav
+# entry pointing at a missing page fails the PR rather than the deploy.
+# On main, the same build is then published to GitHub Pages (Settings →
+# Pages → Source must be "GitHub Actions").
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v10.2.0
+        with:
+          enable-cache: true
+
+      - name: Install docs dependencies
+        run: uv sync --locked
+
+      - name: Build site
+        run: uv run zensical build --clean --strict
+
+      - name: Upload site
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    if: github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    # Deploys queue rather than cancel each other, so one is never
+    # interrupted mid-publish.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Centre National de la Recherche Scientifique (CNRS) and
+The Regents of the University of California
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,3 +1,38 @@
-# docs
+# Lightcone Research Stack documentation
 
-Documentation for the Lightcone Research stack
+[![Docs](https://img.shields.io/github/actions/workflow/status/LightconeResearch/docs/docs.yml?branch=main&style=flat&label=docs&color=darkgreen)](https://docs.lightconeresearch.org)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-426b78.svg?style=flat)](LICENSE)
+
+The **Lightcone Research Stack** is [Lightcone Research](https://lightconeresearch.org/)'s
+tooling for research analyses described with [ASTRA](https://astra-spec.org/latest/)
+(Agentic Schema for Transparent Research Analysis). You describe an analysis in an
+`astra.yaml` specification; the stack validates it and takes care of the rest —
+execution, environments, and provenance.
+
+**→ Read the documentation at <https://docs.lightconeresearch.org>**
+
+## Where to start
+
+- [Install](https://docs.lightconeresearch.org/user/install/) — uv, git, and the `lc` command
+- [Getting started](https://docs.lightconeresearch.org/user/getting-started/) — your first analysis, from `lc init` to a published result
+- [Core concepts](https://docs.lightconeresearch.org/user/concepts/) — projects, output identity, and how provenance is recorded
+- [Running on a cluster](https://docs.lightconeresearch.org/user/cluster/) — SLURM, containers on HPC, and parallel filesystems
+- [Troubleshooting](https://docs.lightconeresearch.org/user/troubleshooting/) — common errors and how to fix them
+
+## Components
+
+| Component | What it does | Repository |
+| --- | --- | --- |
+| **lightcone-cli** | The `lc` CLI: project scaffolding, locked environments, sandboxed execution, and the provenance layer | [LightconeResearch/lightcone-cli](https://github.com/LightconeResearch/lightcone-cli) |
+| **astra-tools** | The SDK and `astra` CLI for ASTRA specifications: schema, validation, and evidence verification helpers | [LightconeResearch/astra-tools](https://github.com/LightconeResearch/astra-tools) |
+
+## Feedback
+
+The stack is in early alpha, and bug reports, design challenges, and use cases it
+doesn't cover yet are welcome. Report a problem with a tool on that tool's
+repository; report a problem with the documentation itself — a page that is wrong,
+unclear, or out of date — [here](https://github.com/LightconeResearch/docs/issues).
+
+## License
+
+BSD 3-Clause — see [LICENSE](LICENSE).

docs/index.md

@@ -1,16 +1,17 @@
-# lightcone-cli
+# Lightcone Research Stack
 
-**lightcone-cli** is [Lightcone Research][lr]'s 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.
+The **Lightcone Research Stack** is [Lightcone Research][lr]'s tooling for research
+analyses described with [**ASTRA**][astra] (Agentic Schema for Transparent Research
+Analysis).  
+You describe an analysis in an `astra.yaml` specification; the stack validates it and
+takes care of the rest — execution, environments, and provenance.
 
 !!! warning "Alpha development"
-    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
-    [GitHub repo](https://github.com/LightconeResearch/lightcone-cli/issues).
+    The stack is in **early alpha**. Its tools 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 [repository](https://github.com/LightconeResearch) of the tool
+    concerned.
 
 ## Choose your path to the documentation
 
@@ -28,7 +29,7 @@ of materialized outputs.
 
     ---
 
-    In depth tour of the software architecture and API docs, as well as contribution instructions, aimed for
+    In-depth tour of lightcone-cli's architecture and internals, as well as contribution instructions, aimed at
     contributors and maintainers.
 
     [Developer corner](maintainer.md){ .md-button .md-button--primary }
@@ -37,7 +38,7 @@ of materialized outputs.
 
 ---
 
-## Two libraries, one toolchain
+## Components of the stack
 
 <div class="grid cards" markdown>
 

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "lightcone-docs"
 version = "0.0.0"
-description = "Documentation for the Lightcone Research stack"
+description = "Documentation for the Lightcone Research Stack"
 requires-python = ">=3.11"
 dependencies = [
     "zensical>=0.0.34",

zensical.toml

@@ -1,6 +1,7 @@
 [project]
-site_name = "lightcone-cli"
-site_description = "Execution layer for ASTRA research pipelines"
+site_name = "Lightcone Research Stack"
+site_description = "Documentation for the Lightcone Research Stack"
+site_url = "https://docs.lightconeresearch.org/"
 site_author = "Lightcone Research Team"
 repo_url = "https://github.com/LightconeResearch/docs"
 repo_name = "LightconeResearch/docs"