andrei-akopian · Oct 21, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026 · Oct 17, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,24 @@
+# Build outputs
 bin/
-/logs/
-__pycache__/
-*.py[cod]
+dist/
+web-interface/dist/
+docs/public/
+docs/resources/
+*.hugo_build.lock
+
+# Dependencies
+node_modules/
+
+# Runtime data & local environment
 data/
+/logs/
 .direnv/
 .fake-backend-config.json
+*.local
+
+# Python caches
+__pycache__/
+*.py[cod]
 
 # OS files
-.DS_Store
+.DS_Store
diff --git a/README.md b/README.md
@@ -23,17 +23,17 @@ administrator SSH access. Kubernetes/containerd run workload containers.
 
 Start with the [documentation index](docs/README.md).
 
-- [Using the portal, teams and jobs](docs/department-rollout.md)
-- [k3s setup, accelerator allocation and diagnostics](docs/k3s-setup.md)
-- [Tailscale and SSH setup](docs/tailscale-ssh.md)
-- [Architecture and code organization](docs/architecture.md)
-- [Storage and upload limits](docs/storage.md)
+- [Using the portal, teams and jobs](docs/content/department-rollout.md)
+- [k3s setup, accelerator allocation and diagnostics](docs/content/k3s-setup.md)
+- [Tailscale and SSH setup](docs/content/tailscale-ssh.md)
+- [Architecture and code organization](docs/content/architecture.md)
+- [Storage and upload limits](docs/content/storage.md)
 - [Deployment and operations](deploy/private/README.md)
