hephaestus/docs/reference/reference.md

title	modified	tags
Reference	2026-04-19	reference meta

Reference

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

Project

• v1-prototype-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, and commits the consumed fragments back to main
• Bumps the workspace version (Cargo.toml + Cargo.lock) to the release version in a commit that only the release tag points at — main deliberately stays at 0.0.0, so cargo install --git --tag vX.Y.Z reports the real version while branch/dev installs report 0.0.0
• Tags that bump commit vX.Y.Z and pushes the tag itself (the workflow tags manually rather than letting the release API create the tag)
• 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 for the pushed tag and uploads the docs tarball plus any extra assets

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 import-todoist	Seed a heph store from Todoist (dry-run by default; -- --commit to write) — see import-todoist
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)