Documentation map

Reading order

1. Synthesis: feasibility, engines, existing tools, the recommended stack, risks and phasing.
2. UI spec: navigation, status system, every screen, phone and tablet.
3. Checking scenarios: the review model (items × checks × evidence × decisions) across the nf-core pipelines, and the five review views.
4. API and data model: headless use, endpoints, identity and tenancy, database schema, events, RO-Crate, depictio compatibility (§13).
5. Plugin architecture and packaging: plugin kinds and contract; Python bundle, Docker Compose and Kubernetes; tasks and message brokers (§7.6).
6. Schedulers and monitoring: SLURM and other HPC schedulers, Kubernetes, pending reasons, accounting, capacity and pre-flight checks.
7. Administration and operations: users and groups, branding, tasks, logs, health, backups, restore, migrations, maintenance.
8. CLI and shared libraries: the spectio command tree, server profiles, and the libraries shared with depictio and LabID.
9. depictio ecosystem reuse: what Spectio depends on, shares, copies, calls or leaves.
10. Dev environment and testing: toolchain, local SLURM (sind) and Kubernetes (kind with Kueue), isolated scenarios, test tiers, staging behind Tailscale Funnel, Claude in the development loop.
11. Authentication and access: instance modes, sign-in methods (password, magic links, share links, OIDC, SAML, depictio trust), sessions and tokens, pipeline provisioning, the auth test matrix.
12. Telemetry and analytics: anonymous install telemetry, local activity analytics, and the web-analytics plugin kind (GA4, Umami, Plausible, Matomo, PostHog).
13. Documentation system: the docs site and landing page, docs written and reviewed at every step, sketch diagrams, screenshots, casts and combined captures, changelog, PR bodies, auto-merge.

Playbooks and reviews

• Progress: one page per pipeline step, written while the step runs.
• Autopilot: runs the whole pipeline (pipeline.yaml) unattended in five waves, with the triage policy deciding what needs Thomas.
• Next phase: the prompt behind each pipeline step (review rounds, development layer, test infrastructure, planning).
• Inbox: the only place Thomas needs to look between runs.
• Reviews: one file per review round, and the finding format.

Decisions

The decision log is append-only and dated: what was decided, why, and where it is specified. New decisions use the decision record template.

Research

Working notes are dated and kept as written. Specs cite them. When something changes, a new note is added; old notes are not rewritten.

• depictio harmonisation: identity, tenancy and hand-off.
• depictio administration and operations.
• depictio CLI, models and packaging; LabID CLI.
• depictio frontend, branding, users and groups.
• depictio authentication, depictio docs system, test corpus and CI, budget governor and telemetry.
• Adoption and positioning: who the first users are, where to find them, and how not to fight Seqera.
• Spikes: synthetic pipelines, docs media tooling.
• research/data/: the nf-core survey behind the checking scenarios (analysis.json, classes.json, nfcore_released.tsv, nfcore_repos.tsv, and fetch.sh, which recreates the sparse clones).
• research/depictio-shots/: depictio screenshots used for comparison.

Conventions

• Language. English for everything in this repository.
• Spec header. Every spec starts with a status line (draft vX.Y · date · author) and its companion docs.
• Stable sections. Section numbers are kept stable so other docs can cite file.md §n. A new section gets the next number; it does not renumber old ones.
• Facts carry their source. A fact about another tool (Nextflow, Snakemake, SLURM, depictio…) gives its source: a link, or a file and line in a dated audit. Anything not verified is marked [to be validated] or inferred.
• Diagrams. Explanatory figures are hand-drawn sketches from tools/diagrams/ (light/dark PNG pairs, SVG committed). Small structural diagrams inside specs stay in Mermaid fenced blocks. See documentation system §0.