From 100132300742040cfd65a17a7261a06789874079 Mon Sep 17 00:00:00 2001 From: Francois Lanusse Date: Sun, 27 Sep 2026 16:19:38 -0700 Subject: [PATCH 1/4] Publish the site to GitHub Pages Replace the build-only workflow with one that builds in strict mode on every PR and, on main, deploys the same build to GitHub Pages. Set site_url so canonical links and the sitemap point at docs.lightconeresearch.org. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/build.yml | 26 ----------------- .github/workflows/docs.yml | 58 +++++++++++++++++++++++++++++++++++++ zensical.toml | 1 + 3 files changed, 59 insertions(+), 26 deletions(-) delete mode 100644 .github/workflows/build.yml create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index d7eed9b..0000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,26 +0,0 @@ -name: Build Docs - -# Builds the site in strict mode, so a broken link or a nav entry -# pointing at a missing page fails the PR rather than the deploy. - -on: - pull_request: - push: - branches: [main] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v4 - - - name: Set up uv - uses: astral-sh/setup-uv@v6 - with: - enable-cache: true - - - name: Install docs dependencies - run: uv sync --locked - - - name: Build site - run: uv run zensical build --strict diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..af83831 --- /dev/null +++ b/.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 + 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 diff --git a/zensical.toml b/zensical.toml index e4ef834..c671102 100644 --- a/zensical.toml +++ b/zensical.toml @@ -1,6 +1,7 @@ [project] site_name = "lightcone-cli" site_description = "Execution layer for ASTRA research pipelines" +site_url = "https://docs.lightconeresearch.org/" site_author = "Lightcone Research Team" repo_url = "https://github.com/LightconeResearch/docs" repo_name = "LightconeResearch/docs" From 4d5a6a8a9b4bb1953f0e71c15c8bbdad0f9f8950 Mon Sep 17 00:00:00 2001 From: Francois Lanusse Date: Sun, 27 Sep 2026 16:20:13 -0700 Subject: [PATCH 2/4] Pin setup-uv to its full version tag setup-uv publishes no floating major tag, so @v10 does not resolve. Co-Authored-By: Claude Opus 5.5 --- .github/workflows/docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index af83831..fc09d90 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -21,7 +21,7 @@ jobs: - uses: actions/checkout@v7 - name: Set up uv - uses: astral-sh/setup-uv@v10 + uses: astral-sh/setup-uv@v10.2.0 with: enable-cache: true From 0747925a9367644e5e176cd5438acf1b394b96e4 Mon Sep 17 00:00:00 2001 From: Francois Lanusse Date: Sun, 27 Sep 2026 16:27:50 -0700 Subject: [PATCH 3/4] Present the site as the Lightcone Research Stack docs Rename the site and rewrite the home page intro and alpha warning for the stack rather than lightcone-cli alone. Pages about the CLI itself are unchanged. Co-Authored-By: Claude Opus 5.5 --- docs/index.md | 25 +++++++++++++------------ pyproject.toml | 2 +- zensical.toml | 4 ++-- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/index.md b/docs/index.md index 3146407..e1b65bc 100644 --- a/docs/index.md +++ b/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
diff --git a/pyproject.toml b/pyproject.toml index fc6816d..0cb0631 100644 --- a/pyproject.toml +++ b/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", diff --git a/zensical.toml b/zensical.toml index c671102..630d5e6 100644 --- a/zensical.toml +++ b/zensical.toml @@ -1,6 +1,6 @@ [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" From 49d5a356e7fd1042b3b00633d520442f220bb5a8 Mon Sep 17 00:00:00 2001 From: Francois Lanusse Date: Sun, 27 Sep 2026 16:27:50 -0700 Subject: [PATCH 4/4] Add a user-facing README and the stack's BSD 3-Clause license The README is now the repository's landing page for readers: what the stack is, where the docs live, where to start, and where to report problems. The license is lightcone-cli's, which the imported content was already published under. Co-Authored-By: Claude Opus 5.5 --- LICENSE | 29 +++++++++++++++++++++++++++++ README.md | 39 +++++++++++++++++++++++++++++++++++++-- 2 files changed, 66 insertions(+), 2 deletions(-) create mode 100644 LICENSE diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..c441ecc --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 0f81c4f..20f0b9e 100644 --- a/README.md +++ b/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 ** + +## 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).