generated from eblume/project-template
Erich Blume
ee865e5635
Some checks failed
Build / validate (pull_request) Failing after 4s
The primary surface begins (tech-spec §8): a Neovim plugin that is a thin
client of the local hephd over its unix-socket JSON-RPC.
- node.resolve {title} → Node|null (heph-core Store + dispatch): exact,
owner-scoped, non-tombstoned alias-then-title match — the same mapping that
materializes wiki links, so follow-link jumps to the node the stored link
points at (never fuzzy search). Unit + rpc_socket integration tests.
- heph.nvim/: vim.uv unix-socket JSON-RPC client (blocking call via vim.wait,
id-demuxed, partial-line buffered, luanil so JSON null → Lua nil; isolated
Sessions for tests). Buffer-backed nodes (heph://node/<id>, acwrite;
BufReadCmd→node.get / BufWriteCmd→node.update, whole-buffer body round-trips
exactly through the CRDT). [[wiki-link]] follow on <CR>. Daily journal.
:Heph command surface + completion.
- Headless e2e (§9): a self-contained busted-style runner (tests/e2e/runner.lua)
— no external plugins, no network, deterministic CI exit codes. Specs: journal
round-trip, follow-link (+ unresolved no-op), link-two-docs/backlink.
`make -C heph.nvim test` builds hephd and runs it.
Docs: heph-nvim reference card, §14 tracker (11a done; 11b/11c/11d queued),
changelog fragment.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
72 lines
3.1 KiB
Markdown
72 lines
3.1 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)
|
|
- [[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`)
|