generated from eblume/project-template
Erich Blume
cbf859b2d7
Some checks failed
Build / validate (push) Failing after 2s
Customize the generated repo (rename Dagger module to hephaestus_ci /
HephaestusCi, set docs baseUrl, add All-Rights-Reserved LICENSE, update
README/AGENTS), and add the project's foundational design documentation:
- docs/explanation/design.md — rationale + decision-history record
- docs/reference/tech-spec.md — implementation-ready technical spec
These define hephaestus as a self-hosted, client/server + offline-first
system unifying a markdown knowledge base with task management: typed node
graph, the lived priority discipline ("what is next?"), recurrence with
fresh-per-occurrence checklists, op-log/CRDT sync with conflict resolution,
OIDC/Authentik auth, the heph.nvim surface, and a TDD strategy.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
71 lines
3 KiB
Markdown
71 lines
3 KiB
Markdown
---
|
|
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)
|
|
|
|
## 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`)
|