HL — TFW-27: Wiki Polish & Brand Identity

Date: 2026-04-05 Author: Coordinator Status: ✅ Approved — Post-RESEARCH update

---

1. Vision

TFW's documentation site has become the project's public face — the first thing a potential user sees when evaluating whether to adopt the methodology. The MVP from TFW-26 proved the compilable contract works: artifacts compile into ~165 MkDocs pages. But the output feels like a file dump, not a product. There is no brand identity (no logo, no color palette, no typography), the landing page is a placeholder, navigation has hardcoded topics, links break after compilation, and there is no structural map of how artifacts relate to each other.

This task transforms the raw documentation output into a polished, branded, navigable knowledge product. It establishes TFW's visual identity, builds a curated open-source landing page, fixes structural issues inherited from TFW-26, and completes Wikipedia-style linking — where every mention of a known entity (task, decision, principle, tech debt item) becomes a clickable link in compiled docs.

Impact: After TFW-27, a developer arriving at the GitHub repo or tfw.saubakirov.kz sees a professional, branded project with clear value proposition, intuitive navigation, and a Wikipedia-like feel where everything is interlinked and discoverable. TFW's existing markdown structure IS the knowledge graph — the compiled docs make it navigable for humans, while AI agents navigate the markdown directly.

"I opened the docs and immediately understood what TFW is, how it works, and where to find everything. It felt like a real product, not a side project. And when I pointed my AI agent at the repo, it could navigate the knowledge graph without me explaining the structure."

2. Current State (As-Is)

Brand

Aspect	Current State
Logo	None
Color palette	MkDocs Material default (indigo)
Typography	Browser defaults
Brand voice	Exists in .tfw/README.md — "Traces Over Code" — but not visually expressed
Favicon	None

Landing Page

Surface	Current State
GitHub README.md	Functional but utilitarian. Task Board dominates. No visual hooks
docs/index.md	Placeholder: "This page is auto-generated by the TFW documentation pipeline" (6 lines)
tfw.saubakirov.kz	Not deployed yet (TFW-28). Would show the placeholder

Documentation Quality (inherited from TFW-26)

Issue	TD	Severity	Description
Nav terminology	TD-69	Low	"Concepts > Philosophy" vs "Knowledge > Topics > Philosophy" — label duplication
Task sidebar	TD-70	Med	Single flat link, no per-task sidebar browsing
Knowledge hardcoded	TD-71	Med	Knowledge topics hardcoded in mkdocs.yml nav. New topics = manual edit
Broken links	TD-72	High	Pre-existing relative links in .tfw/ sources break after compilation (different output paths)
Strict mode	TD-74	Med	--strict fails on absolute link INFO messages

Link Resolution & Navigation

Aspect	Current State
Link resolution	gen_docs.py has 6 resolvers (artifact, phase, HL-dash, TD, D, backtick-path). Missing: bare task IDs, markdown link rewriting, HTML anchors on table rows
Broken links	~31 broken relative links: 15 sibling links in .tfw/, 16 README→.tfw/ links (TD-72)
Navigation source	Hardcoded in mkdocs.yml (TD-71)
Deep linking	No HTML anchors on table rows — D24, P7, [TD-72](../../reference/tech-debt.md) not directly linkable

3. Target State (To-Be)

Brand Identity

Aspect	To-Be
Logo	SVG logo for TFW. Used in: docs site header, README.md, favicon
Color palette	Defined palette (primary, accent, neutral). Applied to MkDocs theme
Typography	Google Font (e.g., Inter, Outfit) via MkDocs Material custom CSS
Brand DNA	Documented in docs/brand/ — colors, logo usage, typography, voice guidelines
Favicon	Generated from logo, configured in mkdocs.yml

Landing Page (unified content, two renderings)

Surface	To-Be
README.md	Open-source marketing page: logo, tagline, value proposition, feature highlights, badges, quick start, links to docs. Task Board stays (it's the project's live status)
docs/index.md	Curated landing: hero with logo + tagline, feature cards, "How It Works" overview, CTA to Getting Started. Generated from README.md sections + custom landing content

Documentation Quality (all TDs resolved)

