RES — TFW-26: Documentation as Output¶
Date: 2026-04-05 Author: Researcher Status: 🔬 RES — Complete Parent HL: HL-TFW-26 Mode: Pipeline (deep)
Research Context¶
TFW-26 aims to close the loop where TFW's structured artifacts become a publishable documentation site — deterministic, scriptable, tool-independent. The HL proposed a two-layer architecture (agent maintains quality, utility compiles docs) with 7 hypotheses and 7 risks. This research investigated the SSG landscape, AI-queryability requirements, artifact structure fitness, and challenged the main architectural decisions.
Briefing¶
See research/briefing.md — research plan, hypotheses from HL §10, scope intent, guiding questions with user direction.
Decisions¶
| # | Decision | Rationale |
|---|---|---|
| D1 | MkDocs + Material + mkdocs-gen-files is the recommended tool. Not because it's the best SSG, but because gen-files solves TFW's multi-source aggregation problem natively — Python scripts read artifacts from anywhere at build time, no symlinks, no copy scripts, Windows-safe |
6 SSGs evaluated. All share single-source-dir limitation. MkDocs gen-files is the only plugin-native aggregation mechanism that avoids pre-build scripts. Material provides search, nav, responsive design for free |
| D2 | No compiled output in git. Deployment via GitHub Actions (CI/CD builds → deploys artifact). GitLab Pages: same mkdocs.yml, different CI wrapper (.gitlab-ci.yml) |
HL §3.1 docs/ at project root implied checked-in output. User confirmed: "держать папку под гитом означало бы дублирование информации". GitHub Actions is the modern standard. GitLab Pages trivially compatible |
| D3 | The compilable contract is the primary deliverable — more important than the tool choice. The contract defines strict structure each artifact type must have. MkDocs, MCP servers, zip tools, and any future consumer all read the same contract | User revealed MCP/AI-queryability as parallel goal (not just web docs). The contract is the common interface for all output targets. Tool (MkDocs) is one consumer |
| D4 | docs/ folder at project root = curated-only content. Empty by default (.gitkeep). Optional manual pages (landing, FAQ). All artifact-derived pages are virtual (generated by gen-files script at build time)** |
MkDocs requires docs_dir to exist. Using it for manual curation gives human control over landing page while keeping artifact compilation automated |
| D5 | Utility should WARN on contract violations (not fail silently, not block builds). CI/CD logs show "WARNING: expected heading not found". Still produces output** | HL §7 P5 "dumb compiler" missed the silent failure problem. Warning is still deterministic — string matching, not semantic judgment. Position between "too fragile" and "too strict" |
| D6 | Current TFW artifact structure is already sufficient for compilation. Only the formal contract specification is missing, not structural changes | Direct audit of all 10 source artifacts: heading patterns are consistent, cross-references follow conventions, table formats are uniform. The structure emerged from TFW discipline — it just wasn't documented as a contract |
| D7 | MCP server for TFW knowledge is a separate, future task. The compilable contract design must not preclude it, but MCP implementation is out of TFW-26 scope | Existing generic MCP servers (library-mcp, markdown-rules-mcp) already work on raw TFW files. A TFW-specific MCP server that understands decisions/facts/conventions = future value-add |
| D8 | MkDocs ecosystem risk is accepted. Switching cost is low because the compilable contract isolates tool choice | Material for MkDocs in maintenance mode. Zensical (successor) reads same config. Custom script alternative (~100 LOC) is always available. Contract = tool-agnostic |
| D9 | Dead links from task references (tasks/RF-...) in docs output are accepted as a known limitation. Source links work in repo context (GitHub), not in docs context |
Three options evaluated: accept, strip, include tasks. Including tasks = scope explosion. Stripping = lossy. Accepting = honest and documented |
Open Questions¶
| # | Question | Status | Answer |
|---|---|---|---|
| Q1 | Should docs/ contain an index.md landing page or should it be 100% generated from README.md? |
Open | Recommend: curated docs/index.md for public-facing landing, with README.md content as fallback if no curated version exists |
| Q2 | Should the gen-files script be part of TFW core (.tfw/) or project-specific? |
Open | Recommend: .tfw/scripts/gen_docs.py — part of TFW core, shipped with starter. mkdocs.yml is project-specific (has project name, URL) |
Hypotheses (from HL §10)¶
| # | Hypothesis | HL Status | RES Status | Evidence |
|---|---|---|---|---|
| H1 | A simple copy + frontmatter injection is sufficient for most artifacts | open | ✅ confirmed | 7/10 artifacts need only frontmatter + copy. 3 need splitting (KNOWLEDGE.md, README.md) or extraction |
| H2 | An existing tool (MkDocs / Jekyll / Hugo) can be configured to read TFW structure directly | open | ⚠️ partial | No SSG reads scattered directories natively. MkDocs gen-files plugin solves this with build-time scripts |
| H3 | A lightweight Python/bash script (<100 LOC) can handle the compilation step | open | ✅ confirmed | Gen-files script estimated 80-120 LOC. Stress-tested: 10 file reads + frontmatter + 2 splits. Only gen script counts — mkdocs.yml and CI are separate |
| H4 | The same docs/ output works for both GitHub Pages and GitLab Pages |
open | ✅ confirmed | MkDocs output (HTML/CSS/JS) is platform-agnostic. Only CI/CD wrapper differs (~20 lines each) |
| H5 | docs/ at project root is the right location |
open | ⚠️ revised | docs/ = curated-only pages, not compiled output. Compiled site is a CI/CD artifact, never in git. mkdocs.yml at project root |
| H6 | Current artifact structure is already sufficient — only contract is missing | open | ✅ confirmed | Direct audit: all 10 sources have consistent heading formats, table structures, cross-references. Contract = documenting what already exists |
| H7 | Traceability gaps can be fixed by tightening workflow rules | open | ⚠️ deferred | Dead links from task refs are accepted (D9). Traceability improvements are workflow enhancements, not research findings |
HL Update Recommendations¶
| # | What to update | Source |
|---|---|---|
| R1 | §3 Target State: replace docs/ as compiled output with docs/ as curated content + CI/CD deployed site |
Gather G4, Challenge C4 |
| R2 | §3.1 Result Visualization: replace source→output mapping with revised version from Extract E3 | Extract E3 |
| R3 | §4 Phase A: add "define compilable contract" as primary deliverable, not secondary to tooling | Gather G8, Decision D3 |
| R4 | §4 Phase B: add mkdocs.yml, scripts/gen_docs.py, CI/CD workflows as implementation artifacts |
Extract E5, E6 |
| R5 | §7 Principles: add P9 "Warning-level validation in compiler — deterministic checks, not silent failures" | Challenge C3 |
| R6 | §9 Risks: add MkDocs ecosystem risk (maintenance mode) with mitigation (compilable contract = low switching cost) | Challenge C1 |
| R7 | §9 Risks: revise "over-engineering" risk — 100 LOC confirmed, risk is LOW | Challenge C2 |
| R8 | §2/§3: add AI-queryability as a parallel output target. Compilable contract serves both web docs and MCP | Gather G7, G8 |
| R9 | Add new future task: TFW-MCP — MCP server for TFW project knowledge (decisions, facts, conventions) | Decision D7 |
Fact Candidates¶
Before writing Fact Candidates, review the conversation history. The human's messages are the primary source of strategic knowledge — domain insights, stakeholder priorities, business context, and constraints that shape decisions.
Record strategic facts about THIS project — not findings about alternatives, not implementation details (those belong in tfw-docs).
Human-Only Test: would this fact be unknown without the human saying it?
| # | Category | Candidate | Source | Confidence |
|---|---|---|---|---|
| FC1 | philosophy | TFW's ultimate goal is not web docs — it's AI-queryable knowledge endpoints. Web docs is one output target. MCP integration for team-internal AI assistants is equally or more important. "допустим мы родим .md артефакты, уже есть готовые набор для запуска чата по нему" | User, TFW-26 research session | ✅ high |
| FC2 | philosophy | The user uses Yandex Docs MCP at Innoforce "он очень круто помогает строить инфру в их облаке" — this is TFW's north star for project knowledge: structured docs that AI agents can query to help teams build things | User, TFW-26 research session | ✅ high |
| FC3 | constraint | No compiled documentation output should live in git — "держать папку под гитом означало бы дублирование информации". Build artifacts are CI/CD products, not repo content | User, TFW-26 research session | ✅ high |
| FC4 | process | The compilable contract is more important than the tool choice. If artifacts have strict structure, MkDocs, MCP servers, zip tools, and any future consumer can all read them independently. The contract IS the documentation engine | Researcher synthesis of user direction + external research | ⚠️ medium — researcher-derived insight, but directly from user steering |
Conclusion¶
This research confirmed TFW-26's core thesis: TFW artifacts ARE already compilable. The discipline that produced 33 architecture decisions, 19 verified facts, 4 topic files, and a 353-line philosophy document also produced consistent heading formats, table structures, and cross-references — a structure that only needs to be formalized as a "compilable contract" to enable deterministic compilation.
The tool recommendation (MkDocs + Material + gen-files) is secondary to this insight. The contract specification is the primary deliverable because it serves not just web docs, but any future consumer — MCP servers, AI assistants, knowledge distribution tools. The user's steering to investigate AI-queryability expanded the vision beyond the HL's original scope but confirmed that the two-layer architecture is correct: agents maintain quality (Layer 1), utilities consume the contract (Layer 2, plural).
What RESEARCH provided that would have been missed: (1) the mkdocs-gen-files plugin changes the architectural model from "compile to folder" to "generate at build time"; (2) the dead links limitation from task references; (3) the MkDocs maintenance risk with migration path; (4) the user's MCP/AI-queryability vision as a parallel output, making the compilable contract the central deliverable.
RES — TFW-26: Documentation as Output | 2026-04-05