ValgulNecron · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026 · Oct 22, 2026
@@ -0,0 +1 @@
+AGENTS.md
@@ -300,8 +300,10 @@ bundle format and how to author additional modules.
 ## Contributing
 
 Design changes go through `design.pen` (Pencil) before any UI code is
-written. See [`docs/contributing.md`](docs/contributing.md) for the
-full guide: code style, test tiers, and the PR process.
+written. New contributors start with
+[Your first PR](docs/contributing.md#your-first-pr) (owning folder, local
+check and CI time per change type); [`docs/contributing.md`](docs/contributing.md)
+has the full guide: code style, test tiers, and the PR process.
 
 Translations are welcome. Translate in the browser on
 [Hosted Weblate](https://hosted.weblate.org/engage/gameplane/), or see

@@ -48,8 +48,17 @@ This document is the **first stop** for AI agents modifying or extending Gamepla
 | --- | --- |
 | Translations, language packs, localized server or module messages (i18n) | `docs/translating.md`, `specs/019-localization-language-packs/contracts/` (`pack-format.md`, `server-messages.md`, `i18n-api.md`, `module-locales.md`, `check-tool.md`), and the Internationalization section of `web/specs.md` |
 | CI test selection: which jobs, packages and tests a PR runs (`hack/ci_scope.py`, `hack/check_changed_coverage.py`, `test/e2e/suite-components.json`, the `changes` job in `.github/workflows/ci.yaml`) | `docs/contributing.md` ("How CI picks tests"), `specs/023-change-based-test-selection/contracts/` (`ci-scope-cli.md`, `suite-components.md`, `changed-coverage.md`) |
+| Add a CRD field | `operator/specs.md`, `AGENTS.md` (rule 7 and "Common workflows"), `docs/architecture.md` |
+| Add an API route | `api/specs.md`, `docs/security.md`, `web/specs.md` (client-side code in `web/src/lib/api.ts`) |
+| Add or change a dashboard screen | `web/specs.md`, `docs/layout.md` (web app), `assets/design-export/MANIFEST.md`, `docs/contributing.md` ("Design first for UI changes") |
+| Add or change a game module | `docs/module-authoring.md`, `modules/<game>/specs.md` (module repo) |
+| Change the website | `website/AGENTS.md` (submodule) |
+| Add a DB migration | `api/specs.md`, `api/internal/db/migrations/README.md` |
+| Change CI or a workflow | `docs/contributing.md` ("CI and workflows", "How CI picks tests") |
+| Decide where new code goes | `docs/layout.md` |
 
 ## How to use this index
 1. Identify the domain of your task (e.g., "Add an auth provider").
 2. Find the component handling this domain (e.g., "API Gateway").
-3. Read the documentation or resource at the path listed in the table (e.g., `api/specs.md`) to understand its architecture, boundaries, and specific rules before modifying code.
+3. Read the documentation or resource at the path listed in the table (e.g., `api/specs.md`) to understand its architecture, boundaries, and specific rules before modifying code.
+4. Adding a file, package or screen? Check `docs/layout.md` for the target folder shape of that module.
@@ -0,0 +1,10 @@
+# Archive
+
+Read-only design documents from before the design-doc rule in
+[`docs/contributing.md`](../contributing.md#where-design-docs-go). Nothing here
+is current: the features have shipped and each file names the `specs.md` that
+describes today's behavior. Do not add new files here; new changes go in
+`specs/NNN-<slug>/`.
+
+- `superpowers/`: July 2026 designs and implementation plans for console
+  protocols, action stdin, multi-category modules and wake-on-connect.
@@ -1,3 +1,5 @@
+> **Historical, superseded.** This July 2026 document is kept for reference only. The work it describes has shipped and the code may differ from it. Current behavior is described in `operator/specs.md` and `agent/specs.md`. See [docs/archive](../../README.md).
+
 # Console Protocols Implementation Plan (Phase 2)
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax.
@@ -10,7 +12,7 @@
 
 ## Global Constraints
 
-- **Phase 2 of** `docs/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md`. Read §1 first, including the 2026-07-14 correction about Satisfactory's `RunCommand`.
+- **Phase 2 of** `docs/archive/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md`. Read §1 first, including the 2026-07-14 correction about Satisfactory's `RunCommand`.
 - **Do NOT run tests or linters locally** (CLAUDE.md rule 8). CI is the source of truth. Compile checks ARE allowed and required.
 - **`go vet ./...` SKIPS files behind build tags.** After touching operator test files you MUST also run `cd operator && go vet -tags=envtest ./...`. A bad import in an `*_envtest_test.go` passes the plain check and reddens CI — this has already happened once on this feature.
 - **Sign commits**: `git -c commit.gpgsign=false commit -s -m "..."` (the `-c` MUST precede the subcommand).

@@ -1,3 +1,5 @@
+> **Historical, superseded.** This July 2026 document is kept for reference only. The work it describes has shipped and the code may differ from it. Current behavior is described in `operator/specs.md` and `gp-module/specs.md`. See [docs/archive](../../README.md).
+
 # Multi-Category Modules Implementation Plan
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
@@ -10,7 +12,7 @@
 
 ## Global Constraints
 
-- **Phase 1 of** `docs/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md`. Read the spec's §2 before starting.
+- **Phase 1 of** `docs/archive/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md`. Read the spec's §2 before starting.
 - **Do NOT run tests or linters locally.** Push to a branch; GitHub Actions is the source of truth (CLAUDE.md rule 8). A compile check (`go build ./...`, `go vet ./...`, `tsc --noEmit`) is fine and encouraged. Note `go build` skips test files — use `go vet ./...` to compile-check tests.
 - **After editing CRD Go types, run `make generate && make manifests`** and commit the regenerated `zz_generated.deepcopy.go`, `operator/config/crd/*.yaml`, `operator/config/rbac/*.yaml`, and `charts/gameplane/crds/*.yaml` in the SAME commit as the source change (CLAUDE.md rule 7). Codegen is not a test — running it locally is required.
 - **Sign every commit**: `git -c commit.gpgsign=false commit -s -m "..."` (the `-c` MUST precede the subcommand). Conventional-commit prefixes.
@@ -974,7 +976,7 @@ git push -u origin feat/multi-category-modules
 
 ```bash
 gh pr create --title "feat: modules declare multiple categories" --body "$(cat <<'EOF'
-Phase 1 of docs/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md.
+Phase 1 of docs/archive/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md.
 
 `category: string` becomes `categories: []string` across the CRDs, the bundle
 parser, the API catalog DTO, and the dashboard. A module may now belong to

@@ -1,3 +1,5 @@
+> **Historical, superseded.** This July 2026 document is kept for reference only. The work it describes has shipped and the code may differ from it. Current behavior is described in `operator/specs.md` and `agent/specs.md`. See [docs/archive](../../README.md).
+
 # Action Schema & Stdin Transport Implementation Plan (Phase 3)
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`).
@@ -10,7 +12,7 @@
 
 ## Global Constraints
 
-- **Phase 3 of** `docs/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md`. Read §3 first.
+- **Phase 3 of** `docs/archive/superpowers/specs/2026-07-14-console-protocols-categories-actions-design.md`. Read §3 first.
 - **Do NOT run tests/linters locally** (CLAUDE.md rule 8); CI is the source of truth. Compile checks (`go build`, `go vet`, `tsc --noEmit`) are allowed and required.
 - **`go vet ./...` SKIPS build-tagged files.** After operator test edits run `cd operator && go vet -tags=envtest ./...` too.
 - **After CRD type edits: `make generate && make manifests`**, commit the regenerated `zz_generated.deepcopy.go`, `operator/config/crd/*.yaml`, `operator/config/rbac/*.yaml`, `charts/gameplane/crds/*.yaml` in the SAME commit (rule 7).

@@ -1,7 +1,9 @@
+> **Historical, superseded.** This July 2026 document is kept for reference only. The work it describes has shipped and the code may differ from it. Current behavior is described in `operator/specs.md`, `agent/specs.md` and `gp-module/specs.md`. See [docs/archive](../../README.md).
+
 # Console protocols, multi-category modules, and richer quick actions
 
 **Date:** 2026-07-14
-**Status:** approved, not yet implemented
+**Status:** shipped; historical (see the banner above)
 
 ## Problem
 

@@ -1,7 +1,9 @@
+> **Historical, superseded.** This July 2026 document is kept for reference only. The work it describes has shipped and the code may differ from it. Current behavior is described in `sentinel/specs.md`. See [docs/archive](../../README.md).
+
 # Wake-on-connect for idle auto-sleep
 
 **Date:** 2026-07-24  
-**Status:** approved, not yet implemented
+**Status:** shipped; historical (see the banner above)
 
 ## Problem
 

@@ -1,5 +1,49 @@
 # Contributing
 
+This guide covers the dev loop, house rules, CI and the review process. New here?
+Start with [Your first PR](#your-first-pr): it tells you which folder owns your
+change, the one compile check to run, and how long CI takes.
+
+## Your first PR
+
+1. Fork the repo and create one branch for the change.
+2. Find the owning folder for your change in the table below. For where new
+   code goes inside a module, see [`docs/layout.md`](layout.md).
+3. Run the local check for that row only. Do not run test or lint suites
+   locally (`make test`, `make lint`, `go test`, `npm test`); CI runs them.
+4. Commit with `git commit -s` and a conventional prefix (`feat:`, `fix:`,
+   `docs:`, `chore:`, …).
+5. Open the PR and check that it has one `type:` label and one `area:` label
+   (see [Submitting a change](#submitting-a-change)).
+6. Wait for CI (times below) and fix what it reports.
+
+| Change | Owning folder | Local check | CI wall clock (2026-10-20) |
+| --- | --- | --- | --- |
+| Docs only | `docs/`, `README.md`, any `*.md` | none | 1.8 min (run 2507) |
+| Spec only | `specs/NNN-<slug>/` | none | 5.3 min (run 2525) |
+| Web only | `web/` | `cd web && npx tsc --noEmit` | 18.3 min (run 2524) |
+| One small Go service | `<module>/` (e.g. `sentinel/`, `tunnel/`) | `go build ./...` in that module | same as any Go change: 29–75 min, median 37.5 min |
+| Operator / CRD | `operator/` (types in `operator/api/v1alpha1/`) | `make generate && make manifests`, then `go build ./...` in `operator/` | same as any Go change |
+| API route | `api/` (handlers in `api/internal/handlers/`) | `go build ./...` in `api/` | same as any Go change |
+| Game module | `modules/<game>/`: PR in `GameplanePanel/module`, then a pointer bump here | `make module-validate MODULE=<game>` | 2.7 min in `GameplanePanel/module` (run 79, 2026-10-20); the bump PR here runs the docs gates |
+| Website | `website/`: PR in `GameplanePanel/website`, then a pointer bump here | `npm run build` in `website/` | 0.6 min in `GameplanePanel/website` (PR 25, 2026-10-22); the bump PR here runs the docs gates |
+
+Times are GitHub Actions wall clock for one PR run, measured 2026-10-20: runs
+2507, 2525 and 2524, and 11 Go PR runs for the median. Change-based test
+selection (`specs/023-change-based-test-selection/`) shortens Go runs as it
+lands, so treat these as upper bounds.
+
+Gates a first PR trips on:
+
+- Unsigned commits: every commit needs `git commit -s`.
+- Missing labels: one `type:` and one `area:` label on every PR.
+- Local test or lint runs: only compile checks locally; CI is the verifier.
+- UI without design: dashboard changes start in `design.pen` (Pencil), see
+  [Design first for UI changes](#design-first-for-ui-changes). Never hand-edit
+  `.pen` files.
+- Submodule work in the wrong repo: `modules/` and `website/` changes go to
+  their own repos first, then a pointer bump PR here.
+
 ## Dev loop
 
 ```sh
@@ -195,15 +239,34 @@ which applies `deploy/kind/postgres.yaml` and installs the chart with
 login rate limiter. The frozen 001–012 upgrade path is covered separately by
 `TestPostgres_MigrateFromFrozenBaseline` in the `api (postgres)` job.
 
+## Where design docs go
+
+Two homes, nothing else:
+
+- **A change** (feature, fix, cleanup) is written up in `specs/NNN-<slug>/`
+  through speckit (spec, plan, tasks, `OPEN-DECISIONS.md`). Once every task
+  is done and merged, the folder is renamed `specs/done_NNN-<slug>/`.
+- **How a module works today** is described in its `<module>/specs.md`,
+  updated in the same PR as the behavior (constitution Principle IV,
+  checked by `make check-specs`).
+
+No other folder holds designs or plans. Older designs from before this rule
+are kept read-only in [`docs/archive/`](archive/README.md).
+
 ## AI-assisted development
 
 Much of this codebase is developed with AI coding assistants (Claude
 Code). The project was started on Claude Opus 4.8 (`claude-opus-4-8`);
 since June 2026 development continues on Claude Fable 5
-(`claude-fable-5`). Agent-facing guidance lives in
-[`CLAUDE.md`](../CLAUDE.md) — keep it current when project structure or
-house rules change. All contributions, AI-assisted or not, go through
-the same review, lint, and test gates below.
+(`claude-fable-5`). Agent-facing guidance lives in one real file,
+[`AGENTS.md`](../AGENTS.md); keep it current when project structure or
+house rules change. `CLAUDE.md` is a symlink to `AGENTS.md` for tools
+that read that name, and the `website/` submodule uses the same pair
+(`AGENTS.md` real, `CLAUDE.md` link). Always edit `AGENTS.md`: with
+`git config core.symlinks false` (the Windows default) the link checks
+out as a one-line text file that only holds the name `AGENTS.md`. All
+contributions, AI-assisted or not, go through the same review, lint,
+and test gates below.
 
 ## Submitting a change