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.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.

import { registryMeta, registryName } from 'faf-cli';

serverJson.name  = registryName(faf);   // → one.faf/<name>, derived from project.homepage
serverJson._meta = registryMeta(faf);   // nests one.faf/context under publisher-provided (4 KB cap)

Honest-first: the block carries { faf, mediaType, iana, deterministic, generated } — no baked score. One emitter, every door, byte-identical.

---

v6.11 — The Ledger Edition

faf bench --submit posts your cold-vs-grounded receipt to the public ledger — the context bench goes public, one command. Run the grounding benchmark, then submit the full pair receipt:

faf bench --submit