faf

Home: faf.one/cli

FAF defines. MD instructs. AI codes.

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.

---

Install

bunx faf                      # Bun — zero install, fastest path
npx faf                       # npm — works everywhere
brew install faf-cli && faf   # Homebrew

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

---

Nelly Never Forgets

Run faf with no arguments:

---

v6.14 — The Loop Edition

faf loop drives any repo to 🏆 100% or the honest human wall — sourcing every slot it can with provenance, asking only what only you know, never inventing.

faf loop    # init → auto → score, then ask only the human-only gaps

The loop sources what detection can, then stops at one of three honest terminals: done (🏆 100%), needs-human (it asks only the slots only you can answer), or stuck (it sourced everything sourceable and nothing's left for a human to add). It never fabricates a slot to reach 100% — sourced 6Ws now carry provenance ({value, source, confidence}), so every seeded value is a confirm-or-edit suggestion, never an auto-confirmed guess.

---

v6.13 — The Dart Edition

faf now understands Dart and Flutter projects. Content-aware pubspec.yaml classification — Flutter app vs reusable package · Dart server (Serverpod / Dart Frog / Shelf) / CLI / MCP — pure Dart stays Dart. The single-source engine faf-python-sdk and the MCPs compose, parity-tested across languages.

faf auto    # reads pubspec.yaml → Dart/Flutter into project.faf

A pubspec alone no longer means "Flutter": faf reads the dependencies and classifies — a Flutter app, a reusable package, a Dart server, a CLI, or a Dart MCP server. The detection knowledge lives in one spec (dart-detection.json) that faf-cli, faf-python-sdk, and the MCPs all share.

---

v6.12 — The Single-Source Edition

faf-cli is now the single source for the registry _meta — it emits the one.faf/context block every FAF MCP server composes: registryMeta/registryName/fafContextBlock, one deterministic projection, byte-identical, end-to-end across every surface, verifiable by sha, re-derivable instantly on-demand.