docs: streamline navigation and adopt Go 1.26

.agents/skills/prepare-iteration/SKILL.md

@@ -5,12 +5,12 @@ description: "Use when completing an OpsQuest iteration, release-sized milestone
 
 # Prepare an OpsQuest iteration
 
-Use [references/iteration-template.md](references/iteration-template.md) for the final `docs/history/iterations/iteration-NN.md`. The report is an evidence record, so include only commands and results actually observed.
+Use [references/iteration-template.md](references/iteration-template.md) for the final `project/history/iterations/iteration-NN.md`. The report is an evidence record, so include only commands and results actually observed.
 
 ## Workflow
 
 1. Establish the milestone boundary.
-   - Read the reports in `docs/history/iterations/`, README, `internal/cli/app.go`, and the milestone request.
+   - Read the reports in `project/history/iterations/`, README, `internal/cli/app.go`, and the milestone request.
    - Identify the next iteration number and intended version. Do not change version strings or roadmap claims unless the milestone requires it.
 
 2. Review the complete change set.
@@ -30,7 +30,7 @@ Use [references/iteration-template.md](references/iteration-template.md) for the
    - Use individual targets such as `make build` or `make smoke-test` only to isolate a failure or when the full target cannot run. Verify the built release binary with `./bin/opsquest version` when the version changes.
    - Record exact commands, exit results, and relevant observed output. Never infer that an unrun check passed because a related command succeeded.
 
-5. Write `docs/history/iterations/iteration-NN.md`.
+5. Write `project/history/iterations/iteration-NN.md`.
    - Summarize delivered user behavior, architecture or tooling changes, and tests without copying commit history.
    - Describe compatibility and safety considerations, including intentionally unchanged formats or boundaries.
    - List validation results actually observed and remaining work that is genuinely outside the iteration.

.github/workflows/codeql.yml

@@ -1,49 +1,49 @@
-name: CodeQL
+# name: CodeQL
 
-on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
-  schedule:
-    - cron: "23 4 * * 1"
-  workflow_dispatch:
+# on:
+#   push:
+#     branches:
+#       - main
+#   pull_request:
+#     branches:
+#       - main
+#   schedule:
+#     - cron: "23 4 * * 1"
+#   workflow_dispatch:
 
-permissions:
-  contents: read
+# permissions:
+#   contents: read
 
-concurrency:
-  group: codeql-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
-  cancel-in-progress: true
+# concurrency:
+#   group: codeql-${{ github.event_name }}-${{ github.event.pull_request.number || github.ref }}
+#   cancel-in-progress: true
 
-jobs:
-  analyze:
-    name: Analyze Go
-    runs-on: ubuntu-latest
-    timeout-minutes: 20
-    permissions:
-      actions: read
-      contents: read
-      security-events: write
-    steps:
-      - name: Check out repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-        with:
-          persist-credentials: false
-      - name: Set up Go
-        uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
-        with:
-          go-version-file: go.mod
-          cache: true
-          cache-dependency-path: go.sum
-      - name: Initialize CodeQL
-        uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
-        with:
-          languages: go
-          build-mode: manual
-      - name: Build analyzed code
-        run: make build
-      - name: Analyze
-        uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
+# jobs:
+#   analyze:
+#     name: Analyze Go
+#     runs-on: ubuntu-latest
+#     timeout-minutes: 20
+#     permissions:
+#       actions: read
+#       contents: read
+#       security-events: write
+#     steps:
+#       - name: Check out repository
+#         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+#         with:
+#           persist-credentials: false
+#       - name: Set up Go
+#         uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+#         with:
+#           go-version-file: go.mod
+#           cache: true
+#           cache-dependency-path: go.sum
+#       - name: Initialize CodeQL
+#         uses: github/codeql-action/init@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4
+#         with:
+#           languages: go
+#           build-mode: manual
+#       - name: Build analyzed code
+#         run: make build
+#       - name: Analyze
+#         uses: github/codeql-action/analyze@e4fba868fa4b1b91e1fdab776edc8cfbe6e9fb81 # v4

