update guides

Author: dorien-er

.github/workflows/README.md

@@ -8,7 +8,7 @@ Renders the Quarto site and deploys `_site/` to GitHub Pages on every push to
 ## `generate-reference.yml`
 
 Populates **versioned** reference docs for the **whole ecosystem**, driven
-entirely from this repo — no package repository needs its own workflow. Layout:
+entirely from this repo, no package repository needs its own workflow. Layout:
 
 ```
 reference/<package>/<version>/<namespace>/<name>.qmd
@@ -20,7 +20,7 @@ On manual dispatch (or a weekly schedule) it:
    (`openpipeline`, `openpipeline_spatial`, `openpipeline_qc`,
    `openpipeline_composed`; `openpipeline_rapids` excluded for now),
 2. **caches**: if `reference/<package>/<version>/` already exists, that version
-   is skipped and never rebuilt — so a run does nothing unless a **new** release
+   is skipped and never rebuilt, so a run does nothing unless a **new** release
    has appeared ("latest forward"),
 3. for each new version, clones that tag from viash-hub (public, no credentials;
    the tag ships the built `target/` the generator reads) and runs
@@ -34,12 +34,12 @@ organized by package + version and can never drift from released code. The
 generator must read a **built** package (`target/`), which is why we pull tagged
 releases from viash-hub rather than `main` (where `target/` is not committed).
 
-**Setup required:** add repo secret **`GTHB_PAT`** — used only as the
+**Setup required:** add repo secret **`GTHB_PAT`**: used only as the
 `viash_pro_token`, which the generator needs to clone the private
 `viash-io/viash_tools` repo. Package fetching itself needs no credentials. This
 is the same token the production website workflow uses; reuse that value. Then
 run the workflow from the Actions tab (**Generate reference → Run workflow**) to
 produce the first PR.
 
-Never hand-edit anything under `reference/<package>/<version>/` — a version is
+Never hand-edit anything under `reference/<package>/<version>/`, a version is
 generated once and then frozen (later runs skip it).

README.md

@@ -1,6 +1,6 @@
 # openpipeline_docs
 
-Draft next-generation documentation site for the **OpenPipeline** ecosystem —
+Draft next-generation documentation site for the **OpenPipeline** ecosystem,
 covering single-cell (`openpipeline`) and spatial (`openpipeline_spatial`), plus
 the cross-cutting `openpipeline_qc`, `openpipeline_rapids`, and
 `openpipeline_composed` packages.
@@ -26,7 +26,7 @@ index.qmd            landing page (single-cell + spatial flows)
 get-started/         tutorial: guided first run (Local / Seqera / Viash Hub)
 guides/              task-oriented how-tos
 concepts/            explanation: MuData, Viash, param_list, pipeline model
-reference/           AUTO-GENERATED per package (see below) — do not hand-edit
+reference/           AUTO-GENERATED per package (see below), do not hand-edit
   openpipeline/
   openpipeline_spatial/
   openpipeline_qc/
@@ -58,4 +58,4 @@ See `.github/workflows/README.md` for the wiring plan.
 ## Status
 
 Scaffold + design mockup. Narrative content is partially ported from the current
-site and partially placeholder — see individual pages.
+site and partially placeholder, see individual pages.

_quarto.yml

@@ -6,6 +6,9 @@ project:
   # Draft site: ship a crawler-blocking robots.txt into the build output.
   resources:
     - robots.txt
+    # Shared single-cell/spatial flow widget, loaded by index.qmd and
+    # concepts/architecture.qmd via <script src>.
+    - flow.js
   # NOTE: team/ is a hand-curated static page for now (sections + roles the flat
   # author registry can't express). scripts/generate_team.py is kept for the
   # eventual return to auto-generation but is intentionally NOT wired as a
@@ -31,16 +34,25 @@ website:
     logo: images/logo-mark.svg
     title: "OpenPipeline"
     left:
-      - href: get-started/index.qmd
-        text: Get started
-      - href: guides/index.qmd
-        text: Guides
       - href: concepts/index.qmd
         text: Concepts
-      - href: reference/index.qmd
-        text: Reference
-      - href: contributing/index.qmd
-        text: Contributing
+      # "Workflows" = the curated available-workflows overview. Page still lives
+      # under concepts/ (kept there to avoid breaking cross-links). The advanced
+      # developer deep-dive stays in the Concepts hub, not here.
+      - href: concepts/architecture.qmd
+        text: Workflows
+      # "Documentation" groups the practical, do-it materials. Get started is
+      # also the primary landing-page CTA, so it stays reachable from the hero.
+      - text: Documentation
+        menu:
+          - href: get-started/index.qmd
+            text: Get started
+          - href: guides/index.qmd
+            text: Guides
+          - href: reference/index.qmd
+            text: Reference
+          - href: contributing/index.qmd
+            text: Contributing
       - href: team/index.qmd
         text: Team
     right:
@@ -55,9 +67,9 @@ website:
     - id: guides
       title: "Guides"
       contents: guides/*
-    - id: concepts
-      title: "Concepts"
-      contents: concepts/*
+    # Concepts has no sidebar — the concepts index (concepts/index.qmd) is a
+    # card catalog that serves as the section hub, and the pages run wide
+    # (flow widget, workflow tables) so the reclaimed width matters.
     - id: contributing
       title: "Contributing"
       contents: contributing/*

concepts/architecture.qmd

@@ -1,6 +1,6 @@
 ---
-title: "Pipeline architecture"
-description: "How OpenPipeline fits into a single-cell project"
+title: "Available workflows"
+description: "Every workflow OpenPipeline offers, arranged by where it sits in the pipeline."
 order: 60
 ---
 
@@ -54,7 +54,7 @@ This per-sample H5MU is the unit that flows through all subsequent steps. The
 right ingestion workflow depends on your sequencing platform and library type.
 
 ::: {.callout-tip appearance="simple"}
-**Guide:** [Ingest 10x Genomics data](../guides/ingest-10x.qmd): workflow selection, reference genome setup, and examples.
+**Guide:** [Ingestion](../guides/ingest-10x.qmd): workflow selection, reference genome setup, and examples.
 :::
 
 | Workflow / component | Package | Description |
@@ -148,7 +148,7 @@ The concatenated object then goes through:
 4. **PCA**: a principal-component embedding is computed.
 
 ::: {.callout-tip appearance="simple"}
-**Guide:** [Process & filter samples](../guides/process-filter.qmd): full details and examples.
+**Guide:** [Sample processing](../guides/process-filter.qmd): full details and examples.
 :::
 
 :::{.callout-note}
@@ -176,7 +176,7 @@ OpenPipeline provides one workflow per integration method. There is no single
 default; the right choice depends on dataset size and batch structure.
 
 ::: {.callout-tip appearance="simple"}
-**Guide:** [Integrate with Harmony or scVI](../guides/integrate.qmd): guidance on choosing a method.
+**Guide:** [Integration](../guides/integrate.qmd): guidance on choosing a method.
 :::
 
 | Workflow | Package | Method | Description |
@@ -198,7 +198,7 @@ separately from the core pipeline and depends on the tissue and biological
 question.
 
 ::: {.callout-tip appearance="simple"}
-**Guide:** [Annotate cell types](../guides/annotate.qmd): details and examples.
+**Guide:** [Cell type annotation](../guides/annotate.qmd): details and examples.
 :::
 
 | Workflow | Package | Description |