Resync template docs

2026-04-19 08:19:26 -07:00 · 2026-04-19 08:19:26 -07:00 · 5bb6051262
commit 5bb6051262
parent bcb6e01e58
7 changed files with 95 additions and 24 deletions
--- 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/<name>.<type>.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/<name>.<type>.md`
    Types: `feature`, `bugfix`, `infra`, `doc`, `ai`, `misc`
-    - **C1/C2:** Use branch name: `<branch>.<type>.md`
-    - **C0:** Use orphan prefix: `+<descriptive-slug>.<type>.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/<chain-stem>` governed by the Mikado Branch Invariant: all card commits first, then code progress, then card closures. Commits use `C2(<chain>): 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

-<!-- TODO: Fill in when forking this template -->
 ```
-./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.
--- 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`
 ```

--- a/docs/changelog.d/+forgejo-workflow-templates.infra.md
+++ b/docs/changelog.d/+forgejo-workflow-templates.infra.md
@ -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.
--- a/docs/changelog.d/feature-forgejo-template-variables.infra.md
+++ b/docs/changelog.d/feature-forgejo-template-variables.infra.md
@ -1 +0,0 @@
-Add Forgejo template repository variable expansion — most TODO markers are now auto-resolved when creating a new repo from this template.
--- 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 <card>` | Show dependency chain for a goal card |
 | `mise run docs-mikado <card> --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 <chain>` | Resume a specific chain with branch consistency check |
+| `mise run docs-preview <tarball>` | 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`.

--- 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.

-<!-- TODO: Add reference entries as the project grows -->
+## 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-<version>.tar.gz` via `dagger call build-docs --src=. --version=<version>`
+- Executes `.forgejo/scripts/release <version>` 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 <tarball>` | Extract and serve a released docs tarball locally |
+| `mise run mikado-branch-invariant-check` | Validate `mikado/*` branch commit discipline |
+| `mise run pr-comments <pr_number>` | 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
--- 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 |
				`@ -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.
				`@ -1 +0,0 @@`
				`Add Forgejo template repository variable expansion — most TODO markers are now auto-resolved when creating a new repo from this template.`