docs: add diataxis based documentation structure

DEVELOPER.md

@@ -0,0 +1,99 @@
+# Developer Guide
+
+## Prerequisites
+
+- Node.js 16 or higher
+- npm
+
+## Development and build workflow
+
+### Development mode
+
+Run the following command to rebuild the dashboard automatically on file changes:
+
+```sh
+npm run dev
+```
+
+To serve the static files without rebuilding (default: `http://localhost:8000`):
+
+```sh
+npm run serve
+```
+
+### Production build
+
+Build a minified, optimized bundle in `dist/dashboard.js` with source maps:
+
+```sh
+NODE_ENV=production npm run build
+```
+
+Without `NODE_ENV=production`, the output is not minified:
+
+```sh
+npm run build
+```
+
+### Output details
+
+| Item         | Value                                  |
+| ------------ | -------------------------------------- |
+| Entry point  | `src/main.js`                          |
+| Output       | `dist/dashboard.js` (with source maps) |
+| Format       | IIFE (for direct browser inclusion)    |
+| Minification | Enabled when `NODE_ENV=production`     |
+
+## Local serving with branch data
+
+The dashboard reads data from the `packages` and `historic-releases` branches.
+To serve the dashboard locally with real data, fetch the branch data first, then start the server:
+
+```sh
+npm run packages   # fetches packages/ from the packages branch
+npm run historic   # fetches historic/ from the historic-releases branch
+npm run serve      # serves at http://localhost:8000
+```
+
+To build and serve in one step:
+
+```sh
+npm run start
+```
+
+## Linting
+
+Check JavaScript (ESLint) and formatting (Prettier):
+
+```sh
+npm run lint
+```
+
+Auto-fix issues:
+
+```sh
+npm run fix
+```
+
+## GitHub Pages deployment
+
+The dashboard is served from the `gh-pages` branch via GitHub Pages at
+<https://gardenlinux.github.io/daily/>.
+
+After building, push your changes to the `gh-pages` branch:
+
+- `dist/` — production JavaScript bundle
+- `index.html` — dashboard entry point
+- `style.css` — styles
+
+GitHub Pages is configured to serve from the repository root (`/`).
+
+## GitHub token (optional)
+
+To avoid the GitHub API rate limit of 60 unauthenticated requests per hour,
+configure a personal access token in the dashboard:
+
+1. Go to [GitHub Settings > Tokens](https://github.com/settings/tokens).
+1. Create a token with `public_repo` scope (Classic `ghp_`) or a Fine-grained token (`github_pat_`).
+1. Click the settings icon in the dashboard header.
+1. Enter your token and save. The token is stored only in your browser's `localStorage`.

README.md

@@ -1,77 +1,49 @@
 # Garden Linux Daily Dashboard
 
-A real-time monitoring dashboard for Garden Linux CI/CD pipeline status, package builds, and workflow runs.
+## Documentation
 
-https://gardenlinux.github.io/daily/
+A browser-based monitoring dashboard for the Garden Linux CI/CD pipeline. It displays the
+current health of each pipeline stage and shows historical data for past Garden Linux versions.
 
-## 🌟 Features
+Live dashboard: <https://gardenlinux.github.io/daily/>
 
-- **Real-time Pipeline Status**: Monitor Production Garden Linux workflows
-- **Package Monitoring**: Track package builds and identify issues (via daily cronjob)
-- **Historical View**: Browse past Garden Linux versions
-- **GitHub Authentication**: Support for both Classic and Fine-grained GitHub tokens
+Our documentation contains detailed information about the following topics:
 
-## 🚀 Quick Start
+- [Dashboard concepts and data sources](https://docs.gardenlinux.org/docs/explanation/daily-dashboard)
+- [How to use the dashboard and re-run workflows](https://docs.gardenlinux.org/how-to/daily-dashboard.md)
+- [Dashboard reference](https://docs.gardenlinux.org/reference/supporting_tools/daily-dashboard.md)
 
-### Prerequisites
+For local development, see [DEVELOPER.md](DEVELOPER.md).
 
-- **To build or develop locally:**
-    - Node.js 16 or higher
-    - npm
-- **To use or serve the dashboard (e.g., via GitHub Pages or any static web server):**
-    - No dependencies required; just serve the static files in the repository (index.html, dist/dashboard.js, style.css, etc.)
+# Community
 
-## 🛠️ Development & Build Workflow
+To stay up-to-date with recent news about Gardenlinux, subscribe to our mailing list:
 
-### Development Mode
+<https://lists.neonephos.org/g/gardenlinux-discussion>
 
-- **Watch mode**: `npm run dev`
-  Rebuilds the dashboard automatically on file changes. Use this for local development.
-- **Serve only**: `npm run serve`
-  Serves the static files in the current directory (default: http://localhost:8000).
+For updates and statements regarding security issues, we have a security mailing
+list for you:
 
-### Production Build
+<https://lists.neonephos.org/g/gardenlinux-security>
 
-- **Build for production**:
+For embargoed security related topics, this list is for you:
 
-    ```sh
-    NODE_ENV=production npm run build
-    ```
+<https://lists.neonephos.org/g/gardenlinux-security-embargo>
 
-    This creates a minified, optimized bundle in `dist/dashboard.js` with source maps for debugging. Console statements are removed in production builds.
+# Contributing
 
-- **Build only**: `npm run build`
-  (If you do not set `NODE_ENV=production`, the output will not be minified.)
+We welcome your contributions to Gardenlinux or any supporting projects.
 
-### Output Details
+To find out more, visit our
+[Contributor Documentation](https://docs.gardenlinux.org/contributing).
 
-- **Entry Point**: `src/main.js`
-- **Output**: `dist/dashboard.js` (with source maps)
-- **Format**: IIFE for direct browser inclusion
-- **Minification**: Enabled automatically when `NODE_ENV=production`
+## Licensing
 
-## 🚀 GitHub Pages Integration
-
-This dashboard is designed to be deployed on GitHub Pages:
-
-- The `dist/` directory contains the production-ready JavaScript bundle.
-- The `index.html` and `style.css` are also in the repository root for direct serving.
-- GitHub Pages is configured to serve from the `/` (root).
-- After building, simply push your changes to the `gh-pages` branch.
-- The dashboard will be live at: https://gardenlinux.github.io/daily/
-
-## 🔧 Configuration
-
-### GitHub Token (Optional but Recommended)
-
-To avoid GitHub API rate limits, configure a personal access token:
-
-1. Go to [GitHub Settings > Tokens](https://github.com/settings/tokens)
-2. Create a token with `public_repo` or `repo` scope
-3. Click the ⚙️ settings button in the dashboard
-4. Enter your token and save
-
-The dashboard supports both Classic (`ghp_`) and Fine-grained (`github_pat_`) tokens.
+Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors.
+See our [LICENSE](LICENSE) for copyright and license information.
+Detailed information including third-party components and their
+licensing/copyright information is available
+[via the REUSE tool](https://reuse.software).
 
 <p align="center">
   <img alt="Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo" src="https://apeirora.eu/assets/img/BMWK-EU.png" width="400"/>

docs/explanation/daily-dashboard.md

@@ -0,0 +1,88 @@
+---
+title: "Daily Dashboard"
+description: "How the Garden Linux Daily Dashboard monitors the build and release pipeline, and how it collects data from GitHub Actions."
+order: 160
+github_org: gardenlinux
+github_repo: daily
+github_source_path: docs/explanation/daily-dashboard.md
+github_target_path: docs/explanation/daily-dashboard.md
+related_topics:
+    - /explanation/daily-dashboard
+    - /explanation/github-workflows
+    - /how-to/daily-dashboard
+    - /reference/supporting_tools/daily-dashboard
+    - /reference/releases/release-lifecycle
+---
+
+# Garden Linux Daily Dashboard
+
+The [Garden Linux Daily Dashboard](https://gardenlinux.github.io/daily/) is a static, browser-based monitoring page for the Garden Linux (GL) build and release pipeline. It displays the real-time health of each pipeline stage and shows historical data for past GL days.
+
+## Pipeline stages
+
+The dashboard monitors four pipeline stages and two auxiliary workflows:
+
+| Stage                            | Repository                                     | Workflows                                   |
+| -------------------------------- | ---------------------------------------------- | ------------------------------------------- |
+| Stage 1 – Package Builds         | All non-archived `gardenlinux/package-*` repos | `build.yml` on `main` or `master`           |
+| Stage 2 – Repository             | `gardenlinux/repo`                             | `build.yml`, `update.yml`                   |
+| Stage 3 – Build & Release Images | `gardenlinux/gardenlinux`                      | `nightly.yml` (daily), `manual_release.yml` |
+| Auxiliary – Cloud Test Cleanup   | `gardenlinux/gardenlinux`                      | `cloud_test_cleanup.yml`                    |
+| Auxiliary – Debian Snapshot      | `gardenlinux/repo-debian-snapshot`             | `snapshot.yml`                              |
+
+Stage 4 only applies to GL versions below 2174. From GL 2174 onwards (schema v2), the dashboard suppresses Stage 4 entirely.
+
+### Deprecations
+
+<details>
+
+| Stage                    | Repository                | Workflows                       |
+| ------------------------ | ------------------------- | ------------------------------- |
+| Stage 4 – Publish Images | `gardenlinux/gardenlinux` | `publish.yml`, `publish_s3.yml` |
+
+::: info
+Stage 4 only applies to GL versions below 2174. From GL 2174 onwards (schema v2), the dashboard suppresses Stage 4 entirely.
+:::
+
+</details>
+
+## Data sources
+
+The dashboard combines three data sources.
+
+### Package states (Stage 1)
+
+A Go binary (`package-aggregator/main.go`) runs nightly at 03:00 UTC via the `aggregate_package_states.yml` workflow. It scans every non-archived, non-excluded `gardenlinux/package-*` repository, checks the most recent `build.yml` run on `main` or `master`, and writes the result to `packages/{glDays}.json` on the `packages` branch.
+
+The dashboard fetches this file at build time. The Stage 1 table shows only packages with a non-`success` status. An empty table means all packages are healthy.
+
+### Historic release archive (Stages 2–3)
+
+`scripts/collect-historic.js` runs nightly at 05:00 UTC via the `archive_historic_releases.yml` workflow. It queries the GitHub API for the last 14 GL days and writes per-day pipeline summaries to `historic/{glDays}.json` on the `historic-releases` branch.
+
+For past GL days the dashboard reads these pre-built cache files. It falls back to live GitHub API calls only when the cache is absent for a given day.
+
+### Live GitHub API (current day)
+
+For the current GL day the browser fetches workflow run data directly from the GitHub API at page load time. Unauthenticated requests are subject to a rate limit of 60 requests per hour. You can raise this limit by storing a personal access token in the dashboard settings (see [View the dashboard and re-run workflows](/how-to/daily-dashboard)).
+
+## Branch data model
+
+| Branch              | Content                                                           |
+| ------------------- | ----------------------------------------------------------------- |
+| `packages`          | `packages/{glDays}.json` — package build states per GL day        |
+| `historic-releases` | `historic/{glDays}.json` — full pipeline summary cache per GL day |
+| `gh-pages`          | Static dashboard site (`index.html`, `style.css`, `dist/`)        |
+
+## Schema versions
+
+| Condition | Schema | Stage 4    |
+| --------- | ------ | ---------- |
+| GL < 2174 | v1     | Present    |
+| GL ≥ 2174 | v2     | Suppressed |
+
+The schema version affects which workflow IDs the dashboard expects and how it calculates pipeline durations.
+
+## Related Topics
+
+<RelatedTopics />