Read project DNA from a .faf file. Returns the full parsed structure including project info, stack, preferences, and scoring data. Use this as the first step to understand any FAF-enabled project.

Validate a .faf file and return score, tier, and issues. Returns errors (must fix) and warnings (should fix) with specific messages. Use after faf_init or when checking if a .faf file meets quality standards.

Quick Mk4 score check — returns score (0-100%), tier, and slot counts. Uses the Mk4 Championship 21-slot scoring engine for universal parity. Use this for status checks; use faf_validate when you need error details.

Find .faf files in the project tree by walking up from start_dir. Searches the current directory and parent directories for project.faf. Use this before faf_read to locate the file automatically.

Create a starter .faf file with project name, goal, and language. Writes a valid FAF YAML file with all required sections. Will not overwrite an existing file — use faf_discover first to check. The path is confined to the project root (cwd / FAF_ALLOWED_ROOTS).

Convert parsed FAF data back to YAML string. Useful for displaying the raw .faf content or preparing it for editing. Reads the file, parses it, then re-serializes to clean YAML.

Get Gemini-optimized context from a .faf file. Returns the key sections an AI needs: project info, stack, instructions, and score. Use this to quickly understand a project without reading the full .faf structure.

Export and write GEMINI.md from a .faf file (non-destructive). Authors GEMINI.md in Gemini CLI's own convention (hierarchical, @file-importable — setup · verify · key files · stack · confirm-first actions) via faf-python-sdk's authoring tool, in parity with faf-cli's faf export --gemini. Injects it as a faf-managed block, preserving any hand content. Re-running updates the block in place.

Export and write AGENTS.md from a .faf file (non-destructive). Authors a BETTER-shaped AGENTS.md (setup · tests · layout · conventions · three-tier guardrails · definition of done · security · commit) via faf-python-sdk's authoring tool — in parity with faf-cli's faf export --agents. Injects it into AGENTS.md as a faf-managed block, preserving any hand content. Re-running updates the block in place — it never overwrites your file.

Migrate a .faf file to the current format version (3.0). Bumps faf_version, ensures the section roots exist (project, stack, human_context, monorepo), and re-serializes. Legacy slot names (frontend/database/…) still score via the registry's aliases — this only touches the version and structure, never your values. Parity with faf-cli's faf migrate. Pass dry_run=true to preview.

FAF format info — IANA registration, version, ecosystem. Returns metadata about the FAF format, server version, and available MCP bridges. Use this when users ask what FAF is or how it connects to other AI platforms.

Get a 100% Trophy-scored example .faf file for a specific project type. Returns a complete, realistic project.faf that fills all 21 scored slots. Use this as a reference when building or improving a .faf file — shows exactly what 100% looks like. Call without arguments to list all 15 available project types.

Auto-detect project stack and author/update a .faf file. Scans package.json, pyproject.toml, Cargo.toml, go.mod, and other manifest files for language, framework, database, API type, and build tools — then grounds the result in the repo's own files: docker-compose service images (Postgres, Redis, Elasticsearch...) map onto stack slots, and Makefile / justfile targets map onto test / build / lint commands. Facts from files, no hardcoded defaults. Creates a new .faf if none exists, or fills empty slots in an existing one.