Merge pull request #10 from moja-global/docs/enterprise-upgrade-2026-03-27

Docs/enterprise upgrade 2026 03 27

Author: Simpleshell3

.github/workflows/docs-pages.yml

@@ -8,6 +8,7 @@ on:
     paths:
       - "docs/**"
       - "mkdocs.yml"
+      - "scripts/check_docs_anchors.py"
       - ".github/workflows/docs-pages.yml"
 
 permissions:
@@ -34,7 +35,10 @@ jobs:
       - name: Install docs dependencies
         run: |
           python -m pip install --upgrade pip
-          pip install mkdocs-material
+          pip install mkdocs==1.6.1 mkdocs-material==9.7.3 pymdown-extensions==10.21 requests==2.32.3
+
+      - name: Anchor and internal link check
+        run: python scripts/check_docs_anchors.py
 
       - name: Build docs site
         run: mkdocs build --strict --site-dir site

.github/workflows/docs-quality.yml

@@ -0,0 +1,58 @@
+name: Docs Quality
+
+on:
+  pull_request:
+    paths:
+      - "README.md"
+      - "docs/**"
+      - "mkdocs.yml"
+      - "scripts/check_docs_anchors.py"
+      - ".markdownlint-cli2.yaml"
+      - ".github/workflows/docs-quality.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs-quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install docs dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs==1.6.1 mkdocs-material==9.7.3 pymdown-extensions==10.21 requests==2.32.3
+
+      - name: Anchor and internal link check
+        run: python scripts/check_docs_anchors.py
+
+      - name: Build docs site (strict)
+        run: mkdocs build --strict --site-dir site
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install markdownlint-cli2
+        run: npm install -g markdownlint-cli2
+
+      - name: Markdown style check
+        run: markdownlint-cli2 "README.md" "docs/**/*.md"
+
+      - name: External link check
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --verbose --no-progress --accept 200,206,429 README.md docs/**/*.md
+          fail: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

.markdownlint-cli2.yaml

@@ -0,0 +1,14 @@
+config:
+  default: true
+  MD013: false
+  MD033: false
+  MD041: false
+
+globs:
+  - "README.md"
+  - "docs/**/*.md"
+
+ignores:
+  - "site/**"
+  - "dist/**"
+

README.md

@@ -1,129 +1,41 @@
 # GCBM View
 
-GCBM View is a desktop application for configuring, running, and analyzing
-Generic Carbon Budget Model (GCBM) simulations with a guided user interface.
+GCBM View is a desktop application for configuring, running, compiling, and
+analyzing Generic Carbon Budget Model (GCBM) workflows.
 
-## What You Can Do
+This README is intentionally short. The canonical documentation lives in MkDocs.
 
-- Configure simulation inputs from shapefiles and project folders.
-- Run simulation workflows with live status and logs.
-- Compile model outputs into analysis-ready databases and optional TIFFs.
-- Explore results in charts, maps, and standard reporting views.
+## Start Here
 
-## Table of Contents
-
-1. [Requirements](#requirements)
-2. [Install and Run](#install-and-run)
-3. [End-to-End Walkthrough](#end-to-end-walkthrough)
-4. [Documentation Map](#documentation-map)
-5. [Installer and Release Process](#installer-and-release-process)
-6. [Developer Notes](#developer-notes)
-7. [Troubleshooting](#troubleshooting)
+- Docs home: `docs/index.md`
+- Simulation playbook: `docs/playbooks/simulation.md`
+- Compilation playbook: `docs/playbooks/compilation.md`
+- Visualization playbook: `docs/playbooks/visualization.md`
+- Troubleshooting matrix: `docs/operations/troubleshooting-matrix.md`
 
 ## Requirements
 
 - Python `>=3.10`
-- Windows is the primary supported packaging target for the `.exe` installer
-- A prepared GCBM project workspace (for example `gcbm_training` outputs)
-
-## Install and Run
+- Windows is the primary installer packaging target (`.exe`)
+- A prepared GCBM workspace (for example `gcbm_training`)
 
-### Install from source
+## Run From Source
 
 ```bash
 cd gcbm_view
 uv pip install -e .
-```
-
-### Launch
-
-```bash
 gcbm-view
 ```
 
-or:
+Alternative:
 
 ```bash
 python -m gcbm_view.app
 ```
 
-## End-to-End Walkthrough
-
-This section mirrors the full user flow from configuration to reporting.
-
-### 1. Configure and run a simulation
-
-- Open the **Simulation** page.
-- Select your project directory and confirm discovered input files.
-- Map required columns (age, classifiers, and temperature source).
-- Validate configuration, then run the simulation.
-
-![Simulation page](docs/images/simulation1.png)
-
-### 2. Compile simulation outputs
-
-- Open the **Compile** page.
-- Select the project with generated outputs.
-- Set output database name.
-- Optionally include spatial TIFF outputs.
-
-![Compilation page](docs/images/compilation1.png)
-
-### 3. Explore visual outputs
-
-- Open the **Visualize** page.
-- Load the compiled `.db` file.
-- Build charts (line, stacked area, stacked bars, dual axis, and others).
-- Enable map mode for spatial outputs when TIFFs are present.
-
-![Visualization page](docs/images/visualization1.png)
-
-### 4. Review generated reports
-
-- Open the **Reports** page after loading a compiled database.
-- Export or review standard reporting outputs for analysis workflows.
-
-![Reports page](docs/images/reports1.png)
-
-## Documentation Map
-
-The complete docs are in `docs/` and configured through `mkdocs.yml`.
-
-- Main docs entry: [`docs/index.md`](docs/index.md)
-- Full walkthrough: [`docs/WALKTHROUGH.md`](docs/WALKTHROUGH.md)
-- User guide: [`docs/USER_GUIDE.md`](docs/USER_GUIDE.md)
-- Installation guide: [`docs/guide/installation.md`](docs/guide/installation.md)
-- Simulation guide: [`docs/guide/simulation.md`](docs/guide/simulation.md)
-- Methodology overview: [`docs/methodology/index.md`](docs/methodology/index.md)
-- API notes: [`docs/api.md`](docs/api.md)
-
-## Installer and Release Process
-
-Installer automation and packaging assets live in [`installer/`](installer/README.md).
-
-### Release channels
-
-- Continuous release:
-  - Trigger: push to `main`
-  - Output: prerelease tagged `continuous`, updated automatically
-- Versioned release:
-  - Trigger: tag push matching `v*` (for example `v0.6.0`)
-  - Output: tagged release with installer asset
-
-### CI/CD requirements
-
-- GitHub Actions workflow: `.github/workflows/windows-installer.yml`
-- Required secret: `CROSS_REPO_READ_TOKEN` (read access to private component repos)
-
-## Developer Notes
-
-- Entry point script: `gcbm-view` (`gcbm_view.app:main`)
-- Source package path: `src/gcbm_view`
-- Optional dev tools: `pytest`, `black`, `ruff`
-
-## Troubleshooting
+## Installer and CI/CD
 
-- If simulation configuration fails, verify input file paths and required columns.
-- If charts are empty, confirm the compiled database has expected views/tables.
-- If map mode is blank, verify TIFF outputs were included during compilation.
-- If CI checkout fails, check `CROSS_REPO_READ_TOKEN` scope and org approval.
+- Installer assets and build notes: `installer/README.md`
+- Windows installer workflow: `.github/workflows/windows-installer.yml`
+- Docs quality workflow: `.github/workflows/docs-quality.yml`
+- Docs pages workflow: `.github/workflows/docs-pages.yml`