Issue	Resolution
TD-69: Nav terminology	Restructured nav with clear hierarchy via literate-nav
TD-70: Task sidebar	Per-task folder navigation via literate-nav SUMMARY.md
TD-71: Knowledge hardcoded	Dynamic nav generation via mkdocs-literate-nav + mkdocs_gen_files.Nav()
TD-72: Broken links	Markdown link rewriter using Source Manifest path mapping (~50 LOC)
TD-74: Strict mode	Fix absolute link handling

Wikipedia-Style Linking (RESEARCH outcome replaces artifact graph)

RESEARCH Decision R1: No artifact graph YAML file. TFW's markdown structure IS the knowledge graph. AI agents navigate markdown directly — TFW is designed for AI-queryability by structure. gen_docs.py builds an in-memory entity index at build time for Wikipedia-style link resolution.

New resolvers (4 features, ~120 LOC total):

#	Feature	LOC	What it fixes
1	Bare task ID resolver ([TFW-18](../TFW-18__knowledge_consolidation/HL-TFW-18__knowledge_consolidation.md) → task HL link)	~15	Missing task links in KNOWLEDGE.md Source columns
2	Markdown link rewriter (fix [text](relative.md) after source→output mapping)	~50	TD-72: ~31 broken links in .tfw/ sibling refs + README→.tfw/
3	HTML anchors on table rows (P{N}, D{N}, TD-{N}, F{N})	~30	Deep linking: /knowledge-index/#p7, #d24, /reference/tech-debt/#td-72
4	literate-nav integration (SUMMARY.md generation)	~25	TD-71, TD-70, TD-69: dynamic nav from filesystem

Not implemented (RESEARCH rejections): - P{N} auto-resolution — double semantics (global §0 vs task-local §7). HTML anchors only (R3) - F{N}, S{N} auto-resolution — not globally unique. Deep-linkable via anchors (R3) - File paths without backticks — false positive risk too high (R4)

3.1 Result Visualization

Unified landing page (README.md = docs/index.md source):

┌─────────────────────────────────────────────────┐
│  [TFW Logo]                                     │
│                                                 │
│  Trace-First Workflow                           │
│  "The thought process is more valuable          │
│   than the immediate result."                   │
│                                                 │
│  ┌─────────┐  ┌──────────┐  ┌─────────────┐    │
│  │ Traces  │  │ Candor   │  │ Completeness│    │
│  │ Over    │  │ Over     │  │ Over        │    │
│  │ Code    │  │ Flattery │  │ Speed       │    │
│  └─────────┘  └──────────┘  └─────────────┘    │
│                                                 │
│  ┌─ Quick Start ──────────────────────────┐     │
│  │ 1. Fork this repo                     │     │
│  │ 2. Run /tfw-init                      │     │
│  │ 3. Start with /tfw-plan               │     │
│  └───────────────────────────────────────┘     │
│                                                 │
│  [MIT] [v0.7.1] [GitHub Stars]  ← badges       │
│                                                 │
│  ── What's Inside ──                            │
│  ── Tool Adapters ──                            │
│  ── Key Concepts ──                             │
│  ── Links ──                                    │
│  ── Task Board ──    ← stays in README.md       │
└─────────────────────────────────────────────────┘

Wikipedia-style linking pipeline (replaces artifact graph):

┌────────────────────────────┐
│  gen_docs.py (build time)  │
│                            │
│  1. Scan KNOWLEDGE.md      │
│     → entity index (P,D)   │
│  2. Scan TECH_DEBT.md      │
│     → entity index (TD)    │
│  3. Scan tasks/            │
│     → entity index (TFW-N) │
│  4. Process each page:     │
│     → add HTML anchors     │
│     → rewrite md links     │
│     → resolve refs via     │
│       existing 6 resolvers │
│       + bare task ID       │
│  5. Generate SUMMARY.md    │
│     → literate-nav builds  │
│       dynamic navigation   │
└────────────────────────────┘

MkDocs with brand applied:

┌───────────────────────────────────────────────────┐
│ [Logo] Trace-First Workflow    🔍 Search    🌙/☀  │
├──────────┬────────────────────────────────────────┤
│ Home     │                                        │
│ Start    │   [Content area]                       │
│ ─────── │                                        │
│ Concepts │   Dynamic nav ← literate-nav SUMMARY   │
│   Philos │   Resolved links ← entity index        │
│ ─────── │   Brand colors ← docs/brand/           │
│ Knowledge│                                        │
│   Index  │                                        │
│   Topics │                                        │
│     Auto │ ← from filesystem scan                 │
│ ─────── │                                        │
│ Reference│                                        │
│ Tasks    │                                        │
│   [TFW-1](../TFW-1__formalize_success_criteria/)  │ ← per-task sidebar navigation          │
│   [TFW-2](../TFW-2__upgrade_to_v3/)  │                                        │
│   ...    │                                        │
└──────────┘────────────────────────────────────────┘

4. Phases

Phase A: Brand Identity & Logo 🔴

• Define brand DNA: name treatment, tagline, values visual language
• Generate TFW logo (SVG) — minimal, professional, methodology-focused
• Define color palette (primary, accent, neutral, dark mode variants)
• Choose typography (Google Font for docs, system fallback for README)
• Create docs/brand/ with guidelines document
• Apply palette + logo + font to mkdocs.yml theme config
• Generate favicon from logo
• Test: build docs locally, verify branding applied

Phase B: Wikipedia-Style Linking + Dynamic Nav 🔴

• Implement bare task ID resolver in gen_docs.py ([TFW-18](../TFW-18__knowledge_consolidation/HL-TFW-18__knowledge_consolidation.md) → task HL link, ~15 LOC)
• Implement markdown link rewriter using Source Manifest mapping (~50 LOC, fixes TD-72)
• Add HTML anchors on numbered table rows: P{N}, D{N}, TD-{N}, F{N} (~30 LOC)
• Implement literate-nav integration: gen_docs.py generates SUMMARY.md via mkdocs_gen_files.Nav() (~25 LOC)
• Remove hardcoded nav: from mkdocs.yml, add mkdocs-literate-nav + mkdocs-section-index to requirements
• Fix --strict mode (TD-74)
• Write tests for all 4 new features
• Verify: mkdocs build produces correct links, nav auto-discovers topics/tasks

Phase C: Landing Page & Documentation Polish 🟡

• Redesign README.md as open-source marketing landing page
• Create curated docs/index.md with hero, features, CTA
• Fix nav terminology (TD-69) — clear, non-overlapping labels
• Implement per-task sidebar navigation (TD-70)
• Add SEO: site description, OG tags, sitemap config in mkdocs.yml
• Add badges to README (version, license, docs link)
• Final quality pass: all pages, links, navigation

5. Definition of Done (DoD)

• ✅ 1. TFW has a logo (SVG), favicon, and defined color palette applied to docs site
• ✅ 2. Brand guidelines documented in docs/brand/
• ✅ 3. gen_docs.py resolves all §16.2 reference patterns + bare task IDs + markdown links — TD-72 fixed
• ✅ 4. HTML anchors on numbered table rows (P, D, TD, F) enable deep linking
• ✅ 5. Navigation auto-generated via literate-nav — TD-71 fixed (no hardcoded nav in mkdocs.yml)
• ✅ 6. README.md is a polished open-source landing page with logo, badges, value proposition
• ✅ 7. docs/index.md is a curated landing page with hero + feature cards
• ✅ 8. Per-task sidebar navigation works — TD-70 fixed
• ✅ 9. Nav labels are clear and non-overlapping — TD-69 fixed
• ✅ 10. mkdocs build --strict passes — TD-74 fixed
• ✅ 11. MkDocs SEO configured: site description, sitemap

6. Definition of Failure (DoF)

• ❌ 1. Brand feels generic or clip-art — must be distinctive and aligned with TFW philosophy
• ❌ 2. gen_docs.py grows beyond ~600 LOC without clear module separation
• ❌ 3. Landing page reads like documentation, not like a product pitch — must have marketing energy
• ❌ 4. Link resolution produces false positives (especially bare task ID resolver)
• ❌ 5. Navigation requires manual edits when knowledge topics or tasks change

