gemini-faf-mcp
<!-- faf: gemini-faf-mcp | Python | mcp | FAF MCP server for Google Gemini — persistent project context via PyPI -->
<!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->
# gemini-faf-mcp v3.3 — The Antigravity Edition 🚀
**Persistent Project Context for Google Gemini. Define once. Sync everywhere.**
⭐ [Star it on GitHub](https://github.com/Wolfe-Jam/gemini-faf-mcp): bookmarks it for you, helps other devs find it too.
**FAF defines. AGENTS.md instructs. AI codes.**
☆ Bookmark [the gemini-faf-mcp page](https://wolfe-jam.github.io/gemini-faf-mcp/) for later.
Stop re-explaining your project to every new Gemini session. Every Gemini conversation starts cold — you re-state your stack, your goals, your conventions every single time. `.faf` is one structured file that captures all of it. This package is the MCP server that lets Gemini read it.
<!-- mcp-name: one.faf/gemini-faf-mcp -->
[](https://pypi.org/project/gemini-faf-mcp/)
[](https://faf.one)
[](https://github.com/Wolfe-Jam/gemini-faf-mcp)
[](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
[](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml)
[](https://doi.org/10.5281/zenodo.18251362)
[](https://doi.org/10.5281/zenodo.20348942)
[](https://doi.org/10.5281/zenodo.21951641)
[](https://wolfe-jam.github.io/agent-business-card/?repo=Wolfe-Jam/gemini-faf-mcp)
### Before and after
```
Without FAF With FAF (project.faf filled in)
───────────────────────── ─────────────────────────
You: "I'm using FastAPI with... You: "Add a /users/me endpoint"
PostgreSQL, pytest, and..." Gemini: [writes correct code,
Gemini: "Got it. What's the uses your auth pattern,
codebase like?" matches your test style]
You: "It's a REST API for..."
[5 minutes of re-explaining]
Gemini: [now ready to help]
```
Gemini reads `project.faf` through the faf tools, and `GEMINI.md` written from it loads at session start, so a new session starts with your project.
### What's New in v3.3.3 — The Antigravity Edition 🚀
**3.3.3: one engine, one number, in the Python SDK too.**
- **`validate_faf` gives the same score and tier as `faf_score` and faf-cli** (the always-33 kernel). It used to count its own 10 slots. `valid` now means what it means in `faf_validate` (the structure is valid), `issues` lists each empty slot, and `tier` is upper case (`TROPHY` … `WHITE`). It scores data already parsed; for a file's exact score, use `faf_score`. See the [CHANGELOG](./CHANGELOG.md) for every key that changed.
- **The hosted badge uses faf-cli's tiers** (✪ ★ ◆ ◇ ● ○ ♡), not the retired emoji ladder.
- **The FAQ says only what the code does**, and the Big Orange 🍊 is described as a planned honor, not a score.
#### v3.3.1 — The Antigravity Edition 🚀
**3.3.1: /setup detects your stack; your goal and six W's stay yours.**
- **`/setup` detects your stack first.** It now creates `project.faf` with `faf_auto`, so a new project starts with its language, framework, API type, package manager and test runner filled in. Before, it wrote a starter file that locked the stack, and filling it in afterwards wrote nothing.
- **Your goal and the six W's are yours** (the Human Slots rule, as in faf-cli 8.10). No placeholders or defaults are written into them. A description found in `pyproject.toml` is offered as a suggested goal for you to confirm, not written. Scores now match faf-cli on the same project; a new file scores lower until you fill these in, because empty slots no longer count as filled.
- **`faf_auto` says what it really wrote:** the slots it filled, "unchanged" when none, and detected values it skipped because the slot was already set.
#### v3.3.0 — The Antigravity Edition 🚀
**3.3.0 brings gemini-faf-mcp to Antigravity CLI: install it as a plugin and it works in your project. Simple.**
- **Install it as a plugin** in Antigravity CLI (`agy`, Google's successor to Gemini CLI): `agy plugin install https://github.com/Wolfe-Jam/gemini-faf-mcp`, then run `/setup` in your project. Moving from Gemini CLI, `agy plugin import gemini` converts the extension.
- **It works in your project.** `agy` starts a plugin's server in the plugin's own folder. The plugin now starts Python directly, so the server sees the folder you ran `agy` in, and finds your `project.faf` and writes there. In 3.2.1 this only worked when the server was started by hand.
- **Safe to start anywhere.** A `server.py` (or any module) in your project is never run in place of the server's own, files are read and written as UTF-8 on every platform, and an older installed copy without the fix is never used.
- **The skills are `/setup`, `/score` and `/export` in `agy`** (`/faf:setup` and so on in Gemini CLI).
#### v3.2.1 — The Straight Answers Edition
**3.2.1 lifts gemini-faf-mcp into Antigravity CLI: it installs as a plugin and works in your project.**
- **Installs in Antigravity CLI** (`agy`, Google's successor to Gemini CLI): `agy plugin install https://github.com/Wolfe-Jam/gemini-faf-mcp`. Moving from Gemini CLI, `agy plugin import gemini` now converts the extension cleanly.
- **Works in your project there.** `agy` starts a plugin's server in the plugin's own folder; gemini-faf-mcp now finds your project and writes there, never to a folder broader than it.
- **The skills are `/setup`, `/score` and `/export` in `agy`** (`/faf:setup` and so on in Gemini CLI).
#### v3.2.0 — The Straight Answers Edition
**Every gemini-faf-mcp failure now reaches your client as an error: MCP's isError is set, the reason text is unchanged, and /faf:setup checks before it creates.**
- A missing file, invalid YAML, a refused write, a path outside the project, an unknown model: each now comes back to your client as an error (MCP `isError`), with the same reason text as before. A success is unchanged.
- `faf_score` says when a file isn't valid YAML, using the same reader as the score (faf-cli parity). An empty file still scores 0, White.
- `/faf:setup` looks for a `project.faf` in this folder first, and only creates one when there is none.
**Heads up:** Python scripts that call these tools through FastMCP's `Client.call_tool` now get a `ToolError` on a failure unless they pass `raise_on_error=False`. MCP clients that read `isError` now take their error path, with the same text.
#### v3.1.2
**faf_gemini and faf_agents keep your hand-written GEMINI.md and AGENTS.md, and tell you what they couldn't write.**
- GEMINI.md and AGENTS.md are now written by faf-cli's rules: only faf's own block changes, your text stays, and a file faf can't safely write (not UTF-8, a link out of the project, read-only) is left as it is and named in the reply.
#### v3.1.1
**`gemini-faf-mcp --version` and `--help` answer and exit. Before, both started the server.**
- `--version` (`-V`) prints the version; `--help` (`-h`) prints usage and a client config. Anything else starts the server as before, so your client config doesn't change.
#### v3.1.0 — The New Era Edition
**Glass-box tools: every Gemini tool now says what it does — reads, writes or rewrites — so your client knows when to ask first. In Gemini CLI and Google Antigravity.**
- **Every tool is labelled.** All 13 tools carry MCP tool annotations, matched to what each one does: 8 read only, 4 write without losing anything (`faf_init` never overwrites, `faf_auto` fills empty slots only, `faf_gemini` and `faf_agents` keep your own text), and `faf_migrate` rewrites the file. None reaches the network. Clients that read the labels can let reads run and ask before writes.
- **Its own card.** A refreshed FAF passport (`agent.fafa`, written with faf-cli 8.2's `card init`) and MCP Server Card, both 3.1.0 with all 13 tools and FAF's context.
- **Works in Google Antigravity**, local (`uvx`) or hosted (`serverUrl`). See [Google Antigravity](#google-antigravity) below.
- **A new look:** [the gemini-faf-mcp page](https://wolfe-jam.github.io/gemini-faf-mcp/), redesigned to feel at home for Google developers.
- **The hosted function scores always-33**, the same engine as everything else.
> Earlier: v3.0.0 — **The Always33 Edition** — one engine, one number: the same score as faf-cli 8, claude-faf-mcp 7, faf-mcp 4 and grok-faf-mcp 2.
#### v2.8.2 — The Full-Facts Edition
**Privacy patch — `FAFClient`'s start-up ping is now opt-in (`FAF_TELEMETRY=1`).**
`FAFClient` (the Python SDK client — the MCP server never used it) sent a start-up ping, package name and version, by default, and the opt-out wasn't documented. It now sends only when you set `FAF_TELEMETRY=1`; `FAF_TELEMETRY_OFF` still turns it off. See [faf.one/privacy](https://faf.one/privacy).
> **v2.8.1** was a dependency patch — `faf-python-sdk` floor `>=1.4.0`, where the interop functions are now named `author_agents_md` / `author_gemini_md`. Authored AGENTS.md / GEMINI.md output is byte-identical.
**v2.8.0** — `faf_auto` now grounds its detection in the repo's own files, and every `faf_model` reference template scores 100% Trophy.
`faf_auto` used to read only the root manifest (`pyproject.toml`, `package.json`, …). It now also reads the files that carry the real stack: **docker-compose service images** map onto `database` / `cache` / `search` / `storage` (a running Postgres service *is* the database — it beats a dependency guess), **Makefile / justfile targets** map onto the `commands` block (`test` / `build` / `check-all`, root file or a nested `backend/Makefile`), and **`.github/workflows/`** sets `cicd`. A polyglot repo that reported `library` / `JavaScript` now reports its real Postgres + Redis + FastAPI stack. In parity with faf-cli 7.10.
Separately: the **15 `faf_model` reference templates were scoring 48–57%** — they filled 4 stack slots and used `null`. All rewritten to the full 21-slot schema; every one is 100% Trophy now, and a test keeps it that way. **13 tools · 265 tests.**
> **v2.7.1 / v2.7.0 — The Interop Edition** — `faf_agents` / `faf_gemini` rewritten as `faf-python-sdk` authoring-tool wrappers (were 4-field stubs); new `faf_migrate` brings a `.faf` up to the current format. **v2.6.0 — The Agent Card Edition** added a real `agent.fafa` passport, an MCP Server Card (SEP-2127), and an AI Catalog entry. **v2.5.0 — The Dart Edition** detects Dart/Flutter from `pubspec.yaml`. **v2.4.2 — The Confinement Edition** confined every caller `path` argument. **v2.4.0 — The Chameleon Edition** auto-selects its transport: stdio locally, Streamable HTTP on Cloud Run.
---
## One-Minute Setup
### 1. Install
```bash
uvx gemini-faf-mcp # zero-install run via uvx (fetched from PyPI)
# or: pip3 install gemini-faf-mcp
```
### 2. Add to Antigravity CLI
```bash
agy plugin install https://github.com/Wolfe-Jam/gemini-faf-mcp
```
Antigravity CLI (`agy`) is Google's successor to Gemini CLI ([announcement](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/)). The plugin brings the MCP server and the `setup`, `score` and `export` skills.
**Moving from Gemini CLI?** `agy plugin import gemini` converts the extension you already have. If it stops on `.gemini/project.faf`, that's a link versions up to 3.2.0 shipped: `rm -f ~/.gemini/extensions/gemini-faf-mcp/.gemini/project.faf`, then run the import again, or install fresh with the line above.
Still on Gemini CLI through work? `gemini extensions install https://github.com/Wolfe-Jam/gemini-faf-mcp` installs the same extension.
### 3. Author your project context
Run `/setup` (in Gemini CLI: `/faf:setup`).
That detects your stack from the repo's own files (it calls `faf_auto`), writes `project.faf` and scores it. Then fill in what only you know (the goal, who it's for, why it exists), and run `/score` (`/faf:score` in Gemini CLI) to see what's left. From then on, Gemini reads it through the faf tools; `/export` writes `GEMINI.md` from it, which Gemini loads at the start of every session.
> **Tip:** Trophy ✪ = 100%: AI is optimized to code. `/score` shows exactly which slots are still empty.
---
## The "One-File" Advantage
A `.faf` file is structured YAML that captures your project DNA. Every AI agent reads it once and knows exactly what you're building.
```yaml
# project.faf — your project, machine-readable
faf_version: "3.0"
project:
name: my-api
goal: REST API for user management
main_language: Python
stack:
backend: FastAPI
database: PostgreSQL
testing: pytest
human_context:
who: Backend developers
what: User CRUD with auth
why: Replace legacy PHP service
```
**Result:** Gemini knows your stack and goal from the file, not from you re-typing them each session.
> **FAF defines. MD instructs. AI codes.**
### What about my `GEMINI.md`?
You don't replace it. `.faf` **authors** it. Run `faf_gemini` and you get a fresh `GEMINI.md` in Gemini CLI's own hierarchical, `@file`-importable convention — setup, verify, key files, stack, confirm-first actions — authored from a single source of truth instead of hand-maintained. Your hand-written content outside the faf-managed block is preserved.
```bash
> /faf:export
# Authors GEMINI.md from project.faf (in Antigravity: /export)
```
`.faf` is the source. `GEMINI.md` is one of its outputs. Same logic for `AGENTS.md` (OpenAI Codex), `.cursorrules`, `CLAUDE.md`, and others — write once, render everywhere.
---
## Auto-Detect Your Stack
`faf_auto` scans your project's manifest files **and its docker-compose services, Makefile targets, and CI config**, then authors a `.faf` with accurate slot values. No manual entry needed.
```
> Auto-detect my project stack
```
```json
{
"detected": {
"main_language": "Python",
"package_manager": "pip",
"framework": "FastAPI",
"api_type": "REST",
"database": "PostgreSQL",
"cache": "Redis",
"hosting": "Docker Compose",
"commands": { "test": "make test", "build": "make build", "lint": "make check-all" }
},
"score": 56,
"tier": "YELLOW"
}
```
Shortened output from a real 3.3.3 run on a FastAPI project. `database` and `cache` came from `docker-compose.yml` and `commands` from the `Makefile`; `cicd: GitHub Actions` (from `.github/workflows/`) is written to the file too. None of these come from the manifest. The goal and the six W's are yours to fill in.
**What it scans:**
| File | Detects |
|------|---------|
| `pyproject.toml` | Python + build system + frameworks (FastAPI, Django, Flask, FastMCP) |
| `package.json` | JavaScript/TypeScript + frameworks (React, Vue, Next.js, Express) |
| `Cargo.toml` | Rust + cargo + frameworks (Axum, Actix) |
| `go.mod` | Go + go modules + frameworks (Gin, Echo) |
| `requirements.txt` / `Gemfile` / `composer.json` | Python (fallback) / Ruby / PHP |
| **`docker-compose.yml`** | **`database` / `cache` / `search` / `storage` from service images (Postgres, Redis, Elasticsearch, MinIO, ClickHouse, Qdrant, …)** |
| **`Makefile` / `justfile`** | **`test` / `build` / `lint` commands from targets (root, or a nested `backend/` dir)** |
| **`.github/workflows/`** | **`cicd: GitHub Actions` (also GitLab CI, CircleCI)** |
**Priority rule:** `pyproject.toml` / `Cargo.toml` / `go.mod` take priority over `package.json`. File-facts (a real compose service, a Makefile target) win over dependency guesses. Only sets values that are actually detected — no hardcoded defaults.
---
## Google Antigravity
Antigravity reads MCP servers from `~/.gemini/config/mcp_config.json` (every project) or `.agents/mcp_config.json` (one project); both take both modes. A plugin installed with `agy plugin install` brings its own.
Local (stdio):
```json
{ "mcpServers": { "gemini-faf": { "command": "uvx", "args": ["gemini-faf-mcp"] } } }
```
Hosted:
```json
{ "mcpServers": { "gemini-faf": { "serverUrl": "https://mcpaas.live/gemini/mcp/v1" } } }
```
Antigravity expects `serverUrl`, not `url` or `httpUrl`.
## All 13 Tools
Real input and output for every tool: [docs/TOOLS.md](docs/TOOLS.md). Install, first run and fixes: [docs/SETUP.md](docs/SETUP.md).
Every tool carries MCP tool annotations: **read only** (`faf_read`, `faf_validate`, `faf_score`, `faf_discover`, `faf_stringify`, `faf_context`, `faf_about`, `faf_model`), **writes without losing anything** (`faf_init`, `faf_auto`, `faf_gemini`, `faf_agents`), **rewrites the file** (`faf_migrate`).
### Create & Detect
| Tool | What it does |
|------|-------------|
| `faf_init` | Create a starter `.faf` file with project name, goal, and language |
| `faf_auto` | Auto-detect stack from manifest files and author/update `.faf` |
| `faf_discover` | Find `.faf` files in the project tree |
### Validate & Score
| Tool | What it does |
|------|-------------|
| `faf_validate` | Full Mk4 validation — score, tier, slot counts, errors, warnings |
| `faf_score` | Quick Mk4 score — score, tier, populated/active/total slot counts |
### Read & Transform
| Tool | What it does |
|------|-------------|
| `faf_read` | Parse a `.faf` file into structured data |
| `faf_stringify` | Convert parsed FAF data back to clean YAML |
| `faf_context` | Get Gemini-optimized context (project + stack + score) |
### Export & Interop
| Tool | What it does |
|------|-------------|
| `faf_gemini` | Export `GEMINI.md` in Gemini CLI's hierarchical convention (non-destructive) |
| `faf_agents` | Export a BETTER-shaped `AGENTS.md` for OpenAI Codex, Cursor, and other AI tools (non-destructive) |
### Migrate
| Tool | What it does |
|------|-------------|
| `faf_migrate` | Bring a `.faf` up to the current format version (3.0); `dry_run` to preview |
### Reference
| Tool | What it does |
|------|-------------|
| `faf_about` | FAF format info — IANA registration, version, ecosystem |
| `faf_model` | Get a 100% Trophy-scored example `.faf` for any of 15 project types |
---
## Score and Tier System
Your `.faf` file is scored on completeness — how many slots are filled with real values.
| Score | Tier | Meaning |
|-------|------|---------|
| 100% | TROPHY | AI has full context for your project |
| 99% | GOLD | Exceptional |
| 95% | SILVER | Top tier |
| 85% | BRONZE | Minimum recommended — AI can build from here |
| 70% | GREEN | Solid foundation |
| 55% | YELLOW | Needs improvement |
| <55% | RED | Major gaps — AI will guess |
| 0% | WHITE | Empty |
**Aim for Bronze (85%+).** That's where AI stops guessing and starts knowing.
---
## Using with Antigravity or Gemini CLI
```
> Create a .faf file for my Python FastAPI project
> Auto-detect my project and fill in the stack
> Score my .faf and show what's missing
> Export GEMINI.md for this project
> Show me a 100% example for an MCP server
> What is FAF and how does it work?
> Read my project.faf and summarize the stack
> Validate my .faf and fix the warnings
> Migrate my project.faf to the current format
```
---
## Architecture
```
gemini-faf-mcp v3.3.3
├── server.py → FastMCP MCP server (13 tools, dual-transport, Mk4 scoring)
├── safe_path.py → path confinement for caller-supplied `path` args
├── inject.py → non-destructive faf-managed-block injection
├── interrogate.py → Full-Facts grounding (docker-compose + Makefile signals)
├── main.py → Cloud Run REST API (GET/POST/PUT)
├── models.py → 15 project type examples
└── src/gemini_faf_mcp/ → Python SDK (FAFClient, parser)
```
The MCP server delegates to `faf-python-sdk` for parsing, validation, Mk4 scoring, and AGENTS.md / GEMINI.md authoring. Stack detection in `faf_auto` — including the Full-Facts grounding — is Python-native, no external CLI dependencies.
---
## Testing
Clone, dev install and the full suite: [CONTRIBUTING.md](./CONTRIBUTING.md).
390 tests passing across the FastMCP server, CLI flags, Cloud Function, Mk4 WJTTC championship, Full-Facts grounding, path-confinement, write-guard, model-parity, Dart detection, and client-telemetry suites. Championship-grade test coverage — [WJTTC](https://github.com/Wolfe-Jam/wjttc-public).
---
## FAF Ecosystem
One format, every AI platform.
| Package | Platform | Registry |
|---------|----------|----------|
| [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm + MCP #2759 |
| **gemini-faf-mcp** | **Google** | **PyPI** |
| [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |
| [rust-faf-mcp](https://crates.io/crates/rust-faf-mcp) | Rust | crates.io |
| [faf-cli](https://npmjs.com/package/faf-cli) | Universal | npm |
---
## Python SDK
Use FAF directly in Python without MCP:
```python
from gemini_faf_mcp import FAFClient, parse_faf, validate_faf, find_faf_file
# Parse and validate locally
data = parse_faf("project.faf")
result = validate_faf(data)
print(f"Score: {result['score']}%, Tier: {result['tier']}")
# validate_faf scores data already parsed; for a file's exact score (same as faf-cli), use the faf_score tool
# Find .faf files automatically
faf_path = find_faf_file(".")
# Or use the Cloud Run endpoint
client = FAFClient()
dna = client.get_project_dna()
```
`FAFClient` sends no telemetry unless you set `FAF_TELEMETRY=1`, which adds one start-up ping (package name and version). `FAF_TELEMETRY_OFF` always turns it off. Remote mode sends your requests to the Cloud Run endpoint. Privacy: [faf.one/privacy](https://faf.one/privacy).
---
## Cloud Run REST API
Live endpoint for badges, multi-agent context brokering, and voice-to-FAF mutations.
```
https://faf-source-of-truth-631316210911.us-east1.run.app
```
Supports agent-optimized responses (Gemini, Claude, Grok, Jules, Codex/Copilot/Cursor) via `X-FAF-Agent` header. Voice mutations via Gemini Live through PUT endpoint. Auto-deploys via Cloud Build on push to `main`.
---
If `gemini-faf-mcp` has been useful, consider starring the repo — it helps others find it.
---
## Links
- [FAF Specification](https://faf.one)
- [IANA Registration](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
- [faf-python-sdk](https://pypi.org/project/faf-python-sdk/)
- [faf-cli](https://npmjs.com/package/faf-cli)
- [Changelog](./CHANGELOG.md)
## Citation
If you use `gemini-faf-mcp` 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
### BibTeX
```bibtex
@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}
}
```
## License
MIT
---
Built by [@wolfe_jam](https://x.com/wolfe_jam) | [wolfejam.dev](https://wolfejam.dev)
---
### Get the CLI
> **faf-cli** — the original AI-context CLI.
```bash
npx faf-cli auto
```
**Anthropic MCP [#2759](https://github.com/modelcontextprotocol/servers/pull/2759)** · **IANA Registered:** `application/vnd.faf+yaml` · [faf.one](https://faf.one) · [npm](https://www.npmjs.com/package/faf-cli)
TDQS
Scored across 13 tools
Most tools target distinct operations (read, discover, init, migrate, export), and the descriptions actively differentiate the two closest pairs: faf_validate vs faf_score (error details vs quick status) and faf_read vs faf_context (full structure vs AI-optimized subset). The overlap is real but the guidance reduces misselection, leaving only mild ambiguity.
Every tool uses a uniform faf_ prefix followed by a single snake_case noun/verb (faf_read, faf_score, faf_discover, faf_migrate). The pattern is fully predictable throughout with no mixed conventions.
13 tools sit squarely in the well-scoped 3-15 range, and each maps to a concrete lifecycle step (discover, init/auto, read/context, validate/score, stringify, migrate, export). No tool feels redundant or padded.
The surface covers the full FAF lifecycle: discovery, creation (init/auto), reading (read/context), validation/scoring, serialization, migration, and two export targets (GEMINI.md, AGENTS.md). Minor gaps exist — no explicit delete/edit for arbitrary slots and no updater beyond faf_auto filling empty slots — but core workflows are covered.