project-template/README.md

# project-template

A personal project template with opinionated infrastructure for documentation, CI, and AI-assisted development.

## What's Included

- **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 `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, release preview, and runner inspection

## Forking This Template

This is a **Forgejo template repository**. When you create a new repo from this template, Forgejo automatically expands variables like `${REPO_NAME}` and `${REPO_OWNER}` in key files — handling most customization automatically.

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

If you use Claude Code, it will prompt you to resolve remaining TODOs at the start of your first session.

## Getting Started

```bash
# Install git hooks
prek install && prek install --hook-type commit-msg

# Run all pre-commit checks
prek run --all-files

# List available tasks
mise tasks

# Build docs (requires Dagger)
dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz
```

## Project Structure

```
./docs/                 # documentation (Diataxis, Quartz)
./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`
```

## License

<!-- TODO: Add license information -->