Skip to content

Briefing

Parent: HL-TFW-27 Goal: Transform TFW's raw documentation output into a polished, branded, navigable knowledge product with an artifact graph manifest as its structural backbone.

Research Plan

Gather — "What do we NOT know?"

  • Audit broken links (TD-72): run gen_docs.py, collect all WARNING/ERROR output, classify by pattern type
  • Survey 3-5 open-source methodology projects (Conventional Commits, Keep a Changelog, Semantic Versioning, The Twelve-Factor App, GitFlow) — how they present: logo, landing page, nav structure, badges
  • Investigate MkDocs Material dynamic nav generation: mkdocs-literate-nav, awesome-pages, gen-files hooks, nav rewriting at build time
  • Survey existing graph/relationship schema standards: JSON-LD, RDF-lite, CITATION.cff, custom YAML patterns in similar tools

Extract — "What do we NOT see?"

  • Analyze gen_docs.py's 6 existing resolvers — which reference types does each handle, what gaps exist
  • Map all cross-reference types actually used in project files (scan for RF TFW-, D{N}, TD-{N}, HL-TFW-, P{N}, F{N}, backtick paths)
  • Compare MkDocs nav plugin approaches: which ones work with gen_docs.py's aggregation pattern (scattered sources → single output dir)
  • Analyze what metadata an artifact graph node needs: minimum viable schema

Challenge — "What do we NOT expect?"

  • Is the artifact graph actually needed? Can enhanced gen_docs.py resolvers + MkDocs plugins solve the same problems without a separate YAML?
  • What's the maintenance cost of the graph? Auto-generation reliability, manual curation burden, staleness risk
  • Does dynamic nav generation conflict with MkDocs Material's search indexing or SEO features?

Hypotheses (from HL §10)

# Hypothesis HL Status
H1 Artifact graph can be auto-generated from file structure + conventions.md §16 Source Manifest open
H2 Dynamic nav can be generated by gen_docs.py via mkdocs-literate-nav or nav rewriting open
H3 Broken links (TD-72) are limited to .tfw/ internal relative links that change output path open
H4 Open-source methodology projects use a consistent pattern: logo + tagline + values + quick start + badges open
H5 A custom YAML schema for artifact graph is simpler and more useful than existing standards (JSON-LD, RDF-lite) open

Scope Intent

  • In scope: Artifact graph schema validation, broken link audit, OSS methodology landing page patterns, MkDocs dynamic nav options, gen_docs.py resolver analysis
  • Out of scope: Brand/logo design decisions, actual implementation, deployment (TFW-28), MCP server design, graph visualization

Guiding Questions

  1. Have you looked at any specific OSS methodology/framework projects whose presentation you admire — or want TFW to explicitly NOT look like?
  2. For the artifact graph — do you envision it as primarily a build-time tool (consumed by gen_docs.py only) or also a runtime asset (shipped with the docs, queryable via MCP)?
  3. The HL mentions "manually curable" graph. How much manual curation do you realistically expect to do — zero (fully auto), occasional (fix edge cases), or regular (curate relationships)?

User Direction

  1. OSS role models: No strong preferences. Check https://github.com/openclaw/openclaw specifically.
  2. Graph scope: User doesn't know exact scope, but confirms other tools will definitely consume the graph (not just gen_docs.py). → Graph = project asset, not just build artifact.
  3. Curation level: Fully automatic. Zero manual curation expected. → Auto-generation must be reliable enough to be the sole source.

Stage complete: YES