September 2025: Google Gemini CLI called FAF "README evolution for AI era."

We knew READMEs mattered for AI context. But most are average - missing the structured data AI actually needs. We lived with it.

Then we realized: we don't have to accept mediocre context. We can show people exactly what AI wants.

v4.1.0 does both: Extract what you have (faf_readme), show what's missing, fill the gaps (faf_human_add). That's the evolution.

The Problem

Most READMEs are written for humans, not AI. They're inconsistent, unstructured, and missing the context AI craves.

What AI actually wants:

  • WHO - Team/maintainer info (missing in 60% of repos)
  • WHAT - Clear description (often vague)
  • WHY - Purpose/motivation (rarely documented)
  • WHERE - Runtime environment (scattered)
  • WHEN - Timeline/status (outdated)
  • HOW - App type (implied, not stated)

We can extract READMEs, but why settle for average when we can guide people to Gold Code?

The Solution: Two Paths to Gold Code

Path 1: 6Ws Builder + faf_human_add

For projects starting fresh or developers who prefer guided workflows.

1. Visit faf.one/6ws

Answer 6 questions in a clean web form

→
2. Copy YAML

One-click copy to clipboard

→
3. Paste to Claude

Claude uses faf_human_add tool

→
4. Context merged

Score jumps +25-35% instantly

What faf_human_add does:

  • Merges YAML from web form into project.faf
  • Sets individual fields (who/what/where/why/when/how)
  • Non-interactive bundled command (MK3 engine)
  • Works in Claude Desktop headless environment

Path 2: Automatic README Extraction + faf_readme

For projects that already have a README.md.

User: "Extract context from my README"

Claude: Uses faf_readme tool

📄 README Context README: /path/to/README.md Confidence: 82% Fields found: 5/6 1W (WHO): creators, developers 2W (WHAT): app for persistent AI context 3W (WHERE): web, terminal, CI/CD 4W (WHY): gap in AI memory across sessions 5W (WHEN): active development 6W (HOW): npm install -g faf-cli Next steps: 1. Run faf_readme { merge: true } to merge into project.faf 2. Fill missing field at faf.one/6ws 3. Your context is now available to all AI assistants

What faf_readme does:

  • Intelligent pattern matching for 6 Ws extraction (309 lines from faf-cli v4.3.0)
  • Confidence scoring per field
  • Extract-only mode (preview) or auto-merge to project.faf
  • Handles 20+ README patterns (bold subtitles, blockquotes, Quick Start sections)
  • Same +25-35% score boost as manual entry

The Architecture

Both features use the MK3 Bundled Engine pattern:

  • Zero CLI dependencies - Commands bundled directly in MCP server
  • Non-interactive - Designed for Claude Desktop headless environment
  • 16.2x faster - No process spawning, direct function calls
  • Championship testing - 44 new tests (212 → 256 total)

Test coverage breakdown:

  • 21 tests for human-context.test.ts (YAML merge, field validation, edge cases)
  • 23 tests for readme-extraction.test.ts (pattern matching, confidence scoring, merge behavior)

Try It

Install or update:

npm install -g claude-faf-mcp@4.1.0

Path 1 - Web Form:

  1. Visit faf.one/6ws
  2. Fill 6 questions
  3. Copy YAML
  4. Paste to Claude → "Add this to my project"

Path 2 - README Extraction:

  1. Open Claude Desktop in your project
  2. Say: "Extract context from my README"
  3. Review extracted fields
  4. Say: "Merge it" to add to project.faf

The Numbers

  • v4.1.0 - Released February 9, 2026
  • 256/256 - Tests passing (Championship Grade)
  • 52 MCP tools - Complete context management suite
  • 21,000+ - npm downloads
  • +25-35% - Typical score boost from either path
  • 19ms - Average tool execution time

What Changed

Added

  • faf_human_add tool - Complete 6Ws Builder workflow
  • faf_readme tool - Automatic README context extraction
  • 44 new tests (21 human-context + 23 readme-extraction)
  • 3 new bundled commands in MK3 engine

Infrastructure

  • Updated faf-cli dependency: v3.2.6 → v4.3.0
  • 1,706 lines of new production code
  • IANA-registered format features

Why This Matters

Adoption was the bottleneck. Not understanding, not trust — just friction.

Before v4.1.0:

  • Manual .faf file creation
  • Copying README content by hand
  • Incomplete context = low scores

After v4.1.0:

  • Web form or automatic extraction
  • Zero manual copying
  • Many hit 100% 🏆 on first run

Two paths. Same destination. Zero friction.

Built with .faf ☑️ Championship testing. Professional execution. 🏎️