project/
├── package.json     ← npm reads this
├── project.faf      ← AI reads this
├── README.md        ← humans read this
└── src/

Every building requires a foundation. FAF is AI's foundational layer.

You have a package.json. AI needs you to add a project.faf. Done.

Git-Native. project.faf versions with your code — every clone, every fork, every checkout gets full AI context.
No setup, no drift, no re-explaining.

bunx faf                      # Bun — zero install, fastest path
npx faf                       # npm — works everywhere
brew install wolfe-jam/faf/faf-cli && faf   # Homebrew (auto-taps)

faf is shorthand for faf-cli auto — same behavior, fewer keystrokes.

# ANY GitHub repo — no clone, no install, 2 seconds
bunx faf-cli git https://github.com/facebook/react

# Your own project
bunx faf-cli init              # Create .faf
bunx faf-cli auto              # Zero to 100% in one command
bunx faf-cli go                # Interactive interview to gold code

Run faf with no arguments:

faf-cli dogfoods itself — project.faf is source DNA; CLAUDE.md and GEMINI.md are authored from it via faf. AGENTS.md is the BETTER ops briefing (hand-kept for agents; faf export --agents still authors AGENTS.md for other repos).

Run faf --help for the full command set and options.

Portable agent memory in the IANA-registered .fafm format. Same INTEROP as claude-fafm-sdk 1.0.

# Claude Code memory dir → soul.fafm
faf memory convert ~/.claude/projects/.../memory -o soul.fafm

faf memory ls                    # ranked facts
faf memory recall "your query"   # deterministic filter + rank
faf memory etch "a durable fact" --id my-fact
faf memory show

faf sync is the one name: "bi-sync" is gone from its help, its output and the footer every rendered CLAUDE.md carries.

• One word for one command. faf sync works as before: it writes CLAUDE.md from project.faf. faf sync --direction pull backfills name, goal and language into .faf, and only at ✪ Trophy. faf bi-sync still runs as a hidden alias.
• Tools built on faf-cli follow automatically. Anything that composes renderClaudeMd writes the new STATUS: SYNC ACTIVE footer on its next sync, with no release of its own.

faf-cli opens its renderers, injector and faf auto update chain as public exports — consumers compose instead of port — and faf export --agents is idempotent again: one block, every run.

import { renderAgentsMd, enrichFromRepo, injectFafBlock, updateExistingFaf, writeFaf } from 'faf-cli';

• Renderers are public — renderAgentsMd · renderGeminiMd · renderCursorrules · renderClaudeMd · renderCopilotInstructions and their write* pairs. An MCP server or an editor extension writes the same bytes faf export writes, instead of carrying its own copy that drifts.
• enrichFromRepo(dir, data) — the repo-facts step faf export --agents runs first (commands, key files, secrets location) is exported too. Hand-authored values win; detection fills the gaps.
• updateExistingFaf(dir, existing) — the exact chain faf auto runs on an existing project.faf: existing wins, then interrogated → detected → Turbo-Cat → Relentless fill the empties. faf auto itself now calls it. writeFaf / serializeFaf write the file the way faf-cli does.
• One injector, one rule — injectFafBlock / findFafBlock locate the managed block by whole marker lines at column 0. Fenced examples are skipped, an unbalanced fence inside the block cannot hide the end marker, CRLF and BOM survive. A block that lost its end marker is prefixed, never overwritten.
• Fixed: faf export --agents stacked its own output. 7.1.4–7.11.0 quoted the marker tokens in prose and matched them as substrings, so every re-run appended the old block's tail (58 → 107 → 156 lines). Fixed at both ends; a file already stacked is repaired on its next export.

Recent sprint

• 🧩 7.12.0 The Open Renderers Edition
• 🖥️ 7.11.0 The VS Code Edition
• 📚 7.10.0 The Full-Facts Edition
• 🌱 7.9.0 The Git-Flow Edition
• 🎬 7.8.0 The Projector Edition
• 🐦 7.7.0 The Swift Edition
• 💎 7.6.0 The Ruby Edition
• ☕ 7.5.1 The JVM Edition

Your own rules for the AI — "use full words in identifiers," "use bun, not npm" — go in project.faf under ai_instructions.warnings. They land at the top of every AGENTS.md faf writes, verbatim and non-destructive.

