Improve beginner and deep-dive docs

Author: arthur-van-acker

docs/BEGINNER-FIELD-GUIDE.md

@@ -22,7 +22,9 @@ Welcome! This all-in-one tutorial is for beginning programmers who know a bit of
 ---
 
 ## 1. Welcome to YourApp Starter {#welcome}
-YourApp Starter is a CustomTkinter-based template that shows how to ship a Windows-friendly desktop app with multiple launchers, automated installers, and docs-first guidance. It still looks like Tic Tac Toe out of the box, but the real goal is giving you a neutral codebase where you can plug in your own business rules without guessing how things hang together. For quick context, skim the project overview in `README.md` (see [README – Project Goals](../README.md#-project-goals)).
+YourApp Starter is a CustomTkinter-based template that shows how to ship a Windows-friendly desktop app with multiple launchers, automated installers, and docs-first guidance. It still looks like Tic Tac Toe out of the box, but the real goal is giving you a neutral codebase where you can plug in your own business rules without guessing how things hang together. Think of CustomTkinter as "Tkinter with a modern skin"—you still write standard Python widgets, but the toolkit adds dark mode, theming, and rounder controls. For quick context, skim the project overview in `README.md` (see [README – Project Goals](../README.md#-project-goals)).
+
+Screenshot TODO: capture a single image that shows the GUI, CLI, and desktop shortcut after you finish Section 9 so learners know what a successful setup looks like.
 
 > _Screenshot placeholder: hero shot of the CustomTkinter window + CLI side by side so viewers can see both frontends._
 
@@ -34,15 +36,23 @@ YourApp Starter is a CustomTkinter-based template that shows how to ship a Windo
 - **Screenshot placeholders:** Drop visuals wherever you see "Screenshot placeholder" callouts when you're ready to capture your own screenshots.
 - **Return path:** Every section ends with a "Back to TOC" link so you can bounce around without losing your spot.
 
+When you reach a screenshot placeholder, jot down the scenario it should capture (e.g., "Section 4 install log") and grab the image the first time you successfully finish that step. Keeping a running list now prevents a last-minute scramble before release day.
+
+**Quick glossary for recurring terms**
+- *headless mode:* Runs the GUI logic with fake widgets so CI can exercise it without a display.
+- *service mode:* An automation-first launcher that reads environment variables instead of prompting you.
+- *telemetry hooks:* Convenience functions in `src/tictactoe/controller/__init__.py` that log structured events when you flip logging env vars.
+- *CustomTkinter:* A themed fork of Tkinter that exposes the same widget concepts with a modern appearance.
+
 [Back to TOC](#table-of-contents)
 
 ## 3. Template Highlights at a Glance {#template-highlights}
 Why teams adopt this starter (see [README – Template Highlights](../README.md#-template-highlights)):
-- **One entry point, many frontends:** `python -m tictactoe` dispatches GUI, CLI, headless, or service modes from `src/tictactoe/__main__.py`.
-- **Typed configuration:** `src/tictactoe/config/gui.py` keeps fonts, colors, layout, and copy as immutable dataclasses.
-- **Installer + launcher duo:** `wheel-builder.bat` generates `installation.bat`, `tic-tac-toe-starter.vbs`, helper docs, and the signed wheel bundle under `dist/`.
-- **Headless-friendly testing:** `tictactoe.ui.gui.headless_view` mirrors the CustomTkinter widgets so GUI tests run inside CI (documented in `docs/TESTING.md`).
-- **Docs-first approach:** `docs/TEMPLATE-USAGE-GUIDE.md` and `docs/TEMPLATE-CHECKLIST.md` walk you through adopting the template in a specific order.
+- **One entry point, many frontends:** `python -m tictactoe` dispatches GUI, CLI, headless, or service modes from `src/tictactoe/__main__.py`. You never touch multiple scripts—flags or env vars pick the experience for you.
+- **Typed configuration:** `src/tictactoe/config/gui.py` keeps fonts, colors, layout, and copy as immutable dataclasses, so changing `GameViewConfig` feels like editing normal Python objects instead of ad-hoc dicts.
+- **Installer + launcher duo:** `wheel-builder.bat` generates `installation.bat`, `tic-tac-toe-starter.vbs`, helper docs, and the signed wheel bundle under `dist/`. That bundle is exactly what you zip and ship to testers.
+- **Headless-friendly testing:** `tictactoe.ui.gui.headless_view` mirrors the CustomTkinter widgets so GUI tests run inside CI (documented in `docs/TESTING.md`). Flip `TICTACTOE_HEADLESS=1` and the app behaves like the GUI even though no window opens.
+- **Docs-first approach:** `docs/TEMPLATE-USAGE-GUIDE.md` and `docs/TEMPLATE-CHECKLIST.md` walk you through adopting the template in a specific order, preventing "where do I start?" moments.
 
 > _Screenshot placeholder: collage of `dist/` folder, installer console, and desktop shortcut._
 
@@ -76,13 +86,25 @@ Everything below is straight from `README.md` plus `docs/TEMPLATE-USAGE-GUIDE.md
 
 Tip: keep `pwsh` terminals handy so PowerShell-specific scripts such as `wheel-builder.bat` and `scripts/run-ci.ps1` run without quoting gymnastics.
 
+macOS/Linux quick ref:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+python -m tictactoe --ui cli --script 0,4,8
+```
+
+If Windows blocks the activation script, run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once inside an elevated PowerShell window. Need Python first? Install from python.org, check "Add to PATH," then reopen your terminal so `python` resolves correctly.
+
 > _Screenshot placeholder: terminal session showing the activation + pip install + first run output._
 
 [Back to TOC](#table-of-contents)
 
 ## 5. Install the Packaged Build {#installer}
 Want to preview the real installer experience? Follow `docs/INSTALLATION-GUIDE.md`:
 
+> Windows-only heads up: the installer and `.bat/.vbs` scripts rely on PowerShell and the Windows desktop shell. If SmartScreen pauses the run, choose **More info > Run anyway** after verifying the script came from your build.
+
 1. **Build artifacts** (or download a release ZIP):
    ```pwsh
    .\wheel-builder.bat
@@ -96,6 +118,14 @@ Want to preview the real installer experience? Follow `docs/INSTALLATION-GUIDE.m
    - Drop `YourApp Starter.lnk` on the desktop via the VBScript launcher.
 4. Launch from the shortcut (uses `pythonw.exe` so no console window pops up).
 
+Expected log excerpt so you know things are on track:
+```
+Creating venv under %LOCALAPPDATA%\Programs\yourapp-starter-<version>
+Installing wheel ... done
+Seed data: python -m tictactoe --ui service --script 0,4,8 --quiet
+Shortcut created on Desktop
+```
+
 For an under-the-hood blow-by-blow, read `docs/INSTALLATION-TECHNICAL-DETAILS.md`—it covers everything from registry lookups for OneDrive desktops to how AppUserModelIDs keep icons tidy.
 
 > _Screenshot placeholder: SmartScreen prompt and installer console log._
@@ -124,6 +154,20 @@ Environment fallbacks keep installers and CI simple:
 - `TICTACTOE_SCRIPT`, `TICTACTOE_SCRIPT_FILE`, `TICTACTOE_AUTOMATION_*`
 - `TICTACTOE_LOGGING` (plus legacy `*_LOGGING`) enabling telemetry hooks defined in `src/tictactoe/controller/__init__.py`.
 
+Setter quick ref:
+```pwsh
+$env:TICTACTOE_HEADLESS = "1"
+python -m tictactoe
+Remove-Item Env:TICTACTOE_HEADLESS
+```
+```bash
+export TICTACTOE_HEADLESS=1
+python -m tictactoe
+unset TICTACTOE_HEADLESS
+```
+
+Think of **headless mode** as a fake GUI—it renders the same layout through `HeadlessGameView`, so screenshot tests and CI runs stay deterministic. **Service mode** skips prompts entirely and only reads environment variables, which is what the installer and smoke tests rely on. Capture a screenshot of `python -m tictactoe --list-frontends` and the shortcut properties to replace the placeholder once everything is renamed.
+
 > _Screenshot placeholder: `python -m tictactoe --list-frontends` output next to the desktop shortcut properties dialog._
 
 [Back to TOC](#table-of-contents)
@@ -142,6 +186,8 @@ Use this section as your quick-reference script when explaining the template to
 6. **Assets & tools:** `src/tictactoe/assets/` for icons/themes and `src/tictactoe/tools/theme_codegen.py` for converting JSON themes into typed configs.
 7. **Installer pipeline:** `wheel-builder.bat` → `dist/installation.bat` + VBScript launcher + helper docs.
 
+Whenever you replace the domain logic, keep returning `ExampleState`-shaped objects so the GUI bindings stay alive. Later you can rename the class once tests and UI references are updated. Telemetry hooks are just helper functions (`emit_event`, `log_action`, etc.)—calling them is optional during prototyping but useful once you need trace logs.
+
 > _Screenshot placeholder: architecture block diagram showing entry point → frontends → domain/config → installer._
 
 [Back to TOC](#table-of-contents)
@@ -155,6 +201,15 @@ Everything visual lives in `src/tictactoe/config/gui.py` (see `docs/CONFIGURATIO
 - **CLI hooks:** `python -m tictactoe --theme dark` or `--theme-file path/to/theme.json` injects payloads through `TICTACTOE_THEME_PAYLOAD`.
 - **Dataclass generation:** convert JSON to Python with `python -m tictactoe.tools.theme_codegen src/tictactoe/assets/themes/dark.json --variable-prefix brand`.
 
+Mini walkthrough:
+```bash
+cp src/tictactoe/assets/themes/dark.json tmp-theme.json
+# Edit tmp-theme.json colors/fonts...
+python -m tictactoe.tools.theme_codegen tmp-theme.json --variable-prefix demo
+python -m tictactoe --theme-file tmp-theme.json
+```
+If the app loads without complaining, your JSON validated; if not, the stack trace points to the exact field that needs fixing.
+
 > _Screenshot placeholder: side-by-side view of light vs dark theme plus a snippet of the JSON payload._
 
 [Back to TOC](#table-of-contents)
@@ -166,6 +221,14 @@ Follow `docs/TEMPLATE-CHECKLIST.md` for a linear adoption flow:
    - Update `[project]` metadata inside `pyproject.toml`.
    - Rename `src/tictactoe` to your package name and fix imports.
    - Refresh README hero copy and badges.
+
+   Quick helper commands (PowerShell shown, adapt paths as needed):
+   ```pwsh
+   Rename-Item src/tictactoe src/<your_package>
+   Get-ChildItem -Recurse -Filter *.py | ForEach-Object { (Get-Content $_.FullName) -replace "tictactoe","<your_package>" | Set-Content $_.FullName }
+   python -m pytest -m "not gui"
+   ```
+   When the test run passes, commit immediately—you just validated the rename.
 2. **Adjust config + assets**
    - Edit `tictactoe.config.gui` or drop new JSON themes.
    - Swap icons or additional files in `src/tictactoe/assets/` (wheel-builder copies the entire folder).
@@ -177,12 +240,16 @@ Follow `docs/TEMPLATE-CHECKLIST.md` for a linear adoption flow:
    - Rewrite CLI prompts or automation metadata in `tictactoe/ui/cli/main.py`.
 5. **Keep quality gates green**
    - Re-run `pwsh scripts/run-ci.ps1` after every big change to mirror the CI workflow.
+
+   Watching the script finish once gives you confidence that GitHub Actions will accept your PR later.
 6. **Regenerate installers + docs**
    - Rebuild via `wheel-builder.bat`.
    - Update `docs/INSTALLATION-GUIDE.md`, `docs/INSTALLER-CUSTOMIZATION.md`, and `docs/RELEASE.md` with your new product name and flows.
 
 > _Screenshot placeholder: checklist with checkmarks showing rename → config → UI → installer → docs._
 
+Replace the placeholder with a screenshot of your own tracking document, VS Code checklist, or whiteboard so future readers can see what progress looks like.
+
 [Back to TOC](#table-of-contents)
 
 ## 10. Automation & Headless Workflows {#automation}
@@ -193,16 +260,25 @@ Need scripted runs or CI demos without a GUI? Lean on the CLI + service pair fro
   python -m tictactoe.ui.cli.main --script 0,4,8 --output-json artifacts\automation.json --label nightly-demo
   ```
   Produces a human-readable summary plus optional JSON file and emits controller telemetry if `TICTACTOE_CLI_LOGGING=1`.
+   Example JSON payload:
+   ```json
+   {
+      "label": "nightly-demo",
+      "moves": [0,4,8],
+      "result": "player_x"
+   }
+   ```
 - **Service mode (`tictactoe.ui.service.main`)** consumes env vars:
   ```pwsh
   $env:TICTACTOE_SCRIPT = "0,4,8"
   $env:TICTACTOE_AUTOMATION_OUTPUT = "$PWD\artifacts\service.json"
   python -m tictactoe --ui service --quiet
   ```
+   Remember to clean up afterward with `Remove-Item Env:TICTACTOE_SCRIPT, Env:TICTACTOE_AUTOMATION_OUTPUT` (PowerShell) or `unset` (bash) so later runs do not inherit old values.
 - **Headless GUI** just works by launching `python -m tictactoe --ui headless` or setting `TICTACTOE_HEADLESS=1`; the shim lives in `tictactoe/ui/gui/headless_view.py`.
 - **Telemetry hooks** (see `tictactoe/controller/__init__.py`) let every frontend log events once you flip `TICTACTOE_LOGGING=1`—great for installers or automated smoke tests.
 
-> _Screenshot placeholder: log output from CLI automation plus a JSON summary snippet._
+> _Screenshot placeholder: log output from CLI automation plus a JSON summary snippet._ ← Capture the CLI summary text next to the JSON file in your editor once you have the automation folder in place.
 
 [Back to TOC](#table-of-contents)
 
@@ -227,6 +303,8 @@ Need scripted runs or CI demos without a GUI? Lean on the CLI + service pair fro
 4. **Smoke test** the generated installer on a clean Windows profile.
 5. **Zip and publish** `dist/` as the release payload (see `docs/RELEASE.md#6-publish-github-release`).
 
+`--ci` skips pauses and writes to `%TEMP%` so GitHub Actions can run unattended; the plain invocation prompts you and installs under `%LOCALAPPDATA%`. Both commands require Windows, PowerShell, and access to the Windows desktop shell (no Server Core). Capture a screenshot of the final `dist/` explorer window before zipping so teammates know exactly which files to ship.
+
 > _Screenshot placeholder: PowerShell transcript from `wheel-builder.bat` plus the resulting `dist/` explorer window._
 
 [Back to TOC](#table-of-contents)
@@ -249,6 +327,12 @@ Everything you need lives in `docs/TESTING.md`, but here are the highlights:
 - **Coverage** is optional but easy: `python -m pytest --cov=tictactoe --cov-report=term-missing`.
 - **Helper commands** (from `docs/TESTING.md#16-quick-reference-commands`) keep newcomers productive.
 
+If Tk libraries are missing on Windows, install the official Python build (it bundles Tk) or set `TICTACTOE_HEADLESS=1` before running GUI tests. macOS/Linux users should install the system `tk` package (`brew install python-tk` or distro equivalent). Typical pytest success output:
+```
+==================== 12 passed, 2 skipped in 5.23s ====================
+```
+Seeing green like that means you can move on to packaging with confidence.
+
 > _Screenshot placeholder: VS Code test explorer or pytest output highlighting GUI vs non-GUI markers._
 
 [Back to TOC](#table-of-contents)
@@ -264,6 +348,8 @@ Everything you need lives in `docs/TESTING.md`, but here are the highlights:
 - **GitHub Actions:** `.github/workflows/ci.yml` mirrors the same steps (lint, type, pytest, build wheel). Use the sample matrix in `docs/CI-CD.md` if you want tox-driven jobs.
 - **Release workflow:** `docs/RELEASE.md` describes tagging, uploading `dist/`, and notifying users. When you need extra installer tweaks, capture them in `docs/INSTALLER-CUSTOMIZATION.md` for future maintainers.
 
+Open `.github/workflows/ci.yml` to see the exact job order; the file sits at the repo root so you can tweak it without hunting around. To re-run a workflow manually, head to GitHub → Actions tab → pick the `CI` workflow → **Run workflow**. Grab a screenshot of the green workflow summary for this section once your branch passes.
+
 > _Screenshot placeholder: CI pipeline diagram or GitHub Actions run summary._
 
 [Back to TOC](#table-of-contents)
@@ -278,6 +364,15 @@ Common issues and quick fixes (see `docs/TROUBLESHOOTING.md` for the full FAQ):
 
 > _Screenshot placeholder: snippet of `docs/TROUBLESHOOTING.md` or an error dialog with a fix overlay._
 
+Quick matcher table (copy into your notes as you debug):
+
+| Symptom | Likely cause | Fast fix |
+| --- | --- | --- |
+| `Activate.ps1 cannot be loaded because running scripts is disabled on this system.` | Execution policy blocking venv activation | `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` then retry |
+| `ModuleNotFoundError: No module named 'tictactoe'` after rename | Imports still reference old package name | Run a project-wide search/replace for `tictactoe` and rerun tests |
+| SmartScreen warns "unrecognized app" when running installer | Unsigned local build | Click **More info > Run anyway** after verifying hash/source |
+| GUI launch fails with `No module named '_tkinter'` | Tk runtime missing | Install official Python or system `tk` package, or force headless mode |
+
 [Back to TOC](#table-of-contents)
 
 ## 15. Next Steps & Additional Resources {#next-steps}
@@ -293,4 +388,6 @@ Here’s where to go once you finish this guide:
 
 > _Screenshot placeholder: summary graphic highlighting the key links + "Happy Building!" message._
 
+Suggested next-study order once this guide clicks: `docs/ARCHITECTURE.md` → `docs/CONFIGURATION.md` → `docs/TEMPLATE-USAGE-GUIDE.md` → `docs/RELEASE.md`. Pair that with two hands-on tasks—(1) create a brand-new theme JSON, and (2) rerun `scripts/run-ci.ps1`—so the knowledge sticks.
+
 [Back to TOC](#table-of-contents)

docs/CI-CD.md

@@ -51,6 +51,8 @@ jobs:
 
 > The repository’s checked-in `.github/workflows/ci.yml` currently mirrors the `run-ci` scripts by running the linters/type checker/pytest directly instead of invoking tox. Use whichever style matches your team’s conventions.
 
+Need to tweak the workflow? Open `.github/workflows/ci.yml` at the repo root—no scaffolding tools required. To re-run it manually, visit GitHub → **Actions** → select the `CI` workflow → **Run workflow**, then pick the target branch. Capture a screenshot or permalink of the passing run whenever you document release steps so teammates can see the expected job order.
+
 ## Extending to Release Pipelines
 - Add a `release` job that depends on `tests`, runs `wheel-builder.bat` (or PowerShell equivalent on Windows runners), and uploads `dist/` as an artifact.
 - Gate GitHub Releases on successful CI by requiring the workflow status check.

docs/CONFIGURATION.md

@@ -128,6 +128,24 @@ config = deserialize_game_view_config(theme_dict)
 
 When the GUI (or headless GUI) launches, it inspects `TICTACTOE_THEME_PAYLOAD` and rebuilds the dataclasses via `deserialize_game_view_config`. This keeps installers and CI jobs theme-aware without touching widget code.
 
+### Hands-on Theme Edit (5-minute loop)
+1. Copy one of the shipped themes:
+    ```bash
+    cp src/tictactoe/assets/themes/dark.json tmp-theme.json
+    ```
+2. Edit colors, fonts, or copy inside `tmp-theme.json` (VS Code keeps JSON validation on).
+3. Validate live in the app:
+    ```bash
+    python -m tictactoe --theme-file tmp-theme.json
+    ```
+    If the GUI starts without stack traces, the JSON matches the schema. Errors pinpoint the first mismatched field.
+4. Promote the JSON to typed Python code:
+    ```bash
+    python -m tictactoe.tools.theme_codegen tmp-theme.json --variable-prefix demo
+    ```
+    The command prints a `demo_theme` dataclass assignment you can paste into `config/gui.py` or tests.
+5. Commit both the JSON (if you plan to ship it) and the generated Python so future contributors can tweak either side.
+
 ## Sample JSON Themes & Dataclass Converter
 
 Need a starting point for custom palettes? The repository now ships JSON payloads under `src/tictactoe/assets/themes/` (`light.json`, `dark.json`, `enterprise.json`). Feed those files into the new converter CLI to emit ready-to-paste `GameViewConfig` assignments: