mathieusouflis · mathieusouflis · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026
diff --git a/.githooks/pre-push b/.githooks/pre-push
@@ -11,4 +11,17 @@
 # echo "Running build check..."
 # your-build-command || exit 1
 
+# ── Documentation TODOs ─────────────────────────────────────────────────
+# Non-blocking: lists template placeholder docs (docs/**/todo_*.md) that
+# still need to be filled in, per the domain × type documentation model
+# in docs/README.md. Never fails the push — just keeps the remaining work
+# visible instead of silently forgotten.
+TODO_DOCS=$(find docs -name 'todo_*.md' 2>/dev/null)
+if [ -n "$TODO_DOCS" ]; then
+  echo ""
+  echo "  Documentation still has template placeholders:"
+  echo "$TODO_DOCS" | sed 's/^/    - /'
+  echo ""
+fi
+
 exit 0
diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md
@@ -4,9 +4,8 @@
 
 Before opening an issue, please check these resources:
 
-1. **[Documentation](../docs/getting-started/README.md)** — setup guide and common commands
-2. **[FAQ](../docs/developer-guide/faq.md)** — answers to frequent questions
-3. **[Existing issues](../../issues)** — your problem may already be tracked
+1. **[Documentation](../docs/README.md)** — setup guide, conventions, and everything else, organized by domain and type
+2. **[Existing issues](../../issues)** — your problem may already be tracked
 
 ## Asking a question
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -74,3 +74,23 @@ jobs:
 
       - name: Build
         run: echo "Replace with your build command"