-- [Developer setup](docs/development.md), [CLI](cli/docs/setup.md), [testing](docs/testing.md)
+- [Developer setup](docs/content/development.md), [CLI](cli/docs/setup.md), [testing](docs/content/testing.md)
 
 Main contains the department release merged through
 [PR #110](https://github.com/UTMIST/Mist/pull/110). The earlier main and operating
-snapshots are preserved in the [historical archive](docs/archive/README.md).
+snapshots are preserved in the [historical archive](docs/content/archive/_index.md).
 
 ## Development and checks
 
@@ -49,7 +49,7 @@ npm --prefix web-interface run build
 ```
 
 For a local UI against the authenticated deployed API, follow
-[developer setup](docs/development.md). For the existing installation, deploy with
+[developer setup](docs/content/development.md). For the existing installation, deploy with
 `bash deploy/private/build-and-deploy.sh`; read its [prerequisites](deploy/private/README.md)
 before running it. Fresh-host provisioning is covered separately by the k3s guide.
 

diff --git a/cli/docs/setup.md b/cli/docs/setup.md
@@ -65,4 +65,4 @@ To cancel that job while waiting/running, use `bin/mist-cli job cancel "$JOB_ID"
 read historical jobs; new work requires a team. `--scope common` requires common
 write permission. Custom tagged public images are allowed by team registry policy;
 TT custom images use `--tt-runtime container`. See the
-[department guide](../../docs/department-rollout.md) for limits and storage.
+[department guide](../../docs/content/department-rollout.md) for limits and storage.
diff --git a/deploy/k3s/README.md b/deploy/k3s/README.md
@@ -1,7 +1,7 @@
 # Kubernetes deployment assets
 
 Current installation: two k3s nodes, authenticated team jobs, scoped NFS storage
-and private Tailscale portal. Start with the [k3s setup/handoff](../../docs/k3s-setup.md)
+and private Tailscale portal. Start with the [k3s setup/handoff](../../docs/content/k3s-setup.md)
 and [deployment operations](../private/README.md).
 
 ## Manifest and tooling map
@@ -29,6 +29,6 @@ The application image build uses [Dockerfile.api](Dockerfile.api). API/auth imag
 are imported into main's k3s containerd, not scheduled by a Docker supervisor.
 Use `bash deploy/private/build-and-deploy.sh` for the existing installation.
 
-[Old deployment history](../../docs/archive/k3s-deployment-history.md) and
-[original node setup](../../docs/archive/k3s-setup-history.md) preserve earlier
+[Old deployment history](../../docs/content/archive/k3s-deployment-history.md) and
+[original node setup](../../docs/content/archive/k3s-setup-history.md) preserve earlier
 observations; their unauthenticated/node-local instructions are superseded.
diff --git a/deploy/k3s/evidence/department-2026-10-09/README.md b/deploy/k3s/evidence/department-2026-10-09/README.md
@@ -2,7 +2,7 @@
 
 Evidence from the actual two-node private pilot before repository cleanup.
 The original Go/Docker/logger counts below belong to that earlier release;
-[current cleanup verification](../../../../docs/repository-cleanup.md) records
+[current cleanup verification](../../../../docs/content/repository-cleanup.md) records
 the maintained suites after their obsolete implementations were removed.
 Reports contain synthetic
 verification data and job/device IDs; no passwords, cookies or auth secrets.

diff --git a/deploy/k3s/setup-runbook.md b/deploy/k3s/setup-runbook.md
@@ -1,9 +1,9 @@
 # Current k3s setup runbook
 
-The maintained two-node runbook is [k3s setup and accelerator handoff](../../docs/k3s-setup.md).
+The maintained two-node runbook is [k3s setup and accelerator handoff](../../docs/content/k3s-setup.md).
 It covers current versions, LAN/Tailscale roles, fresh server/worker boundaries,
 NVIDIA/TT operators, diagnostics and troubleshooting.
 
-- [Tailscale and administrator SSH](../../docs/tailscale-ssh.md)
+- [Tailscale and administrator SSH](../../docs/content/tailscale-ssh.md)
 - [Application deployment and service operations](../private/README.md)
-- [Original single-node installation and worker-join history](../../docs/archive/k3s-setup-history.md)
+- [Original single-node installation and worker-join history](../../docs/content/archive/k3s-setup-history.md)
diff --git a/deploy/private/README.md b/deploy/private/README.md
@@ -1,9 +1,9 @@
 # Private deployment operations
 
-Current user/admin and architecture guide: [department rollout](../../docs/department-rollout.md).
-Execution/evidence: [rollout checklist](../../docs/department-rollout-execution.md).
-Setup: [k3s](../../docs/k3s-setup.md), [Tailscale/SSH](../../docs/tailscale-ssh.md),
-[storage](../../docs/storage.md), and [developer setup](../../docs/development.md).
+Current user/admin and architecture guide: [department rollout](../../docs/content/department-rollout.md).
+Execution/evidence: [rollout checklist](../../docs/content/department-rollout-execution.md).
+Setup: [k3s](../../docs/content/k3s-setup.md), [Tailscale/SSH](../../docs/content/tailscale-ssh.md),
+[storage](../../docs/content/storage.md), and [developer setup](../../docs/content/development.md).
 
 ## Services and persistent state
 

diff --git a/docs/README.md b/docs/README.md
@@ -1,43 +1,40 @@
-# Documentation
+# Mist Documentation
 
-Current main-branch documentation, verified against the two running machines on
-**October 9, 2026**. Addresses and versions describe this installation; adjust
-host-specific settings when provisioning another environment.
+This directory contains the documentation site for Mist, powered by **Hugo** and the **Hextra** documentation theme.
 
-## Find the right guide
+## Viewing Documentation Locally
 
-| Task | Guide |
-|---|---|
-| Sign in, manage teams, upload data, submit/download jobs | [Department operating guide](department-rollout.md) |
-| Understand services and source layout | [Architecture](architecture.md) |
-| Install/inspect k3s, join a worker, verify accelerator allocation | [k3s setup](k3s-setup.md) |
-| Connect privately and administer either host | [Tailscale and SSH](tailscale-ssh.md) |
-| Understand dataset/model pools and physical capacity | [Storage](storage.md) |
-| Build, deploy, restart or troubleshoot services | [Deployment operations](../deploy/private/README.md) |
-| Develop locally with the existing authenticated API | [Developer setup](development.md) |
-| Authenticate and submit from a terminal | [CLI](../cli/docs/setup.md) |
-| Run automated checks and read recorded live evidence | [Testing](testing.md) |
-| Maintain UI components and interactions | [Design system](design-system.md) |
-| Understand frontend architecture and backend offloading | [Frontend architecture](frontend-architecture.md) |
-| Read completed scope, exclusions and release verification | [Execution record](department-rollout-execution.md) |
-| See what repository cleanup removed and verified | [Cleanup record](repository-cleanup.md) |
-
-## Access and execution
-
-```text
-Browser / CLI → Tailscale portal :8088 → Nginx → Go API → k3s
-                                                 |       |
-                                             Better Auth + team policy
-                                                         |
-                                       CPU/NVIDIA or Tenstorrent Job
-                                                         |
-                                   scoped dataset/model NFS mounts on QuietBox
+To preview the documentation locally with live-reload:
+
+```bash
+cd docs
+hugo server
+```
+
+The site will be available at `http://localhost:1313/docs/`.
+
+To build the static site (outputting to `web-interface/public/docs` for the web portal):
+
+```bash
+cd docs
+hugo
 ```
 
-Mist login is separate from Tailscale membership and Linux SSH login. Researchers
-use the portal; administrator SSH is restricted by the installed host rules.
-The worker reaches the control plane and storage through LAN addresses.
+## Documentation Guides
 
-[Earlier plans and single-owner guides](archive/README.md) are historical only.
-Current guidance does not require Redis, an SSH session to launch a job, a public
-cloud load balancer, or permission to approve every tagged image.
+Documentation source files are located in `content/`:
+
+| Guide | Description |
+|---|---|
+| [Department operating guide](content/department-rollout.md) | Sign in, manage teams, upload data, submit/download jobs |
+| [Architecture](content/architecture.md) | Service topologies, boundaries, and codebase layout |
+| [k3s setup](content/k3s-setup.md) | Cluster setup, worker nodes, and hardware acceleration |
+| [Tailscale and SSH](content/tailscale-ssh.md) | Remote secure networking and administrator SSH |
+| [Storage](content/storage.md) | Dataset and model shared storage pools |
+| [Developer setup](content/development.md) | Local frontend and backend development |
+| [Testing](content/testing.md) | Automated tests and evidence runs |
+| [Design system](content/design-system.md) | Portal design principles and components |
+| [Frontend architecture](content/frontend-architecture.md) | UI layout and backend offloading plan |
+| [Execution record](content/department-rollout-execution.md) | Department rollout status and validation |
+| [Cleanup record](content/repository-cleanup.md) | Repository maintenance history |
+| [Historical archive](content/archive/_index.md) | Archived previous-generation guides and plans |
diff --git a/docs/content/_index.md b/docs/content/_index.md
@@ -0,0 +1,51 @@
+---
+type: docs
+cascade:
+  type: docs
+title: "Documentation Overview"
+weight: 1
+---
+
+# UTMIST Compute Platform Documentation
+
+Current main-branch documentation, verified against the two running machines on
+**October 9, 2026**. Addresses and versions describe this installation; adjust
+host-specific settings when provisioning another environment.
+
+## Find the right guide
+
+| Task | Guide |
+|---|---|
+| Sign in, manage teams, upload data, submit/download jobs | [Department operating guide](department-rollout.md) |
+| Understand services and source layout | [Architecture](architecture.md) |
+| Install/inspect k3s, join a worker, verify accelerator allocation | [k3s setup](k3s-setup.md) |
+| Connect privately and administer either host | [Tailscale and SSH](tailscale-ssh.md) |
+| Understand dataset/model pools and physical capacity | [Storage](storage.md) |
+| Build, deploy, restart or troubleshoot services | [Deployment operations](../../deploy/private/README.md) |
+| Develop locally with the existing authenticated API | [Developer setup](development.md) |
+| Authenticate and submit from a terminal | [CLI](../../cli/docs/setup.md) |
+| Run automated checks and read recorded live evidence | [Testing](testing.md) |
+| Maintain UI components and interactions | [Design system](design-system.md) |
+| Understand frontend architecture and backend offloading | [Frontend architecture](frontend-architecture.md) |
+| Read completed scope, exclusions and release verification | [Execution record](department-rollout-execution.md) |
+| See what repository cleanup removed and verified | [Cleanup record](repository-cleanup.md) |
+
+## Access and execution
+
+```text
+Browser / CLI → Tailscale portal :8088 → Nginx → Go API → k3s
+                                                 |       |
+                                             Better Auth + team policy
+                                                         |
+                                       CPU/NVIDIA or Tenstorrent Job
+                                                         |
+                                   scoped dataset/model NFS mounts on QuietBox
+```
+
+Mist login is separate from Tailscale membership and Linux SSH login. Researchers
+use the portal; administrator SSH is restricted by the installed host rules.
+The worker reaches the control plane and storage through LAN addresses.
+
+[Earlier plans and single-owner guides](archive/_index.md) are historical only.
+Current guidance does not require Redis, an SSH session to launch a job, a public
+cloud load balancer, or permission to approve every tagged image.
diff --git a/docs/architecture.md → docs/content/architecture.md b/docs/architecture.md → docs/content/architecture.md
@@ -1,3 +1,8 @@
+---
+title: "Architecture & Services"
+weight: 20
+---
+
 # Architecture
 
 Current private department installation, verified October 9, 2026.

diff --git a/docs/archive/README.md → docs/content/archive/_index.md b/docs/archive/README.md → docs/content/archive/_index.md
@@ -1,3 +1,10 @@
+---
+title: "Historical Records"
+weight: 200
+sidebar:
+  open: false
+---
+
 # Historical records
 
 These files preserve earlier design decisions and verification phases. They are
@@ -18,4 +25,4 @@ The old main is preserved on
 [`archive/main-before-k3s-20261009`](https://github.com/UTMIST/Mist/tree/archive/main-before-k3s-20261009).
 The pre-cleanup department release is commit
 [`3431ffd`](https://github.com/UTMIST/Mist/tree/3431ffdb713fac72881fc7f61f2750a82fe3f916).
-Use the [current documentation](../README.md) for this installation.
+Use the [current documentation](../_index.md) for this installation.
diff --git a/docs/archive/complete-foundation.md → docs/content/archive/complete-foundation.md b/docs/archive/complete-foundation.md → docs/content/archive/complete-foundation.md
@@ -1,6 +1,6 @@
 > **Historical record — superseded.** This text describes an earlier phase.
 > Commands and claims below are retained as history, not current setup instructions.
-> Start with the [current documentation index](../README.md) and
+> Start with the [current documentation index](../_index.md) and
 > [department operating guide](../department-rollout.md).
 
 > Current department storage and portal settings: [department rollout](../department-rollout.md).
@@ -11,7 +11,7 @@
 > **Historical account-only snapshot.** The [department rollout](../department-rollout.md)
 > supersedes these instructions: team membership, scoped folders, enforced quotas,
 > self-service images and the new portal are implemented. Use that guide and
-> [current deployment operations](../../deploy/private/README.md) for current behavior.
+> [current deployment operations](../../../deploy/private/README.md) for current behavior.
 > The remaining sections record the preceding foundation, including its limitations.
 
 Implemented on `feat/local-job-foundation`, October 8–9, 2026. This continues the
@@ -196,7 +196,7 @@ inside `/outputs` if you want them to be listed/downloaded.
 
 ## Deployment, restart and rollback
 
-See [deployment scripts](../../deploy/private/README.md). k3s server/agent, NFS and
+See [deployment scripts](../../../deploy/private/README.md). k3s server/agent, NFS and
 Nginx are system services. Kubernetes restores API/auth deployments. The frontend
 is a static release, with `/srv/mist-web/current` pointing at the active build.
 Deployment configuration, RBAC, claim templates and image policies are checked

diff --git a/docs/archive/foundation-execution-plan.md → ...tent/archive/foundation-execution-plan.md b/docs/archive/foundation-execution-plan.md → ...tent/archive/foundation-execution-plan.md
@@ -1,6 +1,6 @@
 > **Historical record — superseded.** This text describes an earlier phase.
 > Commands and claims below are retained as history, not current setup instructions.
-> Start with the [current documentation index](../README.md) and
+> Start with the [current documentation index](../_index.md) and
 > [department operating guide](../department-rollout.md).
 
 # Mist foundation execution plan