.github/workflows/docs.yml

@@ -11,6 +11,7 @@ on:
       - "requirements-docs.txt"
       - "Makefile"
       - "README.md"
+      - "scripts/check-docs.sh"
   pull_request:
     branches:
       - main
@@ -21,6 +22,7 @@ on:
       - "requirements-docs.txt"
       - "Makefile"
       - "README.md"
+      - "scripts/check-docs.sh"
   workflow_dispatch:
 
 permissions:

AGENTS.md

@@ -1,6 +1,6 @@
 # OpsQuest agent guide
 
-OpsQuest is a Go 1.22 CLI game with 23 in-memory Linux missions and six optional Docker Foundations labs. Linux player commands stay inside the teaching shell. Docker input is parsed into a deliberately small command subset that can affect only disposable, OpsQuest-labeled resources. Kubernetes remains future scope unless a task explicitly adds it.
+OpsQuest is a Go 1.26 CLI game with 23 in-memory Linux missions and 6 optional Docker Foundations labs. Linux player commands stay inside the teaching shell. Docker input is parsed into a deliberately small command subset that can affect only disposable, OpsQuest-labeled resources. Kubernetes remains future scope unless a task explicitly adds it.
 
 ## Repository map
 
@@ -14,10 +14,11 @@ OpsQuest is a Go 1.22 CLI game with 23 in-memory Linux missions and six optional
 - `internal/dockerlab`: optional Docker capability detection, typed teaching commands, isolated resource lifecycle, and Docker observations.
 - `internal/profile`: versioned profile model and atomic JSON persistence.
 - `scripts`: deterministic repository checks used by both Make and CI.
-- `docs/game`: current curriculum and learning-design documentation.
+- `docs/game`: learning principles and the high-level product explanation.
 - `docs/technical`: current architecture, safety, and implementation diagrams.
 - `docs/roadmap`: explicitly labeled proposals and unfinished improvements.
-- `docs/history/iterations`: observed delivery reports for completed product iterations.
+- `project/history/iterations`: repository-only delivery reports for completed product iterations.
+- `project/decisions`: implemented project decisions that should not appear on the public site.
 - `mkdocs.yml` and `.github/workflows/docs.yml`: pinned Zensical navigation, strict site validation, and GitHub Pages delivery.
 
 ## Working workflow
@@ -56,7 +57,7 @@ Safe local edits, tests, builds, and documentation updates within the requested
 - Normal local gate: `make check`.
 - Comprehensive gate, including race detection: `make check-all`.
 
-Update README command lists, mission counts, safety notes, or roadmap claims when behavior changes. Use `$prepare-iteration` for a release-sized milestone and base its `docs/history/iterations/iteration-NN.md` report on the supplied template.
+Update README command lists, mission counts, safety notes, or roadmap claims when behavior changes. Use `$prepare-iteration` for a release-sized milestone and base its `project/history/iterations/iteration-NN.md` report on the supplied template.
 
 ## Definition of done
 

CHANGELOG.md

