Skip to content

docs: teach the stack the repositories actually run, and add AGENTS.md - #41

Merged
fmind merged 1 commit into
mainfrom
docs/teach-the-current-stack
Aug 10, 2026
Merged

docs: teach the stack the repositories actually run, and add AGENTS.md#41
fmind merged 1 commit into
mainfrom
docs/teach-the-current-stack

Conversation

@fmind

@fmind fmind commented Aug 10, 2026

Copy link
Copy Markdown
Collaborator

What

Rewrites the chapters that described the previous stack, and adds the AGENTS.md coverage the course never had.

Why

  • Chapter 4.4 taught trivy config . — which silently defers to a TRIVY_CONFIG environment variable and runs only one of the four scanners trivy.yaml declares.
  • Several chapter-4 pages told readers to install tools with uv add --group check, while all four repositories use a single dev group. Following the course literally produced a project whose uv sync omitted ruff and ty.
  • Chapter 5.3 reproduced the package's ci.yml verbatim, including the git diff --exit-code assertion that has since been replaced.
  • Chapter 5.1's task table listed a watch task the package does not define, and omitted all.
  • The course had zero coverage of AGENTS.md while all four repositories ship one.

How

  • 6.2 now covers AGENTS.md properly: what the format is and that the Agentic AI Foundation stewards it under the Linux Foundation, the README-for-humans / AGENTS.md-for-agents split with a comparison table, what belongs in each, a complete skeleton, the boundary where its authority stops (it guides, it does not enforce), and the anti-drift lesson from the vendored skill copies the package used to ship.
  • 5.1 documents all as the named gate, mise.lock, and run_auto_install = false.
  • 5.2 explains why the hook priorities jump by ten (lefthook orders alphabetically) and the three-tier secret scan.
  • 5.3 carries the real hardened workflows, why the job is named checks, why the porcelain assertion beats git diff, that a job-level permissions: block replaces rather than merges, and a new section on linting workflows with actionlint and zizmor.
  • 5.4 wires hadolint to check:dockerfile.
  • 5.5 / 5.6 teach MLflow on SQLite — including that MLflow 3.14 already defaults to it — and the session-scoped migrated-database fixture.
  • 4.1 / 4.2 / 4.4 / 4.5 cover Ruff 0.16, the coverage gate, and the corrected security tooling.

Also pins the security workflow runner to ubuntu-24.04 so it matches CI.

Test plan

  • mise run all — exit 0; mkdocs build --strict green with no WARNING or ERROR lines.
  • A separate review pass re-verified every command, flag, path, task name, and version literal in the diff against the reference repositories, and fixed nine defects: two wrong claims about mise reading .python-version (it does not by default — uv does), a wrong dependency-bump count, an off-by-one rule-family count, a task-table row missing a check, an abridged AGENTS.md quote that contradicted two other chapters, a fabricated line number in tool output, and two cross-chapter contradictions in 6.3.

The chapters described the previous stack. Every command, flag, path, and
version in the rewritten pages was read out of the reference implementations.

- 6.2 gains substantial AGENTS.md coverage, which the course had none of: what
  the format is and that the Agentic AI Foundation stewards it under the Linux
  Foundation, the README-for-humans / AGENTS.md-for-agents split, what belongs
  in each, a complete skeleton, the boundary where its authority stops, and the
  drift lesson from the vendored skill copies the package used to ship
- 5.1 documents the `all` task as the named gate, mise.lock, and
  run_auto_install; the task table drops a `watch` task the package never had
- 5.2 explains the 10/20/30 hook priorities and the three-tier secret scan
- 5.3 carries the real hardened workflows, why the job is named `checks`, why
  the porcelain assertion beats git diff, job-level permissions replacing rather
  than merging, and a new section on linting workflows with actionlint + zizmor
- 5.4 wires hadolint to check:dockerfile and explains the pinned image and the
  numeric user
- 5.5 and 5.6 teach MLflow on SQLite, including that MLflow 3.14 already
  defaults to it, and the fixture that keeps a migrated database per session
- 4.4 corrects `trivy config .` to `trivy --config trivy.yaml fs .` and explains
  both bugs; 4.1 and 4.5 cover Ruff 0.16; 4.2 adds the coverage gate
- every chapter that said `uv add --group check` now says `--group dev`, which
  is the group all four repositories actually use

Also pins the security workflow runner to ubuntu-24.04 so it matches CI.
@fmind
fmind force-pushed the docs/teach-the-current-stack branch from 1a77a20 to feaed74 Compare August 10, 2026 17:14
@fmind
fmind merged commit fa1bce2 into main Aug 10, 2026
1 check passed
@fmind
fmind deleted the docs/teach-the-current-stack branch August 10, 2026 17:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant