faf-cli 7.1.3 → 7.2.0

package/README.md

@@ -3,11 +3,11 @@
 
 <div align="center">
 
-**CONTEXT, versioned.**
-
-<img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="72" />
-
-# faf-cli
+<h1>
+<img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="72" /><br>
+faf-cli<br>
+<sub><sub>CONTEXT, versioned.</sub></sub>
+</h1>
 
 ### The context every AI coding agent reads — authored from your repo, never guessed.
 
@@ -21,10 +21,11 @@ detected from your real stack, scored, and versioned with your code. No drift. N
 [![downloads](https://img.shields.io/npm/dt/faf-cli?color=008B8B&label=downloads)](https://www.npmjs.com/package/faf-cli)
 [![npm](https://img.shields.io/npm/v/faf-cli?color=00CCFF)](https://www.npmjs.com/package/faf-cli)
 
+<br>
+
 **115,000+ downloads across the FAF ecosystem · IANA-registered · Anthropic-merged (#2759)**
 
-⭐ **If faf-cli saves you setup time, a star helps other devs find it** —<br>
-despite all our downloads, ~3 of 4 developers check stars before adopting.
+⭐ **A star helps other devs find faf-cli** — despite the downloads, ~3 of 4 devs check stars.
 
 <!-- ② papers · funnel · testing — one line -->
 [![DOI: Context paper](https://img.shields.io/badge/DOI-Context%20paper-FF6B35)](https://doi.org/10.5281/zenodo.18251362)
@@ -33,7 +34,7 @@ despite all our downloads, ~3 of 4 developers check stars before adopting.
 [![TAF](./badge.svg)](https://github.com/Wolfe-Jam/faf-taf-git)
 [![CI](https://github.com/Wolfe-Jam/faf-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/faf-cli/actions/workflows/ci.yml)
 
-**[faf.one/cli](https://faf.one/cli)** · FAF defines. MD instructs. AI codes.
+FAF defines. MD instructs. AI codes.
 
 <!-- trophy — bottom of hero -->
 [![FAF Trophy 100%](https://img.shields.io/badge/FAF-%F0%9F%8F%86%20100%25-000000?labelColor=FF6B35)](https://faf.one)
@@ -69,271 +70,73 @@ brew install wolfe-jam/faf/faf-cli && faf   # Homebrew (auto-taps)
 
 ---
 
-## Nelly Never Forgets
-
-Run `faf` with no arguments:
-
-![faf](./nelly.png)
-
----
-
-## v7.1 — The AGENTS.md Edition
-
-**`faf export --agents` now authors a complete, best-in-class AGENTS.md for any repo — detected from your code, non-destructive, never stale.**
-
-Point it at any repo and it detects your build/test commands, key files, conventions (ESLint/Prettier/strict/ruff/mypy…), and guardrails — then writes the definitive AGENTS.md: orientation, setup, tests, where-things-live, conventions, three-tier guardrails, a Definition of Done composed from your real commands, and secrets handling. Facts, not bloat. Your hand-written content is preserved.
-
-```bash
-npx faf-cli export --agents
-```
-
----
-
-## Context for AI agents
-
-FAF-CLI authors the files agents read (AGENTS.md, CLAUDE.md, .cursorrules) from real project detection — zero-install via `bunx faf`.
-
-- [→ FAF-CLI for Grok, xAI & Cursor 👀](docs/faf-cli-for-agents.md)
-- [→ FAF-CLI for Claude Code 👀](docs/faf-cli-for-claude.md)
-- [→ FAF-CLI for Bun 👀](docs/faf-cli-for-bun.md)
-
-## v7.0 — The GIT Version
-
-**FAF is to Context what Git is to Versions.**
-
-Git gave your *code* diff, log, blame, hooks, CI. v7.0 gives your *context* the same — `project.faf` is now a git-native artifact:
-
-- **`faf diff`** — semantic context diff + score delta between any two refs (`85% ● → 100% 🏆`)
-- **`git diff` speaks .faf** — `faf diff --install-driver` makes native `git diff` / `log -p` / `show` render the delta
-- **`faf log`** — the score timeline across history (Proof-Over-Time)
-- **`faf hooks --install`** — pre-commit guard: warn, or `--strict` block, on a context regression
-- **`faf git owner/repo --ref <tag>`** — instant, *versioned*, scored context from any repo
-
-Purely additive — a safe upgrade. (One change: `faf git` now refuses to overwrite an existing `project.faf` — pass `--force`.)
-
-## v6.16 — Know Your Stack
-
-**FAF knows your stack — and now labels it identically in every file it writes: CLAUDE.md, AGENTS.md, copilot-instructions.md, GEMINI.md, .cursorrules.**
-
-```bash
-faf export --all     # CLAUDE.md · AGENTS.md · copilot-instructions.md · GEMINI.md · .cursorrules
-```
-
-FAF *knows your stack* — all 33 canonical slots now carry their display label in the registry, so `api_type` → **API**, `cicd` → **CI/CD**, `frontend` → **Framework**, the same way in **every** emitted file. GEMINI.md and `.cursorrules` were raw-key dumps; now they read like the rest. And `.github/copilot-instructions.md` gets a ground-up **Copilot-grade** rewrite — a prose overview, a `## Build & run` command section, GitHub-spec framing. Copilot enhancements, and more.
-
----
-
-## v6.15 — The Copilot Edition
-
-**FAF now writes the file GitHub Copilot reads.**
-
-```bash
-faf export --copilot     # → .github/copilot-instructions.md (every Copilot surface reads it)
-faf git owner/repo       # instant scored .faf from any GitHub repo (now injection-hardened)
-```
-
-`faf export --copilot` emits GitHub Copilot's repository-wide instruction file — the **widest-surface** one, read by default across web chat, code review, VS Code, JetBrains, the CLI, and the coding agent. `faf git` is now hardened against URL command injection (no-shell `execFileSync` + a strict allowlist). Shipped with an exemplary WJTTC Git suite that adopts the full five tiers — **BRAKE · ENGINE · AERO · TYRE · PIT**.
-
----
-
-## 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.
+## Quick Start
 
 ```bash
-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.
+# ANY GitHub repo — no clone, no install, 2 seconds
+bunx faf-cli git https://github.com/facebook/react
 
-```bash
-faf auto    # reads pubspec.yaml → Dart/Flutter into project.faf
+# Your own project
+bunx faf-cli init              # Create .faf
+bunx faf-cli auto              # Zero to 100% in one command
+bunx faf-cli go                # Interactive interview to gold code
 ```
 
-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.
+## Nelly Never Forgets
 
-```ts
-import { registryMeta, registryName } from 'faf-cli';
+Run `faf` with no arguments:
 
-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)
-```
+![faf](./nelly.png)
 
-Honest-first: the block carries `{ faf, mediaType, iana, deterministic, generated }` — **no baked score**. One emitter, every door, byte-identical.
+> **faf-cli dogfoods itself** — [project.faf](./project.faf) is source DNA; [CLAUDE.md](./CLAUDE.md) and [GEMINI.md](./GEMINI.md) are authored from it via `faf`. [AGENTS.md](./AGENTS.md) is the **BETTER** ops briefing (hand-kept for agents; `faf export --agents` still authors AGENTS.md for other repos).
 
 ---
 
-## v6.11 — The Ledger Edition
+## Commands
 
-**`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:
+| Command | What it does |
+|---------|--------------|
+| `faf init` | Create `project.faf` from your local project |
+| `faf git <url>` | Instant `.faf` from any GitHub repo — no clone |
+| `faf auto` | Detect stack, fill every slot it can, score |
+| `faf go` | Guided interview to fill the human-only slots |
+| `faf score` | Check AI-readiness (0–100%) |
+| `faf export` | Author `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules` |
+| `faf sync` | Bi-directional `.faf` ↔ `CLAUDE.md` |
+| `faf memory` | `.fafm` soul ops — convert Claude memory, etch, recall, ls, show |
+| `faf diff` / `log` | Semantic context diff + score timeline across git history |
+| `faf hooks --install` | Pre-commit guard against context regression |
+| `faf compile` / `decompile` | `.faf` ↔ `.fafb` sealed binary |
+| `faf check` | Validate a `.faf` file |
+| `faf recover` | Rebuild `.faf` from an existing `CLAUDE.md` / `AGENTS.md` |
+| `faf show` | Render `project.faf` to a browsable HTML page |
+| `faf formats` | List supported stacks and formats |
+
+Run `faf --help` for the full command set and options.
+
+### Memory (`.fafm`) — new in 7.2.0
+
+Portable agent memory in the IANA-registered [`.fafm`](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml) format. Same INTEROP as [claude-fafm-sdk 1.0](https://pypi.org/project/claude-fafm-sdk/).
 
 ```bash
-faf bench --submit
-```
+# Claude Code memory dir → soul.fafm
+faf memory convert ~/.claude/projects/.../memory -o soul.fafm
 
-The benchmark stops being a private number and becomes a shared, verifiable receipt on the public ledger. Also new: `relentlessContext` / `assembleFreshFaf` and the `buildTableOf8` interview keystone join the public API.
-
-## v6.10 — The Composed Edition
-
-**Every FAF MCP composes single-source engines, never reimplements them.** Turbo-Cat (the ~200-format knowledge base) and the bench engine join the public API, alongside scoring and the 6Ws Interview:
-
-```ts
-import { turboCatScan, deriveQuestionSet, publicQuestions, gradeAnswers, buildReceipt } from 'faf-cli';
+faf memory ls                    # ranked facts
+faf memory recall "your query"   # deterministic filter + rank
+faf memory etch "a durable fact" --id my-fact
+faf memory show
 ```
 
-- **Turbo-Cat composed** — `turboCatScan` / `turboCatSlots`: per-format breakdown + stack signature, sourced-only, deterministic, pure read. The MCPs retire their hardcoded format maps.
-- **Bench composed** — derive questions from any `.faf` (the answer key stays server-side via `publicQuestions`), grade mechanically, emit the `✪` receipt. One grading engine, byte-identical everywhere.
-- **`✪` = one convention** — parity · trust · bench all emit sha256-over-canonical-projection receipts any third party can re-derive.
-
 ---
 
-## v6.9 — The Grounded Edition
+## Custom instructions
 
-**Grounding becomes a first-class primitive: `faf bench` proves it, the 6Ws Interview single-sources it, `faf refresh` keeps it.**
+Your own rules for the AI — *"use full words in identifiers," "use bun, not npm"* — go in `project.faf` under `ai_instructions.warnings`. They land at the top of every `AGENTS.md` faf writes, verbatim and non-destructive.
 
-- **`faf bench`** — the AI-grounding benchmark. Cold vs with-faf, two numbers (answers right, tokens burned), and **the `.faf` is the answer key** — grading is mechanical, the receipt is a verifiable `✪` sha256. A low cold score is an alarm bell: you are hemorrhaging tokens and the AI is guessing at what you're building. `faf bench` → protocol, `faf bench questions` → hand them to any AI, `faf bench grade answers.json --cold|--faf` → the pair.
-- **The 6Ws Interview, exported** — the 8-question core (name + goal + the six Ws) plus the stack interview now ship as the public API (`SIX_WS_INTERVIEW`, `questionForSlot`, `interviewForMissing`). One registry; every consumer (CLI, MCPs, UIs) asks the same questions. Question drift is dead.
-- **`faf refresh`** — the re-ground: re-score the live `.faf`, measure drift vs the DNA baseline (`drift: 43% ↑ 55% (+12)`), keep an existing `.fafb` fast tier compiled current, record the journey. `drift → refresh → re-grounded`.
-
----
-
-## v6.7 — The HTML Edition
-
-**We rendered a `.faf`. 🔥 The day we *saw* FAF.**
-
-A major development — not a new flag, a new way to *see* what your AI
-works from. A `.faf` was always machine-readable. Now it is
-human-visible.
-
-```
-faf show
-```
-
-**What:** one verb renders your *current* `project.faf` to a
-self-contained `project.html` and opens it — score, tier, the 6 W's,
-the stack, in any browser.
-
-**Why it matters:** HTML shows **on-demand** — current truth, never a
-stale snapshot — **visuals for human *and team* review.** The same
-context your AI reads, now reviewable by people. Trophy renders the
-earned award; sub-Trophy renders the honest gaps — a map, not a
-verdict. Humans like visuals. We gave them one.
-
-It is a **cross-check**: see what your AI sees, then improve what it is
-working with **at the root** — the `project.faf` itself, not the
-symptoms.
-
-This is the **4th pillar**:
-
-> **FAF defines. MD instructs. AI codes. HTML shows.**
-
-`faf show` · `faf export --html` · a public render API
-(`generateProjectHtml`) — one single-sourced renderer, no reinvention.
-
-Receipts → [CHANGELOG](./CHANGELOG.md)
-
----
-
-## v6.6 — The Trophy Edition
-
-Until now we have had 85% as a recommended minimum. **It's now 100%! 🏆 All or nothing.**
-
-AI gets its best shot at assisting you. **Period.**
-
-We are able to do this because we can now get you to 100% on virtually any app-type.
-
-**FAF Init > Auto > Go = 100%.**
-
-`faf sync` locks MD ↔ FAF with 100% 🏆 — anti-hallucination, pro-code.
-
-(Adding `about` — the 20th app-type — made the ladder hit a score. *How no-score became a score.* Fitting, because v6.6 is when that score became the only one we recommend.)
-
-Receipts → [CHANGELOG](./CHANGELOG.md)
-
----
-
-## v6.0 — Built with Bun
-
-v6 is a ground-up rewrite. All-in on Bun — same toolchain as Claude Code.
-
-| | Claude Code | faf-cli v6 |
-|-|-------------|------------|
-| **Runtime** | Bun | Bun (`bunx`) |
-| **Test** | Bun | `bun test` |
-| **Build** | Bun | `bun build` |
-| **Language** | TypeScript | TypeScript |
-| **Compile** | Bun bytecode | `bun build --compile` |
-
-880 tests in ~18s. 296KB bundle in 2.4s. Single portable binary, 4 platforms. npx backward-compatible.
-
-32 commands. 880 tests. WJTTC-tested. 93% smaller than v5.
-
-```
-commands → interop → core → wasm
-```
-
-The WASM scoring kernel (`faf-scoring-kernel` 2.0.0) does the math. Bun does the delivery.
-
----
-
-## Commands
-
-| # | Command | One-liner |
-|---|---------|-----------|
-| 1 | `faf init` | Create `.faf` from your local project |
-| 2 | `faf git <url>` | Instant `.faf` from any GitHub repo — no clone |
-| 3 | `faf auto` | Zero to 100% in one command |
-| 4 | `faf go` | Guided interview to gold code |
-| 5 | `faf score` | Check AI-readiness (0-100%) |
-| 6 | `faf sync` | `.faf` ↔ CLAUDE.md (bi-sync, mtime auto-direction) |
-| 7 | `faf compile` | `.faf` → `.fafb` binary — sealed, portable, deterministic |
-| 8 | `faf decompile` | `.fafb` → JSON |
-| 9 | `faf export` | Author AGENTS.md, .cursorrules, GEMINI.md |
-| 10 | `faf check` | Validate `.faf` file |
-| 11 | `faf edit` | Edit `.faf` fields inline |
-| 12 | `faf convert` | Convert `.faf` to JSON |
-| 13 | `faf drift` | Check context drift |
-| 14 | `faf context` | Author context output |
-| 15 | `faf recover` | Recover `.faf` from CLAUDE.md / AGENTS.md |
-| 16 | `faf migrate` | Migrate `.faf` to latest version |
-| 17 | `faf search` | Search slots and formats |
-| 18 | `faf share` | Share `.faf` via URL |
-| 19 | `faf taf` | Generate TAF test receipt |
-| 20 | `faf demo` | Demo walkthrough |
-| 21 | `faf ai` | AI-powered enhance & analyze |
-| 22 | `faf pro` | Pro features & licensing |
-| 23 | `faf conductor` | Conductor integration |
-| 24 | `faf formats` | Show supported formats |
-| 25 | `faf info` | Version and system info |
-| 26 | `faf clear` | Clear cached data |
-
-Run `faf --help` for full options.
-
----
-
-## Quick Start
-
-```bash
-# ANY GitHub repo — no clone, no install, 2 seconds
-bunx faf-cli git https://github.com/facebook/react
-
-# Your own project
-bunx faf-cli init              # Create .faf
-bunx faf-cli auto              # Zero to 100% in one command
-bunx faf-cli go                # Interactive interview to gold code
-```
+**→ [How to add custom rules](https://docs.faf.one/custom-rules)** · [docs.faf.one](https://docs.faf.one)
 
 ---
 
@@ -359,12 +162,38 @@ bunx faf-cli go                # Interactive interview to gold code
 ## Sync
 
 ```
-bi-sync:   .faf  ←── 8ms ──→  CLAUDE.md                (free forever)
-tri-sync:  .faf  ←── 8ms ──→  CLAUDE.md ↔ MEMORY.md    (Pro)
+bi-sync:   .faf  ←── 8ms ──→  CLAUDE.md
+tri-sync:  .faf  ←── 8ms ──→  CLAUDE.md ↔ MEMORY.md
 ```
 
 ---
 
+## Docs
+
+The full manual lives at **[docs.faf.one](https://docs.faf.one)** — facts for devs, faf-cli first.
+
+- [Getting started](https://docs.faf.one/getting-started) — install · run · use
+- [Custom rules](https://docs.faf.one/custom-rules) — pin instructions your AI must follow
+
+For a specific agent: [Grok, xAI & Cursor 👀](docs/faf-cli-for-agents.md) · [Claude Code 👀](docs/faf-cli-for-claude.md) · [Bun 👀](docs/faf-cli-for-bun.md)
+
+---
+
+## Recent editions
+
+Pivotal releases — full history in [CHANGELOG.md](./CHANGELOG.md):
+
+- **v7.1 — AGENTS.md** — `faf export --agents` authors a complete, non-destructive `AGENTS.md`.
+- **v7.0 — GIT** — context goes git-native: `faf diff` / `log` / `hooks`.
+- **v6.16 — Know Your Stack** — every emitted file labels your stack identically.
+- **v6.15 — Copilot** — `faf export --copilot` writes the file GitHub Copilot reads.
+- **v6.14 — Loop** — `faf loop` drives any repo to 🏆 100% or the honest human wall.
+- **v6.7 — HTML** — `faf show` renders a `.faf` to a browsable page. *(FAF defines. MD instructs. AI codes. HTML shows.)*
+- **v6.6 — Trophy** — 100% or nothing.
+- **v6.0 — Bun** — ground-up rewrite; single portable binary, four platforms.
+
+---
+
 ## Compiled Binaries
 
 Bun's single-file compiler produces standalone binaries — no runtime needed.
@@ -382,9 +211,9 @@ Ship `faf` as a single binary for CI/CD, Docker, or air-gapped environments.
 
 ```
 src/
-├── cli.ts              ← Entry point, 26 command registrations
-├── commands/           ← 26 command files (1 per command)
-├── core/               ← Types, slots (33 Mk4), tiers, scorer, schema
+├── cli.ts              ← Entry point (Commander registrations)
+├── commands/           ← one file per faf subcommand
+├── core/               ← Types, slots (Mk4), tiers, scorer, schema
 ├── detect/             ← Framework detection, stack scanner
 ├── interop/            ← YAML I/O, CLAUDE.md, AGENTS.md, GEMINI.md
 ├── ui/                 ← Colors (#00D4D4), display
@@ -400,12 +229,12 @@ src/
 > **Robust. Reliable. Next-level WJTTC tested.** — The Foundation Edition.
 
 ```bash
-bun test                       # 880 tests, 75 files, ~18s
+bun test                       # extensive WJTTC + e2e suite
 ```
 
-- **WJTTC Build Resilience** (13) — every regression class locked.
-- **WJTTC Kernel Stress** (19) — WASM kernel boundary tests.
-- **e2e lifecycle** — every command in sequence.
+- **WJTTC Build Resilience** — regression classes locked.
+- **WJTTC Kernel Stress** — WASM kernel boundary tests.
+- **e2e lifecycle** — commands in sequence.
 
 Test reports in `reports/`.
 
@@ -416,13 +245,10 @@ Test reports in `reports/`.
 - **[GitHub Discussions](https://github.com/Wolfe-Jam/faf-cli/discussions)** — Questions, ideas, community
 - **Email:** team@faf.one
 
----
-
 If `faf-cli` has been useful, consider starring the repo — it helps others find it.
 
 ---
 
-
 ## Citation
 
 If you use `faf-cli` or the `.faf` / `.fafm` formats in research or production, please cite the format papers:
@@ -461,7 +287,7 @@ MIT — Free and open source
 
 **IANA-registered:** [`application/vnd.faf+yaml`](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) (Context Layer) · [`application/vnd.fafm+yaml`](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml) (Memory Layer)
 
-*format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev)*
+*format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev) · [faf.one/cli](https://faf.one/cli)*
 
 <div align="center">