hephaestus/docs/explanation/explanation.md

---
title: Explanation
modified: 2026-03-03
tags:
  - explanation
  - meta
---

# Explanation

Background context and design decisions.

- [[design]] — Hephaestus design document: vision, data model, architecture, sync, and roadmap
- [[task-lifecycle]] — the two-axis task model (lifecycle state × attention), drop vs delete, and where each task shows up
-												Initial commit

											
										
										
											2026-05-31 06:13:36 -07:00
+								---
 								title: Explanation
 								modified: 2026-03-03
 								tags:
 								  - explanation
 								  - meta
 								---
 								# Explanation
 								Background context and design decisions.
-												Set up hephaestus from template and add design + tech spec

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>

											
										
										
											2026-05-31 09:37:28 -07:00
+								- [[design]] — Hephaestus design document: vision, data model, architecture, sync, and roadmap
-												docs(explanation): add Task Lifecycle — the two-axis model

A new explanation doc making the task model explicit: lifecycle state
(outstanding → done/dropped) is orthogonal to attention (white/orange/red/
blue), attention only matters while outstanding, and On Deck (blue) is a live
"later" task — NOT the same as dropped ("let go", terminal). Covers delete/
tombstone (soft-delete that keeps the context doc) and a table of where each
task shows up (agenda / search / export). Cross-links design §6.2/§6.3 and
tech-spec §4.3/§7/§8.1/§12; wired into the explanation index.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

											
										
										
											2026-06-03 08:56:53 -07:00
+								- [[task-lifecycle]] — the two-axis task model (lifecycle state × attention), drop vs delete, and where each task shows up