@@ -6,7 +6,6 @@
 ### Features
 
 * infrastructure to define repo guidelines and secrets workflow ([c8d2792](https://github.com/Aleksandergreg/go-cli-tool/commit/c8d27926acccdd0a276324cfcfd8dbe79ce99eaf))
-* infrastructure to define repo guidelines and secrets workflow ([857955f](https://github.com/Aleksandergreg/go-cli-tool/commit/857955f034d6f82134443d03ef149e92d62a4fe7))
 
 
 ### Bug Fixes
@@ -33,17 +32,11 @@
 ### Features
 
 * add guided world progression and refresh terminal UX ([e709111](https://github.com/Aleksandergreg/go-cli-tool/commit/e709111cc3dc8cda9492bbc83622bbd1213005e0))
-* add guided world progression and refresh terminal UX ([e709111](https://github.com/Aleksandergreg/go-cli-tool/commit/e709111cc3dc8cda9492bbc83622bbd1213005e0))
-* add guided world progression and refresh terminal UX ([fe8b97e](https://github.com/Aleksandergreg/go-cli-tool/commit/fe8b97e6629e533c58c7dc0263b6c7b5de19c2d9))
-* release please, codesql and go releaser ([b892c59](https://github.com/Aleksandergreg/go-cli-tool/commit/b892c59fc09b2eb15e9baf4f263a0a1df83a5edd))
 * release please, codesql and go releaser ([b892c59](https://github.com/Aleksandergreg/go-cli-tool/commit/b892c59fc09b2eb15e9baf4f263a0a1df83a5edd))
-* release please, codesql and go releaser ([71e7ebf](https://github.com/Aleksandergreg/go-cli-tool/commit/71e7ebf62cbd291d51b1760694ce12f5259d4555))
 
 
 ### Bug Fixes
 
 * **cli:** continue after selected mission completion ([446caaf](https://github.com/Aleksandergreg/go-cli-tool/commit/446caaf1b8232abb0f6f9f97568463e2068cf0b0))
 
-## Changelog
-
 OpsQuest release notes are generated from Conventional Commits by Release Please.

Makefile

@@ -2,7 +2,7 @@ GORELEASER ?= goreleaser
 TOFU ?= tofu
 ZENSICAL ?= zensical
 
-.PHONY: build test race vet check-agent-docs validate-missions smoke-test docker-integration orbstack-integration docs-build docs-check docs-serve tofu-check release-check release-snapshot check check-all run clean
+.PHONY: build test race vet check-agent-docs check-docs validate-missions smoke-test docker-integration orbstack-integration docs-build docs-check docs-serve tofu-check release-check release-snapshot check check-all run clean
 
 build:
 	mkdir -p bin
@@ -11,6 +11,9 @@ build:
 check-agent-docs:
 	./scripts/check-agent-docs.sh
 
+check-docs:
+	./scripts/check-docs.sh
+
 validate-missions:
 	./scripts/validate-missions.sh
 
@@ -31,11 +34,11 @@ docker-integration:
 orbstack-integration:
 	DOCKER_CONTEXT=orbstack OPSQUEST_DOCKER_TEST=1 go test ./internal/dockerlab -run Integration -count=1
 
-docs-build:
+docs-build: check-docs
 	@command -v $(ZENSICAL) >/dev/null 2>&1 || { echo "error: Zensical is required; install requirements-docs.txt in a Python 3.10+ virtual environment" >&2; exit 1; }
 	$(ZENSICAL) build --clean
 
-docs-check:
+docs-check: check-docs
 	@command -v $(ZENSICAL) >/dev/null 2>&1 || { echo "error: Zensical is required; install requirements-docs.txt in a Python 3.10+ virtual environment" >&2; exit 1; }
 	$(ZENSICAL) build --clean --strict
 
@@ -56,7 +59,7 @@ release-check:
 release-snapshot: release-check
 	$(GORELEASER) release --snapshot --clean
 
-check: check-agent-docs test vet build smoke-test
+check: check-agent-docs check-docs test vet build smoke-test
 
 check-all: check race
 

README.md

@@ -30,7 +30,7 @@ OpsQuest validates the result, not a prescribed command. Equivalent supported so
 ## What is included
 
 - 23 Linux missions across four ordered learning worlds
-- Six optional, disposable Docker Foundations missions
+- 6 optional, disposable Docker Foundations missions
 - An isolated in-memory filesystem, environment, process table, and archives
 - Quote-aware globs and variables, pipelines, redirection, and command history
 - A compact virtual `vi` and bounded virtual shell scripts
@@ -40,7 +40,7 @@ OpsQuest validates the result, not a prescribed command. Equivalent supported so
 
 ## Quick start
 
-OpsQuest requires Go 1.22 or newer.
+OpsQuest requires Go 1.26 or newer when building from source.
 
 ```console
 $ go run ./cmd/opsquest play
@@ -68,7 +68,9 @@ $ opsquest achievements
 $ opsquest doctor
 ```
 
-The complete player guide covers [installation and first play](docs/play/quick-start.md), [mission behavior](docs/play/how-missions-work.md), and [controls and commands](docs/play/controls-and-commands.md).
+The complete player guide covers [installation and first play](docs/play/quick-start.md),
+[missions and progress](docs/play/missions-and-progress.md), and
+[controls and commands](docs/play/controls-and-commands.md).
 
 ## Optional Docker Foundations
 
@@ -80,15 +82,10 @@ $ opsquest doctor
 $ opsquest play 20
 ```
 
-On macOS, you can direct both setup and gameplay to OrbStack without changing your global Docker context:
-
-```console
-$ DOCKER_CONTEXT=orbstack docker pull docker.io/library/busybox@sha256:73aaf090f3d85aa34ee199857f03fa3a95c8ede2ffd4cc2cdb5b94e566b11662
-$ DOCKER_CONTEXT=orbstack opsquest doctor
-$ DOCKER_CONTEXT=orbstack opsquest play 20
-```
-
-OpsQuest never pulls the image automatically. The OrbStack context uses the same constrained Docker integration and cleanup path as every other compatible engine. See [Docker Foundations](docs/play/docker-foundations.md) for setup details, the teaching subset, and the isolation boundary.
+OpsQuest never pulls the image automatically. See
+[Docker Foundations](docs/play/docker-foundations.md) for Docker Desktop,
+Docker Engine, and OrbStack setup, plus the teaching subset and isolation
+boundary.
 
 ## Safety model
 
@@ -103,10 +100,12 @@ Read [Sandbox and safety](docs/technical/sandbox-and-safety.md) for trust bounda
 The hosted site is published at [aleksandergreg.github.io/go-cli-tool](https://aleksandergreg.github.io/go-cli-tool/). Its source is organized by purpose:
 
 - [Play OpsQuest](docs/play/README.md) — player setup, missions, controls, worlds, and Docker
-- [Game and learning](docs/game/README.md) — learning philosophy, curriculum, mission design, and progression
-- [Technical](docs/technical/README.md) — architecture, safety, mission content, profiles, and contribution workflows
-- [Roadmap](docs/roadmap/README.md) — delivered foundations and proposed improvements
-- [Delivery history](docs/history/README.md) — point-in-time iteration evidence
+- [How OpsQuest works](docs/game/README.md) — learning philosophy, architecture, and safety
+- [Contribute](docs/technical/README.md) — quality gates, mission authoring, and compatibility
+- [Roadmap](docs/roadmap/README.md) — explicitly proposed, unshipped work
+
+Point-in-time iteration evidence stays in the repository-only
+[delivery history](project/history/README.md).
 
 ## Project structure
 
@@ -121,6 +120,7 @@ internal/profile/   XP, ranks, achievements, and atomic persistence
 internal/sandbox/   Virtual filesystem, shell parser, and commands
 internal/dockerlab/ Optional, label-scoped Docker adapter
 docs/               Zensical documentation source and diagrams
+project/            Repository-only decisions and delivery history
 ```
 
 ## Development
@@ -130,6 +130,7 @@ The repository [agent guide](AGENTS.md) defines safety invariants, package bound
 ```console
 $ make check             # tests, mission validation, vet, build, and smoke test
 $ make check-all         # normal gate plus race detection
+$ make check-docs        # dependency-free documentation consistency checks
 $ make docker-integration
 $ make orbstack-integration
 $ make docs-check        # strict Zensical build and link validation
@@ -144,13 +145,22 @@ Task-specific Codex workflows live in [`.agents/skills`](.agents/skills): `$add-
 
 ## Releases and security
 
-Release Please maintains semantic-version release pull requests from Conventional Commits. Merging a release pull request creates the tag and GitHub release; GoReleaser attaches checksummed macOS, Linux, and Windows archives. Repository-managed CodeQL analyzes the real Go build path. GitHub settings and rulesets are declared under [`infra/github`](infra/github); the [governance runbook](docs/technical/repository-governance.md) defines the credential, state, and reviewed-apply boundaries.
+Release Please maintains semantic-version release pull requests from
+Conventional Commits. Merging a release pull request creates the tag and GitHub
+release; GoReleaser attaches checksummed macOS, Linux, and Windows archives.
+Repository-managed CodeQL analyzes the real Go build path. GitHub settings and
+rulesets are declared under [`infra/github`](infra/github); its
+[governance runbook](infra/github/GOVERNANCE.md) defines the credential, state,
+and reviewed-apply boundaries.
 
-See [CHANGELOG.md](CHANGELOG.md), [GitHub Releases](https://github.com/Aleksandergreg/go-cli-tool/releases), and the [CI/CD roadmap](docs/roadmap/ci-cd.md). Third-party module licenses are recorded in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+See [CHANGELOG.md](CHANGELOG.md), [GitHub Releases](https://github.com/Aleksandergreg/go-cli-tool/releases),
+and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
 
 ## Roadmap
 
-Docker campaign increments, distribution improvements, and longer-term ideas are tracked in the [project roadmap](docs/roadmap/README.md). Kubernetes remains future scope.
+Docker campaign increments, distribution improvements, and longer-term ideas
+are tracked in the [roadmap](docs/roadmap/README.md). Kubernetes remains future
+scope.
 
 ## License
 

docs/README.md

@@ -4,7 +4,7 @@ audience: players and contributors
 status: current
 ---
 
-# OpsQuest documentation
+# OpsQuest
 
 OpsQuest is **Duolingo meets a terminal sandbox**: a command-line game where you learn Linux and container operations by resolving fictional production incidents.
 
@@ -19,17 +19,18 @@ The game describes an observable objective, gives you a disposable environment,
 | I want to… | Start here |
 | --- | --- |
 | Install the game and begin a mission | [Quick start](play/quick-start.md) |
-| Understand objectives, hints, and navigation | [How missions work](play/how-missions-work.md) |
+| Understand objectives, hints, routes, and rewards | [Missions, hints, and progress](play/missions-and-progress.md) |
 | Look up terminal controls and supported commands | [Controls and commands](play/controls-and-commands.md) |
-| See what every world and mission teaches | [Curriculum and mission map](game/curriculum.md) |
+| See what every world and mission teaches | [Mission map](play/mission-map.md) |
 | Understand the implementation | [Technical architecture](technical/architecture.md) |
 | Review the isolation guarantees | [Sandbox and safety](technical/sandbox-and-safety.md) |
+| Contribute a change | [Contributing and quality gates](technical/contributing.md) |
 | Explore planned improvements | [Roadmap](roadmap/README.md) |
 
 ## Current scope
 
 - 23 Linux missions across four ordered learning worlds
-- Six optional Docker Foundations missions
+- 6 optional Docker Foundations missions
 - Outcome-based validation rather than one required command transcript
 - An in-memory filesystem, process table, environment, archives, editor, and shell scripts
 - Persistent XP, ranks, command practice, hints, completions, and achievements
@@ -43,6 +44,8 @@ Read [Sandbox and safety](technical/sandbox-and-safety.md) for the complete trus
 
 ## About these docs
 
-This site is built from the same Markdown and diagram sources reviewed with the code. Current behavior lives under `play/`, `game/`, and `technical/`; proposals live under `roadmap/`; point-in-time delivery evidence lives under `history/`.
-
-Contributors should start with [Contributing and quality gates](technical/contributing.md).
+This site is built from Markdown and diagram sources reviewed with the code.
+Player guidance, current design, and contributor reference are public here.
+Forward-looking work is explicitly labeled in the roadmap. Internal decisions,
+infrastructure runbooks, and iteration evidence remain in the repository rather
+than the public site.