+
+  # ── Always applicable, regardless of language ──────────────────────────
+  # Backstop for the pre-push hook check: catches contributors who never
+  # activated .githooks. Independent of the placeholder jobs above so it
+  # keeps working after you replace lint/test/build with real steps.
+  docs-todo-check:
+    name: Documentation TODOs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: List remaining template placeholders
+        run: |
+          TODO_DOCS=$(find docs -name 'todo_*.md' 2>/dev/null || true)
+          if [ -n "$TODO_DOCS" ]; then
+            echo "$TODO_DOCS" | while read -r f; do
+              echo "::warning file=$f::Template placeholder not yet filled in — see docs/README.md"
+            done
+          fi
+          exit 0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,11 +8,9 @@ Thank you for your interest in contributing! This document explains how to get i
 
 - [Code of Conduct](#code-of-conduct)
 - [Getting Started](#getting-started)
-- [Development Setup](#development-setup)
 - [How to Contribute](#how-to-contribute)
   - [Reporting Bugs](#reporting-bugs)
   - [Suggesting Features](#suggesting-features)
-  - [Activating the commit-msg hook](#activating-the-commit-msg-hook)
   - [Submitting Code Changes](#submitting-code-changes)
 - [Commit Conventions](#commit-conventions)
 - [Pull Request Process](#pull-request-process)
@@ -39,13 +37,8 @@ This project follows the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.
    ```bash
    git remote add upstream https://github.com/your-org/your-repo.git
    ```
-4. Follow the [development setup guide](docs/getting-started/README.md)
-
----
-
-## Development Setup
-
-See [Getting Started](docs/getting-started/README.md) for the full setup guide.
+4. Follow the full setup guide: [docs/product-code/tutorials/getting-started](docs/product-code/tutorials/getting-started.md)
+5. Activate the Git hooks (one-time, recommended — validates commit messages locally before you push): [docs/team-process/how-to/activate-git-hooks](docs/team-process/how-to/activate-git-hooks.md)
 
 ---
 
@@ -72,16 +65,6 @@ Open a **Feature Request** issue with:
 
 Features that align with the project's scope and architecture are more likely to be accepted.
 
-### Activating the commit-msg hook
-
-A shell-based hook validates commit messages locally against the Conventional Commits spec. Activate it once after cloning — no runtime or dependencies required:
-
-```bash
-git config core.hooksPath .githooks
-```
-
-Commit messages are also validated in CI on every PR via GitHub Actions.
-
 ### Submitting Code Changes
 
 1. Create a branch from `main`:
@@ -92,7 +75,7 @@ Commit messages are also validated in CI on every PR via GitHub Actions.
    ```
 2. Make your changes following the [code style](#code-style) guidelines
 3. Write or update tests
-4. Run the validation suite locally (see [Development Setup](docs/getting-started/README.md))
+4. Run the validation suite locally (see [Getting Started](docs/product-code/tutorials/getting-started.md))
 5. Commit following [commit conventions](#commit-conventions)
 6. Push and open a Pull Request
 
@@ -113,7 +96,7 @@ We follow **Conventional Commits**. Each commit message should be:
 **Types:**
 
 | Type       | When to use                           |
-|------------|---------------------------------------|
+|------------|----------------------------------------|
 | `feat`     | New feature or behavior               |
 | `fix`      | Bug fix                               |
 | `refactor` | Code change with no behavior change   |
@@ -140,24 +123,26 @@ chore(deps): upgrade dependencies
 - Keep the first line under **72 characters**
 - Reference issues in the footer: `Closes #42`, `Fixes #17`
 
+Enforced automatically both locally (if hooks are activated) and in CI — see [docs/operations/concept/ci-cd-pipeline](docs/operations/concept/ci-cd-pipeline.md) for how.
+
 ---
 
 ## Pull Request Process
 
 1. **One PR per concern** — don't mix unrelated changes
 2. **Fill the PR template** — describe what changed and why
-3. **Keep diffs small** — large PRs are hard to review; split if needed
+3. **Keep diffs small** — large PRs are hard to review; split if needed. Aim for something reviewable in under 30 minutes
 4. **All CI checks must pass** before merging
-5. **Address review comments** — don't push force-merges; iterate on feedback
+5. **Address review comments** — don't force-merge, iterate on feedback
 6. **Squash or rebase** before merge if history is messy
 
-PRs are merged by maintainers once they have one approving review and all checks are green.
+PRs are merged by maintainers once they have one approving review and all checks are green — see [docs/organizational/reference/todo_tool-inventory](docs/organizational/reference/todo_tool-inventory.md) / [.github/CODEOWNERS](.github/CODEOWNERS) for who that is on this project.
 
 ---
 
 ## Code Style
 
-See [Code Style Guide](docs/developer-guide/guidelines/code-style.md) for detailed conventions.
+See [docs/product-code/reference/code-style](docs/product-code/reference/code-style.md) for detailed conventions.
 
 ---
 
@@ -169,4 +154,4 @@ Every PR should maintain or improve the existing test coverage.
 
 ## Questions?
 
-Open a [Discussion](../../discussions) or check the [FAQ](docs/developer-guide/faq.md).
+Open a [Discussion](../../discussions).
diff --git a/README.md b/README.md
@@ -5,9 +5,9 @@
 <!--
 One-time repo settings (not controlled by files in this template):
 - Enable GitHub Discussions under Settings → General → Features.
-  CONTRIBUTING.md, SUPPORT.md, the FAQ, and the issue template config
-  all link to Discussions as the place to ask questions; those links
-  404 until this is turned on.
+  CONTRIBUTING.md, SUPPORT.md, and the issue template config all link
+  to Discussions as the place to ask questions; those links 404 until
+  this is turned on.
 -->
 
 [![CI](https://github.com/your-org/your-repo/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/your-repo/actions/workflows/ci.yml)
@@ -21,8 +21,8 @@ One-paragraph description of what this project does and who it is for.
 
 - [Overview](#overview)
 - [Getting Started](#getting-started)
-- [Development](#development)
 - [Architecture](#architecture)
+- [Documentation](#documentation)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -36,60 +36,38 @@ Describe the problem this project solves, its main features, and any key design
 
 ## Getting Started
 
-### Prerequisites
-
-<!-- List the tools and versions required to run this project. -->
-
-| Tool | Version | Install |
-|------|---------|---------|
-| <!-- e.g. Node, Python, Go, Java --> | <!-- e.g. >= 22.x --> | <!-- link --> |
-
-### Installation
-
 ```bash
 git clone https://github.com/your-org/your-repo.git
 cd your-repo
-
-# Activate the commit-msg hook (optional but recommended)
-git config core.hooksPath .githooks
-
-# Copy and fill in environment variables
-cp .env.example .env
-
-# Install dependencies (replace with your package manager)
-# e.g. npm install / pip install -r requirements.txt / go mod download
+git config core.hooksPath .githooks   # activate the Git hooks — optional but recommended
+cp .env.example .env                   # then fill in the values
 ```
 
-See [docs/getting-started](docs/getting-started/README.md) for the full setup guide.
-
----
-
-## Development
-
-```bash
-# Start development server
-# Run tests
-# Lint / format
-# Build for production
-```
-
-<!-- Replace the comments above with your project's actual commands. -->
+Full setup guide (prerequisites, dependency install, dev server): [docs/product-code/tutorials/getting-started](docs/product-code/tutorials/getting-started.md).
 
 ---
 
 ## Architecture
 
-Brief description of the high-level structure. Link to detailed docs if available.
+<!-- Once this project has a real shape, replace the pointer below with a one-paragraph summary and keep the link for detail. -->
+
+See [docs/product-code/concept/todo_architecture-overview](docs/product-code/concept/todo_architecture-overview.md) — template placeholder, not yet filled in.
 
 ```
 .
 ├── src/           # Source code
-├── docs/          # Documentation
+├── docs/          # Documentation — organized by domain × type, see docs/README.md
 └── .github/       # GitHub configuration
 ```
 
 ---
 
+## Documentation
+
+All project documentation lives in [`docs/`](docs/README.md), organized by domain (what it's about) × type (what shape it takes). Start there for anything beyond this quickstart — architecture, environment variables, coding conventions, CI/CD, decisions, and more.
+
+---
+
 ## Contributing
 
 Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,15 @@
+# Documentation
+
+Organized by two axes: **domain** (what this document is about) and **type** (what shape it takes / what the reader is trying to do). A document always lives at the intersection of both — e.g. `product-code/reference/` is a lookup table about the code, `team-process/how-to/` is a step-by-step guide about how the team works.
+
+| Type → <br> Domain ↓ | Concept | How-to | Reference | Decisions | Tutorials | Runbooks |
+|---|---|---|---|---|---|---|
+| **[product-code](product-code/)** | [Architecture overview](product-code/concept/todo_architecture-overview.md) 🚧 | — | [Code style](product-code/reference/code-style.md), [Environment variables](product-code/reference/environment-variables.md) | [First decision](product-code/decisions/todo_first-architecture-decision.md) 🚧 | [Getting started](product-code/tutorials/getting-started.md) | — |
+| **[operations](operations/)** | [CI/CD pipeline](operations/concept/ci-cd-pipeline.md) | — | — | — | — | [Deployment](operations/runbooks/todo_deployment-runbook.md) 🚧 |
+| **[team-process](team-process/)** | — | [Activate Git hooks](team-process/how-to/activate-git-hooks.md) | [Commit conventions & PR process](../CONTRIBUTING.md) ⧉ | — | — | — |
+| **[organizational](organizational/)** | [Role charter](organizational/concept/todo_role-charter.md) 🚧 | — | [Tool inventory](organizational/reference/todo_tool-inventory.md) 🚧, [Code owners](../.github/CODEOWNERS) ⧉ | [Tooling choice](organizational/decisions/todo_tooling-choice.md) 🚧 | — | — |
+
+🚧 = template placeholder (`todo_` prefix), no real content yet — see the note inside each file for what to fill in and how to rename it once done.
+⧉ = lives outside `docs/` at a fixed path, see below.
+
+A few things intentionally live outside this grid, at fixed paths GitHub itself expects: [`README.md`](../README.md), [`CONTRIBUTING.md`](../CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](../CODE_OF_CONDUCT.md), [`SECURITY.md`](../SECURITY.md), [`LICENSE`](../LICENSE), and [`.github/CODEOWNERS`](../.github/CODEOWNERS). Moving them would break the platform features tied to those paths (Security tab, community profile checklist, the PR-open banner) — so unlike the rest of the grid, these stay canonical at their GitHub-required location, and the grid links *to* them rather than absorbing their content. `CONTRIBUTING.md` in particular is intentionally kept complete (commit conventions, bug/feature reporting, PR process included inline) rather than split into `docs/team-process/`, since GitHub surfaces it directly at the moment a contributor opens a PR or issue — splitting it would add a click at exactly the point someone needs the answer fastest.
diff --git a/docs/developer-guide/faq.md b/docs/developer-guide/faq.md