📚 .faf Documentation

The complete guide to using .faf - The JPEG for AI™

⚡ Quick Start

Get started with .faf in seconds:

# Install globally
npm install -g claude-faf-mcp

# Create your first .faf
faf init my-project

# Add to existing project
cd your-project
faf init .

🔧 Installation

CLI Installation

# NPM
npm install -g claude-faf-mcp

# Yarn
yarn global add claude-faf-mcp

# PNPM
pnpm add -g claude-faf-mcp

Chrome Extension

Install directly from the Chrome Web Store:

Install Chrome Extension →

MCP Server

# Clone and setup
git clone https://github.com/Wolfe-Jam/faf
cd faf
npm install
npm run build

💻 Basic Usage

Creating a .faf file

# Interactive mode
faf init

# With project name
faf init my-awesome-project

# In current directory
faf init .

Updating .faf

# Auto-detect and update
faf update

# Force regeneration
faf update --force

# Custom depth
faf update --depth 5

📋 Format Specification

Structure

A .faf file uses YAML format with these key sections:

project: "Your Project Name"
version: "1.0.0"
description: "Project description"
stack:
  - technology: "Framework/Language"
    version: "x.x.x"

structure:
  type: "tree"
  root: "."
  
rules:
  include:
    - "src/**"
    - "*.config.js"
  exclude:
    - "node_modules"
    - ".git"
    
context: |
  Additional context about your project
  Can be multiple lines

.fafignore

Control what gets included in your context:

# Dependencies
node_modules/
vendor/

# Build outputs  
dist/
build/

# Environment
.env
.env.local

# IDE
.vscode/
.idea/

⌨️ CLI Commands

Command	Description	Options
`faf init`	Initialize a new .faf file	`--force`, `--minimal`
`faf update`	Update existing .faf	`--force`, `--depth`
`faf validate`	Validate .faf format	`--strict`
`faf stats`	Show project statistics	`--json`
`faf export`	Export to other formats	`--format`

🤖 MCP Server

The Model Context Protocol server enables AI models to understand your project structure instantly.

Configuration

{
  "mcpServers": {
    "faf": {
      "command": "node",
      "args": ["path/to/faf-mcp/dist/index.js"],
      "env": {
        "FAF_ROOT": "/path/to/projects"
      }
    }
  }
}

Available Tools

faf_read - Read .faf file contents
faf_update - Update .faf file
faf_validate - Validate format
faf_stats - Get project statistics

🌐 Chrome Extension

The Chrome Extension adds .faf support directly to your browser.

Features

☑️ Auto-detect .faf files on GitHub
☑️ One-click copy to clipboard
☑️ Format validation
☑️ Stats overlay

Keyboard Shortcuts

Shortcut	Action
`Alt+F`	Toggle .faf viewer
`Alt+C`	Copy .faf content
`Alt+S`	Show stats

🔌 API Reference

Node.js API

import { FAF } from 'faf-cli';

// Read .faf file
const faf = await FAF.read('./project.faf');

// Generate .faf
const generated = await FAF.generate({
  path: './my-project',
  depth: 3,
  exclude: ['node_modules']
});

// Validate
const isValid = await FAF.validate(fafContent);

// Get stats
const stats = await FAF.stats('./project.faf');

Response Format

{
  "success": true,
  "data": {
    "project": "string",
    "version": "string",
    "files": number,
    "directories": number,
    "score": number
  },
  "performance": {
    "time": "45ms"
  }
}