dl4rce/flaiwheel

Highlights

Structured Relations (v1) — Flaiwheel can now derive a per-project knowledge graph directly from YAML frontmatter on your existing markdown docs. No new persistent store, no graph_add/invalidate writes — markdown stays canonical and Git history is the validity window.

Two new MCP tools (28 → 30 total):

| Tool | Purpose |
|------|---------|
| relations(entity_id) | Resolve outbound + inbound edges (replaces, depends_on, fixes, implements) across the project |
| timeline(entity_id) | Git history for the doc holding the entity — "what was true at time T?" |

Frontmatter convention

---
id: adr-0042
type: architecture
replaces: [adr-0017]
depends_on: [service-summarizer, supabase-edge]
fixes: []
implements: []
status: active        # active | superseded | deprecated
superseded_at: null
---

Recognised scalar keys: id, type, status, superseded_at.
Recognised relation keys: replaces, depends_on, fixes, implements.

Added

• relations(entity_id) MCP tool — resolves the graph from frontmatter, marks unresolved targets, returns inbound + outbound edges.
• timeline(entity_id) MCP tool — newest-first Git history (hash, author, ISO date, subject) for the entity's doc.
• flaiwheel.frontmatter — stdlib-only YAML subset parser (scalars, flow lists [a, b], block lists - item). Zero new pip dependencies.
• GitWatcher.log_for_file(rel_path, limit=50) — read-only helper that powers timeline().
• validate_doc() now warns on unknown relation keys (info) and invalid status values (warning).
• Tests: tests/test_frontmatter.py, tests/test_watcher_log.py, plus TestValidateDocFrontmatter / TestRelations / TestTimeline in tests/test_server.py (284 tests pass).

Changed

• Quality checks (_check_single_completeness, _check_single_headings, _check_heading_structure) now strip frontmatter before running, so the leading --- block no longer confuses the "first heading must be h1" rule or word counts.
• README "Architecture" diagram updated: 30 tools (search, write, classify, manage, projects, relations, timeline).
• AGENTS.md, CLAUDE.md, installer-templated flaiwheel.mdc / AGENTS.md blocks and the standalone FLAIWHEEL_TOOLS.md reference now list relations() + timeline() in the tool table.
• scripts/install.sh: _FW_VERSION fallback bumped to 3.10.0 (the remote refresh from main's pyproject.toml remains authoritative).

Deferred (explicitly, by design)

• SQLite ER store with valid_from / valid_to — original v1 plan. Deferred to v2; will only be revisited if relations() on real projects becomes measurably too slow. Avoids dual-source-of-truth drift between markdown and a sidecar DB.
• AST-driven code↔symbol edges — merged with backlog item #13 as v3; gated on v1+v2 being insufficient.

Upgrade

Re-run the installer in any project — it auto-detects the new version from main, rebuilds the Docker image, and recreates the container:

bash <(curl -sSL https://raw.githubusercontent.com/dl4rce/flaiwheel/main/scripts/install.sh)

No data migration needed. Existing docs without frontmatter continue to work; relations() simply returns entity not found until you opt in by adding an id: to a doc.

Compatibility

• Backwards-compatible. All previous MCP tools unchanged.
• Frontmatter is optional everywhere — quality checks only warn (never block) on unknown keys.
• No new pip dependencies. No new ports. No new persistent state outside the existing knowledge repo.

Full changelog: https://github.com/dl4rce/flaiwheel/blob/main/CHANGELOG.md
Diff: https://github.com/dl4rce/flaiwheel/compare/v3.9.40...v3.10.0