From 5bb60512629244ac7aa0cd856f139361d184225e Mon Sep 17 00:00:00 2001 From: Erich Blume Date: Sun, 19 Apr 2026 08:19:26 -0700 Subject: [PATCH] Resync template docs --- AGENTS.md | 22 +++---- README.md | 13 ++-- .../+forgejo-workflow-templates.infra.md | 1 - ...eature-forgejo-template-variables.infra.md | 1 - docs/how-to/agent-change-process.md | 6 +- docs/reference/reference.md | 61 ++++++++++++++++++- docs/tutorials/ai-assistance-guide.md | 15 ++++- 7 files changed, 95 insertions(+), 24 deletions(-) delete mode 100644 docs/changelog.d/+forgejo-workflow-templates.infra.md delete mode 100644 docs/changelog.d/feature-forgejo-template-variables.infra.md diff --git a/AGENTS.md b/AGENTS.md index 643bf40..afba364 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,11 +22,11 @@ This repository is a **Forgejo template**. Most customization points are auto-re This will refresh your context with important information you will be assumed to know and follow. **Read the full output** — never truncate, pipe to `head`/`tail`, or skip sections. 2. **Classify the change as C0/C1/C2 before starting** (see below) — this determines branching and PR requirements -3. **Feature branches + PRs for C1/C2** — checkout main, pull, create branch, open PR via `tea pr create`. C0 goes direct to main. -4. **Add changelog fragments (all change levels)** — `docs/changelog.d/..md` +3. **Generated repos use feature branches + PRs for C1/C2** — checkout main, pull, create branch, open PR via `tea pr create`. This template source repo usually stays C0/direct-to-main so it remains clean and templatable. +4. **Use changelog fragments in generated repos, not as template residue** — `docs/changelog.d/..md` Types: `feature`, `bugfix`, `infra`, `doc`, `ai`, `misc` - - **C1/C2:** Use branch name: `..md` - - **C0:** Use orphan prefix: `+..md` + - **Generated repos:** add fragments for noteworthy changes + - **This template repo:** keep `docs/changelog.d/` empty except for `.gitkeep` 5. **Never commit secrets** ## Change Classification @@ -41,7 +41,7 @@ Before starting work, classify the change: **C0** — commit directly to main. No branch or PR needed. Fix forward if problems arise. -**C1** — feature branch with early PR. Search related docs first, write documentation changes before code. Upgrade to C2 if complexity spirals. +**C1** — in generated repos, use a feature branch with an early PR. In this template source repo, prefer direct cleanups unless the user explicitly wants branch-based review. Search related docs first, write documentation changes before code. Upgrade to C2 if complexity spirals. **C2** — branch `mikado/` governed by the Mikado Branch Invariant: all card commits first, then code progress, then card closures. Commits use `C2(): plan/impl/close/finalize` convention. Reset the branch when new prerequisites are discovered. Resume with `mise run docs-mikado --resume`. @@ -49,13 +49,13 @@ See [[agent-change-process]] for the full methodology. ## Project Structure - ``` -./docs/ # documentation (Diataxis, Quartz) -./docs/changelog.d/ # towncrier fragments -./.dagger/ # dagger pipelines -./.forgejo/ # forgejo-runner actions and workflows -./mise-tasks/ # scripts via `mise run` +./docs/ # Diataxis docs, Quartz config, and release content +./docs/changelog.d/ # keep only .gitkeep in the template; generated repos add towncrier fragments here +./.dagger/ # Dagger module; rename src/project_template_ci/ when forking +./.forgejo/workflows/ # generic build and release workflows for generated repos +./.forgejo/scripts/ # optional per-project build/release hooks consumed by the workflows +./mise-tasks/ # repo automation via `mise run` ``` Other code paths will be listed via ai-docs. When you encounter wiki-links (`[[like-this]]`) it is referring to docs/ cards. diff --git a/README.md b/README.md index dd0575a..9a742a1 100644 --- a/README.md +++ b/README.md @@ -6,10 +6,10 @@ A personal project template with opinionated infrastructure for documentation, C - **Documentation** — [Diataxis](https://diataxis.fr/)-structured docs built with [Quartz](https://quartz.jzhao.xyz/) - **Changelog** — [Towncrier](https://towncrier.readthedocs.io/) fragment-based changelog -- **CI/CD** — [Dagger](https://dagger.io/) pipelines + [Forgejo](https://forgejo.org/) Actions workflow for releases +- **CI/CD** — [Dagger](https://dagger.io/) pipelines + Forgejo `build` and `release` workflows - **Pre-commit hooks** — [prek](https://github.com/dustinblackman/prek) with linting, formatting, secret detection - **AI assistance** — `AGENTS.md` + structured docs for Claude Code (C0/C1/C2 change process, Mikado method) -- **Task runner** — [mise](https://mise.jdx.dev/) tasks for docs validation, Mikado chain management, and more +- **Task runner** — [mise](https://mise.jdx.dev/) tasks for docs validation, Mikado chain management, release preview, and runner inspection ## Forking This Template @@ -19,7 +19,7 @@ After creating your repo, the remaining manual steps are: 1. Set `baseUrl` in `docs/quartz.config.ts` to your docs site domain 2. Rename `.dagger/src/project_template_ci/` directory and update class names to match your project -3. Fill in the project structure section in `AGENTS.md` +3. Review and tailor the project structure section in `AGENTS.md` 4. Add license information to `README.md` 5. Remove the "First-Time Setup" section from `AGENTS.md` and this section from `README.md` @@ -45,9 +45,10 @@ dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz ``` ./docs/ # documentation (Diataxis, Quartz) -./docs/changelog.d/ # towncrier fragments -./.dagger/ # dagger pipelines -./.forgejo/ # forgejo-runner actions and workflows +./docs/changelog.d/ # leave only .gitkeep in the template; generated repos add towncrier fragments here +./.dagger/ # Dagger module backing docs builds and releases +./.forgejo/workflows/ # generic build/release workflows for generated repos +./.forgejo/scripts/ # optional per-project hooks consumed by those workflows ./mise-tasks/ # scripts via `mise run` ``` diff --git a/docs/changelog.d/+forgejo-workflow-templates.infra.md b/docs/changelog.d/+forgejo-workflow-templates.infra.md deleted file mode 100644 index a67b6f3..0000000 --- a/docs/changelog.d/+forgejo-workflow-templates.infra.md +++ /dev/null @@ -1 +0,0 @@ -Split the template's Forgejo workflows into a generic CI `build` workflow and a docs-first `release` workflow, with optional hooks for project-specific validation and release artifacts. diff --git a/docs/changelog.d/feature-forgejo-template-variables.infra.md b/docs/changelog.d/feature-forgejo-template-variables.infra.md deleted file mode 100644 index 6c20d1a..0000000 --- a/docs/changelog.d/feature-forgejo-template-variables.infra.md +++ /dev/null @@ -1 +0,0 @@ -Add Forgejo template repository variable expansion — most TODO markers are now auto-resolved when creating a new repo from this template. diff --git a/docs/how-to/agent-change-process.md b/docs/how-to/agent-change-process.md index 7a90f8f..462baae 100644 --- a/docs/how-to/agent-change-process.md +++ b/docs/how-to/agent-change-process.md @@ -1,6 +1,6 @@ --- title: Agent Change Process -modified: 2026-03-03 +modified: 2026-04-19 tags: - how-to - ai @@ -260,11 +260,15 @@ tags: | Command | Purpose | |---------|---------| +| `mise run changelog-check` | Validate changelog fragment layout | +| `mise run docs-check-frontmatter` | Check required doc frontmatter fields | | `mise run docs-mikado` | List all active Mikado chains with branch status | | `mise run docs-mikado ` | Show dependency chain for a goal card | | `mise run docs-mikado --all` | Include completed cards in full | | `mise run docs-mikado --resume` | Resume a chain: detect branch, show state and next steps | | `mise run docs-mikado --resume ` | Resume a specific chain with branch consistency check | +| `mise run docs-preview ` | Preview a released docs bundle locally | +| `mise run runner-logs [run_number]` | List Forgejo Actions runs or fetch logs for a specific job | The `mikado-branch-invariant-check` commit-msg hook runs automatically on `mikado/*` branches, validating commit message conventions and invariant ordering. Requires `prek install --hook-type commit-msg`. diff --git a/docs/reference/reference.md b/docs/reference/reference.md index 0d0e5b1..7045557 100644 --- a/docs/reference/reference.md +++ b/docs/reference/reference.md @@ -1,6 +1,6 @@ --- title: Reference -modified: 2026-03-03 +modified: 2026-04-19 tags: - reference - meta @@ -8,6 +8,61 @@ tags: # Reference -Technical reference material. +Technical reference material for the repository tooling that ships with this project. - +## Template Surface Area + +| Path | Purpose | +|------|---------| +| `.dagger/src/project_template_ci/` | Dagger module that builds the Quartz docs tarball used by releases | +| `.forgejo/workflows/build.yaml` | Generic CI validation workflow | +| `.forgejo/workflows/release.yaml` | Manual release workflow that versions, builds docs, and publishes release assets | +| `.forgejo/scripts/` | Optional project-specific hooks consumed by the workflows | +| `mise-tasks/` | Helper tasks for docs validation, Mikado chains, PR review, and runner inspection | + +## Forgejo Workflows + +### `build.yaml` + +- Triggers on pushes to `main` and pull requests targeting `main` +- Runs `prek run --all-files` +- Executes `.forgejo/scripts/build` if that hook exists and is executable +- Otherwise exits after generic template validation + +### `release.yaml` + +- Triggered manually via `workflow_dispatch` +- Accepts `BUMP_PATCH`, `BUMP_MINOR`, `BUMP_MAJOR`, or `SPECIFIC_VERSION` +- Resolves the next version from the latest Forgejo release tag +- Builds `CHANGELOG.md` with towncrier when fragment files exist +- Builds `docs-.tar.gz` via `dagger call build-docs --src=. --version=` +- Executes `.forgejo/scripts/release ` if present to stage extra files under `release-assets/` +- Creates the Forgejo release and uploads the docs tarball plus any extra assets +- Commits generated changelog updates back to `main` when fragments were consumed + +## Mise Tasks + +| Task | Purpose | +|------|---------| +| `mise run ai-docs` | Print the key docs files AI agents are expected to read first | +| `mise run changelog-check` | Validate changelog fragments are flat files under `docs/changelog.d/` | +| `mise run docs-check-filenames` | Detect duplicate doc filenames | +| `mise run docs-check-frontmatter` | Validate required frontmatter fields | +| `mise run docs-check-index` | Ensure each doc is linked from its category index | +| `mise run docs-check-links` | Validate wiki-links against existing doc filenames | +| `mise run docs-mikado` | Inspect active Mikado chains and resume C2 work | +| `mise run docs-preview ` | Extract and serve a released docs tarball locally | +| `mise run mikado-branch-invariant-check` | Validate `mikado/*` branch commit discipline | +| `mise run pr-comments ` | List unresolved PR comments | +| `mise run runner-logs [run_number]` | List Forgejo Actions runs or fetch logs for a job | + +## Changelog Fragments + +- Store towncrier fragments under `docs/changelog.d/` +- Use one flat `.md` file per change +- The directory may contain only `.gitkeep` until the first real fragment is added + +## TODO After Templating + +- TODO: Set `baseUrl` in `docs/quartz.config.ts` to the hosted docs domain, or `localhost` if the docs are only previewed locally +- TODO: Rename `.dagger/src/project_template_ci/` and the exported Dagger class to match the generated project diff --git a/docs/tutorials/ai-assistance-guide.md b/docs/tutorials/ai-assistance-guide.md index 169844f..b60a6c2 100644 --- a/docs/tutorials/ai-assistance-guide.md +++ b/docs/tutorials/ai-assistance-guide.md @@ -1,6 +1,6 @@ --- title: AI Assistance Guide -modified: 2026-03-03 +modified: 2026-04-19 tags: - tutorials - ai @@ -82,13 +82,26 @@ Run `mise tasks` to list all available tasks. | Task | When to Use | |------|-------------| | `ai-docs` | At session start — review project documentation | +| `changelog-check` | Validate that changelog fragments are flat files in `docs/changelog.d/` | +| `docs-check-frontmatter` | Check required frontmatter fields across docs | +| `docs-preview` | Preview a released docs tarball locally | | `docs-mikado` | View active Mikado dependency chains for C2 changes | | `docs-mikado --resume` | Resume a C2 chain: detect branch, show state and next steps | | `pr-comments` | Check unresolved PR comments during review | +| `runner-logs` | Inspect recent Forgejo Actions runs or fetch logs for a job | | `docs-check-links` | Validate wiki-links in documentation (includes orphan detection) | | `docs-check-index` | Check every doc is referenced in its category index | | `docs-check-filenames` | Check for duplicate doc filenames | +## Repository Tooling + +This project ships two Forgejo workflows: + +- `build.yaml` runs on pushes and pull requests targeting `main`, executes `prek run --all-files`, and then runs an optional project hook at `.forgejo/scripts/build` when present. +- `release.yaml` is a manual workflow that computes the next version, optionally builds `CHANGELOG.md` from fragments, packages Quartz docs via Dagger, runs an optional `.forgejo/scripts/release` hook for extra assets, creates the Forgejo release, and pushes changelog updates back to `main` when fragments were consumed. + +- TODO: Rename `.dagger/src/project_template_ci/` and the exported Dagger class during first-time setup. + ## Common Pitfalls | Pitfall | Correct Approach |