→ How to add custom rules · docs.faf.one

✪ Trophy 100% — all or nothing. From v6.6.0 onward, faf-cli recommends only Trophy. 100% on the FCL is what makes the layers above (MD instructions, Agents, AI tooling) work — sub-Trophy leaves gaps that AI guesses on. Sub-Trophy tiers (including Bronze 85) remain on the ladder as honest interim states — they are not deleted; we just no longer aim for 85 as the goal.

One score, three glyphs: ✪ work (CLI · docs · receipts) · 🏆 social (X · blogs) · Trophy Mark PNG (brand). Source of truth: src/core/tiers.ts.

sync:      .faf  ──── 8ms ───→  CLAUDE.md   (pull: Trophy-gated backfill)
tri-sync:  .faf  ←── 8ms ──→  CLAUDE.md ↔ MEMORY.md

The full manual lives at docs.faf.one — facts for devs, faf-cli first. One-page overview: faf-cli.vercel.app.

• Getting started — install · run · use
• Custom rules — pin instructions your AI must follow

For a specific agent: Grok, xAI & Cursor 👀 · Claude Code 👀 · Bun 👀

Pivotal releases — full history in CHANGELOG.md:

• v7.1 — AGENTS.md — faf export --agents authors a complete, non-destructive AGENTS.md.
• v7.0 — GIT — context goes git-native: faf diff / log / hooks.
• v6.16 — Know Your Stack — every emitted file labels your stack identically.
• v6.15 — Copilot — faf export --copilot writes the file GitHub Copilot reads.
• v6.14 — Loop — faf loop drives any repo to ✪ 100% or the honest human wall.
• v6.7 — HTML — faf show renders a .faf to a browsable page. (FAF defines. AGENTS.md instructs. AI codes. HTML shows.)
• v6.6 — Trophy — 100% or nothing.
• v6.0 — Bun — ground-up rewrite; single portable binary, four platforms.

Bun's single-file compiler produces standalone binaries — no runtime needed.

bun run compile                # Current platform
bun run compile:all            # darwin-arm64, darwin-x64, linux-x64, windows-x64

Ship faf as a single binary for CI/CD, Docker, or air-gapped environments.

src/
├── cli.ts              ← Entry point (Commander registrations)
├── commands/           ← one file per faf subcommand
├── core/               ← Types, slots (Mk4), tiers, scorer, schema
├── detect/             ← Framework detection, stack scanner
├── interop/            ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md
├── ui/                 ← Colors (#00D4D4), display
└── wasm/               ← faf-scoring-kernel wrapper (Rust → WASM)

Toolchain: Bun (test, build, compile) · TypeScript (strict) · WASM (scoring kernel)

Robust. Reliable. Next-level WJTTC tested. — The Foundation Edition.

bun test                       # extensive WJTTC + e2e suite

• WJTTC Build Resilience — regression classes locked.
• WJTTC Kernel Stress — WASM kernel boundary tests.
• e2e lifecycle — commands in sequence.

Test reports in reports/.

• GitHub Discussions — Questions, ideas, community
• Email: team@faf.one

If faf-cli has been useful, consider starring the repo — it helps others find it.

If you use faf-cli or the .faf / .fafm / .fafa formats in research or production, please cite the format papers:

Wolfe, J. (2025). Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory. Zenodo. https://doi.org/10.5281/zenodo.20348942

Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641

@article{wolfe2025faf,
  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
  author    = {Wolfe, James},
  year      = {2025},
  month     = {nov},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18251362},
  url       = {https://doi.org/10.5281/zenodo.18251362}
}

@article{wolfe2026fafm,
  title     = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {may},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20348942},
  url       = {https://doi.org/10.5281/zenodo.20348942}
}

@article{wolfe2026fafa,
  title     = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {aug},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21951641},
  url       = {https://doi.org/10.5281/zenodo.21951641}
}

MIT — Free and open source

IANA-registered: application/vnd.faf+yaml (Context Layer) · application/vnd.fafm+yaml (Memory Layer) · application/vnd.fafa+yaml (Agent Layer)

format | driven 🏎️⚡️ wolfejam.dev · faf.one/cli