hephaestus/docs/reference/reference.md

---
title: Reference
modified: 2026-04-19
tags:
  - reference
  - meta
---

# Reference

Technical reference material for the repository tooling that ships with this project.

## Project

- [[tech-spec]] — Hephaestus technical specification (data model, RPC API, "what is next?" ranking, recurrence, testing strategy, v1 scope)
- [[heph-nvim]] — The Neovim plugin surface: architecture, buffer-backed editing, RPC dependencies, commands, and the headless e2e harness

## Template Surface Area

| Path | Purpose |
|------|---------|
| `.dagger/src/hephaestus_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 once published (currently `localhost`)