On failure: If brand direction is wrong (DoF#1), iterate with user before proceeding to Phase C. If gen_docs.py complexity grows (DoF#2), extract entity index + resolvers into separate module.

7. Principles

1. One landing, many renderings — README.md content is the canonical source. docs/index.md renders it for the web. GitHub renders it for the repo. Same content, different presentations.
2. Source Manifest drives linking, literate-nav drives navigation — TFW markdown IS the knowledge graph. gen_docs.py resolves references at build time via in-memory entity index. No separate graph artifact.
3. Brand = philosophy made visible — TFW's visual identity must express its values: precision, traceability, structured thinking. Not flashy, not corporate — professional and methodological.
4. Forward links only — links go from mention to target (text → entity). No backward links (entity → all mentions). If an author wants a back-reference, they add it explicitly.
5. Progressive enhancement — a project with zero brand customization still gets a working docs site. Brand elements are additive.

8. Dependencies

Dependency	Status
TFW-26 (compilable contract + gen_docs.py)	✅ DONE
MkDocs Material theme installed	✅
conventions.md §16 Compilable Contract	✅
gen_docs.py (445 LOC, 42 tests)	✅
TFW-28 (deploy to GitHub Pages)	⬜ Future — separate task

9. Risks

Risk	Probability	Impact	Mitigation
Logo doesn't capture TFW essence	Medium	Medium	Define brand DNA first, iterate with user before final
Bare task ID resolver false positives	Low	Medium	Runs LAST, after all type-prefixed resolvers. Guard with negative lookbehind
gen_docs.py grows beyond maintainable size (~445 → 570+ LOC)	Low	Medium	+120 LOC is modest. If grows further, extract entity_index module
MkDocs Material custom CSS breaks on upgrade	Low	Medium	Use theme extension points (custom_dir), not raw overrides
Unified README/index.md diverges	Low	Medium	docs/index.md imports from README.md sections, not duplicates

10. RESEARCH Results

RESEARCH completed 2026-04-05. Full findings: RES__TFW-27

Hypotheses — Final Status

#	Hypothesis	Status	Evidence
H1	Artifact graph can be auto-generated from file structure	⚫ Not needed	TFW markdown IS the graph. In-memory index sufficient. User: "плодить лишние сущности не надо"
H2	Dynamic nav via mkdocs-literate-nav	✅ Confirmed	API (mkdocs_gen_files.Nav()) designed for this. Same author as gen-files
H3	Broken links limited to .tfw/ internal relative links	🟡 Partial	Two categories: sibling (15) + README→.tfw/ (16). Plus missing Wikipedia-style links
H4	OSS methodology projects use consistent landing pattern	🟡 Partial	Hybrid pattern: methodology (spec/FAQ) + product (quick start). Badges = TFW addition
H5	Custom YAML for graph	⚫ Not needed	No graph file. In-memory entity index at build time

Key Decisions from RESEARCH

#	Decision
R1	No artifact graph YAML — TFW markdown IS the knowledge graph
R2	Wikipedia-style linking via in-memory entity index (build-time only)
R3	P{N} NOT auto-resolved — double semantics (global vs task-local). HTML anchors only
R4	File paths without backticks NOT resolved — false positive risk too high
R5	Adopt mkdocs-literate-nav for dynamic navigation
R6	Landing page = hybrid methodology + tool pattern

11. Strategic Session Insights

Human-Only Test: Would this insight be unknown without the user saying it?

#	Insight	Category	Source
S1	README.md = docs/index.md = GitHub Pages home = one unified content, three renderings. Not separate pages	convention	User, Q1 answer
S2	Brand is not just a logo — it's DNA, brandbook, colors, style. TFW needs a full visual identity	philosophy	User, Q2 answer
S3	"Marketing" = open-source marketing. README as product page with badges, visual hooks, clear value proposition. Plus SEO metadata	stakeholder	User, Q3 answer
S4	Deploy is a separate task (TFW-28). Quality must be verifiable locally via mkdocs serve	process	User, Q4 answer
S5	Broken links need a structural solution — a map/YAML that shows how everything connects. This same map helps AI agents and MCP navigate. Could power an Obsidian-like graph visualization. RESEARCH outcome: no separate YAML needed — TFW markdown IS the graph, in-memory entity index at build time sufficient	philosophy	User, Q5 answer + RES R1
S6	The knowledge graph manifest is not just a link-fixing tool — it's a navigation/orientation file for AI agents and MCP. A structural asset, not a build artifact. RESEARCH outcome: AI agents navigate markdown directly, no need for separate manifest	philosophy	User, Q5 answer + RES R1

---

HL — TFW-27: Wiki Polish & Brand Identity | 2026-04-05 | Post-RESEARCH update