.claude/gitea-ship.json

@@ -2,5 +2,5 @@
   "owner": "justin",
   "version_source": "git-tag",
   "migrations": "none",
-  "notes": "Docs/content repo (course lessons + small runnable lab files). No container image, no CI build, no deploy — registry/runner/deploy fields intentionally omitted. Ship flow is branch -> commit (claude bot) -> push FQDN -> PR -> squash-merge for traceability; never push direct to main. A future GitHub copy and jpaul.me blog posts are planned but not part of this repo's pipeline."
+  "notes": "Docs/content repo (course lessons + small runnable lab files). No container image, no CI build, no deploy; registry/runner/deploy fields intentionally omitted. Ship flow is branch -> commit (claude bot) -> push FQDN -> PR -> squash-merge for traceability; never push direct to main. A future GitHub copy and jpaul.me blog posts are planned but not part of this repo's pipeline."
 }

.gitea/workflows/sync-wiki.yml

@@ -1,8 +1,8 @@
 # Render the course (single source of truth = modules/) into the Gitea wiki on
-# every push to main. The wiki is generated BUILD OUTPUT — never hand-edit it.
+# every push to main. The wiki is generated BUILD OUTPUT; never hand-edit it.
 #
 # Runs on the stack's shared `docker` runners (Linux). To actually push the wiki it
-# needs a repo secret WIKI_TOKEN with wiki write (a scoped PAT/deploy token — NOT a
+# needs a repo secret WIKI_TOKEN with wiki write (a scoped PAT/deploy token, NOT a
 # site-admin token). Until that secret exists the job skips cleanly (stays green).
 name: Sync course wiki
 on:
@@ -27,9 +27,9 @@ jobs:
           WIKI_TOKEN: ${{ secrets.WIKI_TOKEN }}
         run: |
           set -euo pipefail
-          echo "runner: $(uname -srm) — $(python3 --version 2>/dev/null || echo 'python3 missing')"
+          echo "runner: $(uname -srm); $(python3 --version 2>/dev/null || echo 'python3 missing')"
           if [ -z "${WIKI_TOKEN:-}" ]; then
-            echo "::warning::WIKI_TOKEN secret not set — skipping wiki sync. Add the secret to enable auto-sync."
+            echo "::warning::WIKI_TOKEN secret not set; skipping wiki sync. Add the secret to enable auto-sync."
             exit 0
           fi
           command -v python3 >/dev/null || { apt-get update && apt-get install -y --no-install-recommends python3; }

.github/workflows/sync-wiki.yml

@@ -1,9 +1,9 @@
 # Render the course (single source of truth = modules/) into the GitHub wiki on
-# every push to main. The wiki is generated BUILD OUTPUT — never hand-edit it.
+# every push to main. The wiki is generated BUILD OUTPUT; never hand-edit it.
 # This activates on the GitHub mirror; the Gitea copy uses .gitea/workflows/.
 #
 # Prerequisites (one-time on the mirror):
-#   1. The wiki must be INITIALIZED first — create any page once in the GitHub UI,
+#   1. The wiki must be INITIALIZED first; create any page once in the GitHub UI,
 #      otherwise the <repo>.wiki.git remote does not exist and the clone fails.
 #   2. A repo secret WIKI_TOKEN holds a PAT with wiki/repo write. The default
 #      GITHUB_TOKEN CANNOT push to the wiki repo, so a PAT is required.
@@ -34,7 +34,7 @@ jobs:
         run: |
           set -euo pipefail
           if [ -z "${WIKI_TOKEN:-}" ]; then
-            echo "::error::WIKI_TOKEN secret is not set — see this workflow's header."
+            echo "::error::WIKI_TOKEN secret is not set; see this workflow's header."
             exit 1
           fi
           repo="${GITHUB_REPOSITORY}"   # owner/repo

.gitignore

@@ -1,4 +1,4 @@
-# Generated by running the lab apps — never authored, never versioned.
+# Generated by running the lab apps; never authored, never versioned.
 __pycache__/
 *.pyc
 tasks.json

AGENTS.md

@@ -1,15 +1,15 @@
-# AGENTS.md — instructions for AI agents working in this repo
+# AGENTS.md: instructions for AI agents working in this repo
 
 > This is the committed AI instructions file for *The Workflow* course. It exists for two reasons:
 > it actually configures the agents that help author the course, **and** it is a live worked example
-> of [Module 5 — Commit the AI's Config, Not Just the Code](modules/05-commit-the-ai-config/). The
+> of [Module 5: Commit the AI's Config, Not Just the Code](modules/05-commit-the-ai-config/). The
 > filename is deliberately vendor-neutral: most agentic coding tools read a repo-level instructions
 > file, and the principle outlives any one vendor's filename. If your tool looks for a different
 > name, point it here.
 
 ## What this repo is
 
-A course that teaches IT professionals the engineering toolchain *around* AI coding — version
+A course that teaches IT professionals the engineering toolchain *around* AI coding: version
 control, collaboration, CI/CD, and the tools that extend AI into real systems. The repo is both the
 course content and a dogfooded example of the practices it teaches.
 
@@ -23,22 +23,22 @@ course content and a dogfooded example of the practices it teaches.
 
 - **Model-agnostic in principle; Claude Code as the concrete example.** The concepts and workflow
   never depend on one LLM or tool. Name the common agentic tools once, then use **Claude Code** as
-  the worked example in commands and labs — e.g. `claude --version  # sub your own agent`. Keep the
+  the worked example in commands and labs, e.g. `claude --version  # sub your own agent`. Keep the
   *concepts* vendor-neutral; use a concrete tool so steps aren't abstract. Examples must survive a
   model swap.
 - **GitHub is the default, not the requirement.** Keep hosting content provider-neutral; name the
   alternatives and the self-host track. Do not reintroduce a single specific forge as *the* answer.
 - **The dependency chain is load-bearing.** A module may assume only what precedes it. Never
-  reference a tool before its introducing module. If you think something should move, **flag it** —
+  reference a tool before its introducing module. If you think something should move, **flag it**;
   don't silently reorder.
 - **Honesty about limits.** Where a tool or analogy breaks, say so. Don't sand off the caveats.
-- **Don't pad.** This audience reads fast and trusts concrete over comprehensive. Lead with the
+- **Don't pad.** This audience reads fast and trusts the concrete over the exhaustive. Lead with the
   pain, show the command and the failure mode.
 
 ## What the course teaches about git (the reframe)
 
 This is **not** a "memorize git commands" course. The reader should finish knowing git is
-*critical*, understanding the *concepts* and the *basics*, and — above all — that they don't have to
+*critical*, understanding the *concepts* and the *basics*, and, above all, that they don't have to
 memorize commands because **the AI drives git for them**. The analogy: learn arithmetic by hand,
 then use a calculator.
 
@@ -46,14 +46,14 @@ then use a calculator.
   learner types git to build intuition. Keep that.
 - **Module 4 is the pivot.** It puts the AI in the editor/CLI. From there on the learner **directs
   the AI** to do the git work (commit, branch, merge, revert, decide what to commit) and **verifies**
-  the result — they don't type the commands by hand, and modules must not tell them to.
+  the result; they don't type the commands by hand, and modules must not tell them to.
 - **Don't re-teach basics.** Once a concept is introduced, later modules build on it through the AI;
   they don't re-explain how to create a branch, etc.
 
 ## Lesson vs. lab (keep them separate)
 
 - The **lesson / Key-concepts** section is **theory**. To show a command, show it *with example
-  output* as illustration — never instruct the reader to *run* it there.
+  output* as illustration; never instruct the reader to *run* it there.
 - **All hands-on execution lives in the lab.** The lesson must not duplicate commands the lab runs.
 
 ## Voice
@@ -63,8 +63,9 @@ No motivational filler. When in doubt, show the command and what goes wrong with
 
 **No slop (hard rules).** Don't write like an AI.
 
-- **No em-dash character (`—`) anywhere.** Use a semicolon, a period, a comma, or restructure the
-  sentence. This is absolute; self-check every edit by searching for `—` and removing each one.
+- **No em-dash character anywhere.** Use a semicolon, a period, a comma, or restructure the
+  sentence. This is absolute; self-check every edit by searching for that character and removing
+  each one.
 - **Banned words:** "prose" (say "writing"/"words"/"docs"), delve, leverage, utilize, foster,
   bolster, underscore, unveil, streamline, robust, comprehensive, pivotal, seamless, significantly,
   extremely, truly, unlock, "dive in".
@@ -86,7 +87,7 @@ No motivational filler. When in doubt, show the command and what goes wrong with
 This repo is hosted on `git.jpaul.io`. Follow the same flow the course teaches:
 
 - **Never commit directly to `main`.** Branch per module/change, open a PR, squash-merge. The PR is
-  the review gate (Module 10) even for solo work — it exists for traceability.
+  the review gate (Module 10) even for solo work; it exists for traceability.
 - **Build in dependency-chain order.** Modules 1–2 are the locked exemplars; match their tone,
   depth, and lab style.
 - **Verify before publishing volatile claims.** Anything about pricing, versions, or tool behavior
@@ -95,7 +96,7 @@ This repo is hosted on `git.jpaul.io`. Follow the same flow the course teaches:
 
 ## Don't
 
-- Duplicate or fork `the-workflow-syllabus.md` — edit it in place if structure changes.
+- Duplicate or fork `the-workflow-syllabus.md`; edit it in place if structure changes.
 - Reorder modules or break the dependency chain without flagging it.
 - Pin to a specific LLM vendor or a specific tool's config filename.
 - Write pricing/version claims from memory.

_TEMPLATE.md

@@ -9,10 +9,10 @@
   No padding. See AGENTS.md for the full conventions.
 -->
 
-# Module NN — <Title>
+# Module NN: <Title>
 
-> **<One-line hook.>** *Why this module exists for an IT pro — the pain it removes or the payoff it
-> unlocks. One sentence. Make them want to keep reading.*
+> **<One-line hook.>** *Why this module exists for an IT pro: the pain it removes or the payoff it
+> delivers. One sentence. Make them want to keep reading.*
 
 ---
 
@@ -21,13 +21,13 @@
 *Which prior modules this one depends on, named explicitly (the dependency chain). If a reader could
 parachute in here with only some of the course, say what they minimally need.*
 
-- Module X — <what it gave you that this module uses>
+- Module X: <what it gave you that this module uses>
 
 ---
 
 ## Learning objectives
 
-*3–5 outcomes, action verbs, phrased as what the reader can **do** afterward — not "understand X."*
+*3–5 outcomes, action verbs, phrased as what the reader can **do** afterward, not "understand X."*
 
 By the end of this module you can:
 
@@ -39,16 +39,16 @@ By the end of this module you can:
 
 ## Key concepts
 
-*The teaching content — **theory only**. Explain the concept and why it matters; reframe an ops
-instinct the reader already has. To show a command, show it **with example output** as illustration —
+*The teaching content: **theory only**. Explain the concept and why it matters; reframe an ops
+instinct the reader already has. To show a command, show it **with example output** as illustration;
 do NOT tell the reader to run anything here (all hands-on is the lab, and the lesson must not
-duplicate it). No "prose"/slop words. No fixed length — go as deep as the topic needs, no further.*
+duplicate it). No slop filler. No fixed length; go as deep as the topic needs, no further.*
 
 ---
 
 ## The AI angle
 
-*The module's AI-specific reason for existing — the thing that makes this more than a generic devops
+*The module's AI-specific reason for existing: the thing that makes this more than a generic devops
 lesson. Pull it from the syllabus entry for this module and make it concrete. This section is the
 differentiator; never skip it.*
 
@@ -59,7 +59,7 @@ differentiator; never skip it.*
 *The only place the reader runs things. End at a keyboard, not a quiz. State the lab language
 (Python or shell) once; provide starter files in `lab/` and reference them by path. **From Module 4
 on, the learner directs the AI agent (Claude Code as the worked example) to do the git/setup work
-and then verifies it — they don't type the commands by hand.** In Modules 1–3 the learner still
+and then verifies it; they don't type the commands by hand.** In Modules 1–3 the learner still
 runs git manually, on purpose.*
 
 **You'll need:** *<tools/setup required for this lab>*
@@ -73,14 +73,14 @@ runs git manually, on purpose.*
 
 ## Where it breaks
 
-*The honest caveats — limits, pitfalls, where a tool or analogy stops holding. This section builds
+*The honest caveats: limits, pitfalls, where a tool or analogy stops holding. This section builds
 trust with a skeptical audience. Always present; never sanded off.*
 
 ---
 
 ## Check for understanding
 
-*A short self-check or a concrete "you're done when…" criterion. Self-assessment only — no grading.*
+*A short self-check or a concrete "you're done when…" criterion. Self-assessment only, no grading.*
 
 **You're done when:** …
 
@@ -88,7 +88,7 @@ trust with a skeptical audience. Always present; never sanded off.*
 
 ## Verify-before-publish
 
-*For fast-moving topics only: what to re-check at build/publish time — versions, pricing, tool
+*For fast-moving topics only: what to re-check at build/publish time: versions, pricing, tool
 behavior, UI labels that drift. Omit this section for durable-core modules with nothing volatile.*
 
 - [ ] …

handoff.md

@@ -1,9 +1,9 @@
-# Handoff — Building Out "The Workflow"
+# Handoff: Building Out "The Workflow"
 
 This is a build-context note for a coding session (e.g. Claude Code) that will turn the course
 plan into actual lessons. **`syllabus.md` (sibling file) is the source of truth** for structure,
 module content, the thesis, and the dependency chain. Don't duplicate it here and don't re-derive
-decisions it already settled — read it first, then use this file for the *how* of building.
+decisions it already settled. Read it first, then use this file for the *how* of building.
 
 **Status:** planning is complete (27 modules across 5 units + a capstone finale). No lesson content
 exists yet. The job is to produce the lessons and hands-on labs.
@@ -17,7 +17,7 @@ exists yet. The job is to produce the lessons and hands-on labs.
   not a brand. Examples should survive a model swap.
 - **GitHub is the default, not the requirement.** Module 8 stays provider-neutral (GitHub as the
   titan; GitLab/Bitbucket/Azure DevOps/Codeberg/SourceHut and self-host options named). Earlier
-  drafts leaned on Gitea specifically — that was deliberately removed. Don't reintroduce it.
+  drafts leaned on Gitea specifically; that was deliberately removed. Don't reintroduce it.
 - **The Module 8 hosting comparison is intentionally NOT built yet.** It's marked a "planned
   artifact" because pricing/feature claims go stale. When you build it, verify current facts at that
   moment rather than writing from memory.
@@ -36,13 +36,13 @@ exists yet. The job is to produce the lessons and hands-on labs.
 
 These threads are what make it one course instead of 27 tutorials. Preserve them:
 
-- **The thesis** — the model is the cheap, swappable part; the workflow is the durable skill.
+- **The thesis:** the model is the cheap, swappable part; the workflow is the durable skill.
   Surface it periodically, and land it hard in Module 27 (evals as how you judge a model swap).
-- **The AI-specific angle** — every module in the syllabus has a reason it matters *specifically*
+- **The AI-specific angle:** every module in the syllabus has a reason it matters *specifically*
   for AI-assisted work (e.g. CI catches code that "looks right"; secrets module exists because AI
   hardcodes keys). Keep that angle front and center; it's the differentiator from a generic devops
   course.
-- **Honesty about limits** — the course repeatedly states where a tool or analogy breaks (Git isn't
+- **Honesty about limits:** the course repeatedly states where a tool or analogy breaks (Git isn't
   backup for your database; git only sees what's written to disk). This builds trust with the
   audience. Don't sand it off.
 - **The backup-and-recovery thread** spans Module 8 (backup/distribution) and Module 12
@@ -54,7 +54,7 @@ These threads are what make it one course instead of 27 tutorials. Preserve them
 
 ## Audience and voice
 
-IT professionals who are fluent in an AI chat window and comfortable with ops concepts — **not
+IT professionals who are fluent in an AI chat window and comfortable with ops concepts; **not
 beginners.** They respect rigor and detect fluff instantly. Lead with the copy-paste pain they
 already feel; reframe ops instincts they already have toward AI-assisted work; be direct and
 concrete. No padding, no motivational filler. When in doubt, show the command and the failure mode.
@@ -66,16 +66,16 @@ concrete. No padding, no motivational filler. When in doubt, show the command an
 Build every module to the same shape so the course feels coherent and so partial drafts are
 reviewable. Suggested structure for each `modules/NN-slug/README.md`:
 
-1. **Title & one-line hook** — why this module exists for an IT pro (the pain or payoff).
-2. **Prerequisites** — which prior modules it depends on (from the chain).
-3. **Learning objectives** — 3–5, action verbs, what they can *do* afterward.
-4. **Key concepts** — the actual teaching content, in prose with commands/snippets.
-5. **The AI angle** — the module's AI-specific reason for existing (pull from the syllabus entry).
-6. **Hands-on lab** — a practical exercise using AI *and* the tool together. This is a tools course;
+1. **Title & one-line hook:** why this module exists for an IT pro (the pain or payoff).
+2. **Prerequisites:** which prior modules it depends on (from the chain).
+3. **Learning objectives:** 3–5, action verbs, what they can *do* afterward.
+4. **Key concepts:** the actual teaching content, written out with commands/snippets.
+5. **The AI angle:** the module's AI-specific reason for existing (pull from the syllabus entry).
+6. **Hands-on lab:** a practical exercise using AI *and* the tool together. This is a tools course;
    every module should end at a keyboard, not a quiz. Provide starter files where useful.
-7. **Where it breaks** — limits, pitfalls, the honest caveat.
-8. **Check for understanding** — a short self-check or "you're done when…" criterion.
-9. **Verify-before-publish** — for fast-moving topics, a note on what to re-check at build time
+7. **Where it breaks:** limits, pitfalls, the honest caveat.
+8. **Check for understanding:** a short self-check or "you're done when…" criterion.
+9. **Verify-before-publish:** for fast-moving topics, a note on what to re-check at build time
    (versions, pricing, tool behavior).
 
 Before mass-producing, write **Modules 1–2 fully as the reference exemplars**, then pause for human
@@ -92,7 +92,7 @@ the-workflow/
   README.md            # course overview, derived from syllabus front matter
   syllabus.md          # source of truth (exists)
   handoff.md           # this file
-  <agent-config>       # committed AI instructions file — dogfoods Module 5 (tool-agnostic name)
+  <agent-config>       # committed AI instructions file; dogfoods Module 5 (tool-agnostic name)
   modules/
     01-the-copy-paste-problem/
       README.md         # the lesson
@@ -118,7 +118,7 @@ once; the *concepts* stay language-agnostic but the labs need something concrete
 4. Build the **durable core (Units 1–3, Modules 1–19)** in chain order.
 5. Build the **expansion zone (Units 4–5, Modules 20–27)**, flagging fast-moving topics to verify.
 6. Build the **Module 8 hosting comparison** with live verification of current facts.
-7. Build the **capstone** last — it integrates everything, so it can't be written before the parts exist.
+7. Build the **capstone** last; it integrates everything, so it can't be written before the parts exist.
 
 ---
 
@@ -135,35 +135,35 @@ itself becomes the worked example students can inspect.
 
 These were the open questions; the owner has now ruled on them. Build to these; don't re-litigate.
 
-- **Delivery medium** — **written lessons + interactive labs** (hybrid). Each module is a written
+- **Delivery medium:** **written lessons + interactive labs** (hybrid). Each module is a written
   README *and* a real hands-on lab the learner runs at the keyboard, not a quiz.
-- **Hosting/platform** — **plain repo with an optional self-hosted-forge track.** GitHub stays the
+- **Hosting/platform:** **plain repo with an optional self-hosted-forge track.** GitHub stays the
   neutral default (per the syllabus); add a parallel self-host lab track for the air-gapped/on-prem
   audience. No LMS, no static-site build required.
-- **Lab environment** — **the learner's own machine, any OS.** Don't assume a provided sandbox or
+- **Lab environment:** **the learner's own machine, any OS.** Don't assume a provided sandbox or
   cloud environment. Provide starter files where useful; keep setup OS-agnostic.
-- **Lab language** — **pick per lab, leaning Python or shell.** (This relaxes the handoff's earlier
+- **Lab language:** **pick per lab, leaning Python or shell.** (This relaxes the handoff's earlier
   "one neutral language stated once": prefer Python or shell, but use whatever fits a given lab.)
-- **Depth/length target per module** — **no fixed budget.** Let each module run as long as it needs;
+- **Depth/length target per module:** **no fixed budget.** Let each module run as long as it needs;
   rely on the shared template (not a word count) for coherence. Lead the consistency check off the
   first two modules, not just one.
-- **Assessment / certification** — **self-checks only.** Each module ends at its "you're done when…"
+- **Assessment / certification:** **self-checks only.** Each module ends at its "you're done when…"
   criterion; no graded work, no certification.
-- **Unit 4 scope** — **keep as one unit.** Leave Modules 20–23 together under the "extend the AI"
+- **Unit 4 scope:** **keep as one unit.** Leave Modules 20–23 together under the "extend the AI"
   theme; revisit only if a seam becomes obvious while building.
-- **Module 20–21 sequencing** — **keep MCP/skills at the back** so later units can build on them.
+- **Module 20–21 sequencing:** **keep MCP/skills at the back** so later units can build on them.
   The dependency chain stands as written.
-- **Capstone** — **stays a finale, not a numbered module** (27 + finale).
-- **Future Unit 6 (Adoption, Governance, Scale)** — **deferred.** Finish the 27 + capstone first;
+- **Capstone:** **stays a finale, not a numbered module** (27 + finale).
+- **Future Unit 6 (Adoption, Governance, Scale):** **deferred.** Finish the 27 + capstone first;
   Unit 6 stays parked in the syllabus notes.
 
 ---
 
 ## Don't
 
-- Duplicate or fork `syllabus.md` — edit it in place if structure changes, and keep this file's
+- Duplicate or fork `syllabus.md`; edit it in place if structure changes, and keep this file's
   cross-references in sync.
 - Reorder modules or break the dependency chain without flagging it.
 - Pin to a specific LLM vendor or a specific tool's config filename.
-- Write the hosting comparison (or any pricing/version claim) from memory — verify at build time.
-- Pad. This audience reads fast and trusts concrete over comprehensive.
+- Write the hosting comparison (or any pricing/version claim) from memory; verify at build time.
+- Pad. This audience reads fast and trusts concrete over exhaustive.

tools/README.md

@@ -1,10 +1,10 @@
 # tools/
 
-## `build_wiki.py` — render the course into a wiki
+## `build_wiki.py`: render the course into a wiki
 
 The course wiki (the "textbook" view under the **Wiki** tab) is **generated build
 output**. The single source of truth is `modules/**/README.md` + `capstone/README.md`.
-**Never hand-edit the wiki** — edits there are overwritten on the next sync.
+**Never hand-edit the wiki**; edits there are overwritten on the next sync.
 
 `build_wiki.py` is host-agnostic: it writes Markdown pages into a wiki working
 directory (`Home.md`, `_Sidebar.md`, `_Footer.md`, one page per module + capstone),
@@ -35,7 +35,7 @@ For GitHub, use `--host github` and `--web-base https://github.com/<owner>/<repo
 
 Both need, one time:
 1. an **Actions runner** attached (Gitea: Settings → Actions → Runners);
-2. a repo secret **`WIKI_TOKEN`** with wiki write (a scoped PAT/deploy token — *not*
+2. a repo secret **`WIKI_TOKEN`** with wiki write (a scoped PAT/deploy token, *not*
    a site-admin token; on GitHub the default `GITHUB_TOKEN` can't push the wiki);
 3. the wiki **initialized** once (Gitea is already initialized; on GitHub create one
    page in the UI first so `<repo>.wiki.git` exists).