faf-mcp 2.3.1 → 3.0.1

package/CHANGELOG.md

@@ -1,5 +1,5 @@
-<!-- faf: faf-mcp | TypeScript | mcp-server | FAF MCP IDE Edition — persistent project context for Cursor, Windsurf, Cline, VS Code -->
-<!-- faf: doc=changelog | latest=v2.3.1 | canonical=project.faf | family=FAF -->
+<!-- faf: faf-mcp | TypeScript | mcp | The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for Cursor, VS Code, and every MCP-compatible IDE. IANA-registered application/vnd.faf+yaml. Start with "Use FAF". -->
+<!-- faf: doc=changelog | latest=v3.0.1 | canonical=project.faf | family=FAF -->
 
 # Changelog
 
@@ -8,7 +8,52 @@ All notable changes to faf-mcp will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [3.0.1] - 2026-09-10 — The Compose Edition
+
+**Names that match the code: `faf_bi_sync` is now `faf_claude`, `faf_init` writes what `faf init` writes, and the listings lead with .FAF Context.**
+
+### Changed
+- **`faf_bi_sync` is now `faf_claude`.** The tool only ever wrote CLAUDE.md from `project.faf`, one direction; nothing read CLAUDE.md back. The old name, its "Bi-sync now active!" message and its header claimed a two-way sync it never did. `faf_claude` sits beside `faf_agents`, `faf_cursor` and `faf_gemini`, keeps the `agents` / `cursor` / `gemini` / `all` flags, and stays in the Core tier. Tool count unchanged: 29, 15 by default.
+- `faf_bi_sync` still answers as an unlisted alias, so existing prompts and configs keep working. Its removal will be announced here first.
+- `faf_agents`, `faf_cursor` and `faf_gemini` no longer call their `sync` action "bidirectional": it re-writes the file from `project.faf` (export with force). `import` reads the file; `merge: true` writes it into `project.faf`.
+- README "Eternal Sync" tells the direction truthfully: CLAUDE.md is written from `project.faf`; the other three formats can also import.
+
+### Fixed
+- **`faf_init` writes what `faf init` writes.** It runs faf-cli's own init steps on the folder, so the file is valid and scored from what the folder holds, and it reports that starting score. Before, it wrote a legacy template that scored 0% on any folder, failed `faf_trust` and crashed `faf_go`. The new project also becomes the current one, so the next steps it suggests act on it. Path handling is unchanged.
+- **The docs page no longer strikes through its own keyword.** The hero line rendered "Context" in red strikethrough, a style left over from an older slogan.
+- README: the all-formats example is the MCP call that works (`faf bi-sync --all` is rejected by faf-cli 7.12); 25 test suites, not 9; the Trophy badge and tier table use ✪.
+- The server status banner reports 29 tools, 15 by default, and reads the version from the package instead of a hardcoded "33+".
+- Tool output: headers say FAF, not "Claude FAF"; the readiness target is 100%, not 99%; tier lines use ✪ ★ ◆ ◇ ●; tools say they author and rewrite files.
+- `faf_git` writes `faf_version: "3.0"` and the package version into the files it authors (it wrote 2.5.0 and 4.5.0), with the spec URL at faf.one.
+- Listings lead with the product name: the npm, MCP Registry, Glama and Smithery descriptions say **.FAF Context**, and `project.faf` marks PulseMCP and Glama live.
+- The registry receipt in `server.json` is refreshed, and the `.faf-dna` birth certificate is re-grounded at 100% with its 2025 birth record kept.
+- Docs: the two essays keep their dated figures with broken links, paths and the missing image fixed; the style source mirrors the live page.
+- Source comments that labelled faf-cli 7.12 code as v4.5.0, faf-cli 7.11.0 or Node 18 now say what the code does; ported parsers keep their provenance line.
+
+## [3.0.0] - 2026-09-09 — The Compose Edition
+
+**Compose, don't port: faf-mcp 3.0 runs on faf-cli 7.12 in-process — one scorer, one set of renderers, one injector — and every number, file and claim this package makes is true. Local stdio, 29 tools, Node 22+.**
+
+### Fixed
+- **One score function.** `faf_auto`, `faf_dna`, `faf_doctor`, `faf_go` and `faf_bi_sync` all report faf-cli's `scoreFafYaml` on the bytes on disk. The local `calculateSimpleScore` heuristic (29 points off `faf_score` on the same file), `faf_go`'s 8-field ratio, `faf_bi_sync`'s "FAF Score: 0%" and `faf_dna`'s frozen birth score are gone.
+- **No more shelling out.** `faf_trust`, `faf_clear` and both resources no longer fall through to whatever `faf` is on PATH. The startup `which faf` detector, the exec fallback and the "install faf-cli FIRST" banner are removed; nothing under `src/` imports `child_process`. A machine with an unrelated `faf` binary on PATH is no longer a problem.
+- **Managed-block injector** matches markers as whole lines at column 0 (fenced examples skipped, an unbalanced fence inside the block cannot hide the end marker, CRLF and BOM preserved). A file written by faf-cli 7.11.0 no longer stacks on re-export; a block that lost its end marker is prefixed, never overwritten.
+- **Tool contracts match their handlers.** `faf_sync` says what it does (reconcile `project.faf` with package.json/git, dry-run, `apply:true` writes); `faf_bi_sync` drops the never-read `auto`/`watch`/`force` flags and states its direction; `faf_clear` offers only the store that exists; `faf_debug` reports the bundled faf-cli version; `faf_auto` drops an unread `force`; seven references to the retired `faf_enhance` are gone. Failed bundled commands now carry their reason instead of "❌ undefined".
+- **Docs tell the truth.** The "Hosted MCP endpoint" claim, the "Deploy to Vercel" door, the MCPaaS landing copy, the `faf_cloud_*` tool table, "Streamable HTTP" and "Cloudflare edge" in `project.faf`/`CLAUDE.md` are removed. faf-mcp runs locally over stdio; that is what every surface now says.
+- `tests/wjttc-v200` no longer writes AGENTS.md / .cursorrules / GEMINI.md into the repo root on every run.
+
+### Changed
+- **Composes faf-cli 7.12.0 (The Open Renderers Edition).** AGENTS.md, GEMINI.md, .cursorrules and CLAUDE.md are written by faf-cli's own renderers, repo enrichment and injector — the same bytes `faf export` and `faf sync` write. `faf_auto` runs faf-cli's `updateExistingFaf` on an existing file and `writeFaf` for the bytes (no runtime `_meta` block; docker-compose facts flow instead of arriving as `slotignored`). The hand-ported renderers, the pre-v3 CLAUDE.md template and faf-mcp's own injector are deleted.
+- Resource URIs are `faf://context` and `faf://status`; `claude-faf://` stays readable as an alias for this release.
+- `faf-cli` dependency `^6.10.1` → `^7.12.0`; `@modelcontextprotocol/sdk` `^1.27.1` → `^1.30.0` (its own range now admits `@hono/node-server` 2.x, so the forced-major override for it is gone); hono override floor `>=4.13.5`.
+- **Node 22 or newer.** The floor was 18, which reached end of life in April 2025 (20 followed in April 2026), and six production dependencies already required 20+. `engines.node` is now `>=22.0.0`, the CI smoke matrix runs 22 and 24, and `scripts/check-engines.mjs` refuses a floor that CI does not exercise.
+
+### Removed
+- 44 unreachable source modules (~15,900 lines): the Mk3 bundled engine (13 vendored commands, `championship-tools.ts`, `cloud-handler.ts`, the shadow tool-visibility registry, the bundled compiler, `faf-dna.ts` and helpers). Tarball 256 → 126 files. `prebuild` now clears `dist/` — tsc never did, so deleted modules had kept shipping.
+- `scripts/postinstall.js` (told users to global-install a dependency this package bundles), `start-http.js` (retired transport), the stale `skill/SKILL.md`.
+
+### Added
+- Regression suites: score parity with a hand-authored seed that kills the pre-merge mutant, tool-schema truth (every declared property is read by its handler; every `faf_*` name in output exists), score truth, engine-adapter (no `child_process`, unknown command is an error), line-anchored injector, compose-faf-cli (byte-identical to faf-cli's writers), no-false-hosted-claim over every shipped surface.
 
 ## [2.3.1] - 2026-06-30
 
@@ -58,7 +103,7 @@ faf-mcp now **enhances** your context files instead of replacing them — a stru
 
 ### Changed
 
-- **Non-destructive interop.** `faf_cursor`, `faf_agents`, `faf_gemini`, and `faf_sync` now inject a structured `.faf` block at the top of .cursorrules, AGENTS.md, GEMINI.md, and CLAUDE.md and preserve everything you've written below. Re-runs update the block in place (idempotent); existing faf-generated files upgrade cleanly in one pass.
+- **Non-destructive interop.** `faf_cursor`, `faf_agents`, `faf_gemini`, and `faf_sync` now inject a structured `.faf` block at the top of .cursorrules, AGENTS.md, GEMINI.md, and CLAUDE.md and preserve everything you've written below. Re-runs update the block in place (idempotent); existing faf-authored files upgrade cleanly in one pass.
 - **Composes faf-cli's single-source engines.** Turbo-Cat (~200-format detection) and the 6Ws interview now come from faf-cli — faf-mcp's own forks are deleted. One source of truth, no drift between the CLI and the server.
 - **Migrated to the `one.faf` namespace.** MCP Registry identity `io.github.Wolfe-Jam/faf-mcp` → `one.faf/faf-mcp` (DNS-verified), carrying the single-source `one.faf/context` `_meta` block emitted by faf-cli. The npm package `faf-mcp`, its tools, and its downloads are **unchanged** — only the registry identity moves.
 

package/CLAUDE.md

@@ -12,9 +12,9 @@ The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for
 
 - **Language:** TypeScript
 - **Backend:** MCP SDK (TS)
-- **API:** MCP (stdio + Streamable HTTP)
-- **Runtime:** Node.js >=18
-- **Hosting:** npm + Cloudflare edge
+- **API:** MCP (stdio)
+- **Runtime:** Node.js >=22
+- **Hosting:** npm
 - **Build:** TypeScript (tsc)
 - **CI/CD:** GitHub Actions
 - **Package Manager:** npm
@@ -24,11 +24,15 @@ The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for
 - **Who:** Developers using Claude, Cursor, Windsurf, VS Code, Cline, and any MCP-compatible IDE
 - **What:** The Cursor / IDE Edition — persistent context for Cursor, VS Code, and every MCP-compatible IDE — 29 MCP tools (15 essential shown by default), interop with AGENTS.md, .cursorrules, GEMINI.md
 - **Why:** Eliminate the 20-minute AI context tax — give AI instant project understanding in 30 seconds
-- **Where:** npm · MCP Registry · Cloudflare edge (ide.faf.one/mcp/v1) · any MCP-compatible IDE — people get it how they wish
-- **When:** Production/Stable — v2.3.0 The Curated Edition, WJTTC certified
+- **Where:** npm · MCP Registry · any MCP-compatible IDE — people get it how they wish
+- **When:** Production/Stable — v3.0.1 The Compose Edition, WJTTC certified
 - **How:** npx faf-mcp or npm install -g faf-mcp, then add to your MCP config
 
 ---
 
-*STATUS: BI-SYNC ACTIVE — 2026-07-01T01:00:16.899Z*
+*STATUS: BI-SYNC ACTIVE — 2026-09-10T19:01:58.786Z*
 <!-- faf:end -->
+
+## Working here
+
+Build, test, layout and the load-bearing conventions live in AGENTS.md under "Working in this repo". Refresh the managed block above with `faf sync` (CLI) or the `faf_claude` tool (MCP); both keep this section.

package/README.md

@@ -1,4 +1,4 @@
-<!-- faf: faf-mcp | TypeScript | mcp-server | FAF MCP IDE Edition — persistent project context for Cursor, Windsurf, Cline, VS Code -->
+<!-- faf: faf-mcp | TypeScript | mcp | The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for Cursor, VS Code, and every MCP-compatible IDE. IANA-registered application/vnd.faf+yaml. Start with "Use FAF". -->
 <!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->
 
 <div style="display: flex; align-items: center; gap: 12px;">
@@ -10,13 +10,16 @@
 </div>
 
 [![npm](https://img.shields.io/npm/v/faf-mcp?color=008B8B)](https://www.npmjs.com/package/faf-mcp)[![downloads](https://img.shields.io/npm/dm/faf-mcp?color=008B8B&label=downloads)](https://www.npmjs.com/package/faf-mcp)
-[![FAF Trophy 100%](https://img.shields.io/badge/FAF-%F0%9F%8F%86%20100%25-000000?labelColor=FF6B35)](https://faf.one)
+[![FAF Trophy 100%](https://img.shields.io/badge/FAF-%E2%9C%AA%20100%25-000000?labelColor=FF6B35)](https://faf.one)
 [![IANA: vnd.faf+yaml](https://img.shields.io/badge/IANA-vnd.faf%2Byaml-008B8B)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
 [![DOI: Context paper](https://img.shields.io/badge/DOI-Context%20paper-FF6B35)](https://doi.org/10.5281/zenodo.18251362)
+[![DOI: Agents paper](https://img.shields.io/badge/DOI-Agents%20paper-FF6B35)](https://doi.org/10.5281/zenodo.21951641)
 
-**Home:** [wolfe-jam.github.io/faf-mcp](https://wolfe-jam.github.io/faf-mcp/) · **Hosted MCP endpoint:** `https://ide.faf.one/mcp/v1` (Streamable HTTP)
+**Home:** [wolfe-jam.github.io/faf-mcp](https://wolfe-jam.github.io/faf-mcp/)
 
-The MCP you didn't realise you needed, or wanted but didn't know who to ask, is here. Building on [100,000+](https://faf.one/blog/hundred-thousand) downloads across the FAF ecosystem, we bring you faf-mcp to cure your syncing pain and fuel your chosen AI with optimized context, on-demand.
+**.FAF Context** is the MCP server for the IDE side of FAF. One `project.faf` in your repo, and every AI tool's context file is authored from it — AGENTS.md, .cursorrules, GEMINI.md, CLAUDE.md — and scored, so you know exactly where to focus. It runs locally over stdio on the same faf-cli the terminal uses. The FAF ecosystem it belongs to has comfortably passed 100k downloads across npm and PyPI ([live count](https://faf.one/downloads)).
+
+⭐ Bookmarks it for you, helps other devs find it too.
 
 [![CI](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -24,9 +27,26 @@ The MCP you didn't realise you needed, or wanted but didn't know who to ask, is
 
 ---
 
-## What's New in 2.3.0 — The Curated Edition
+## What's New in 3.0.1 — The Compose Edition
+
+**Names that match the code: `faf_bi_sync` is now `faf_claude`, `faf_init` writes what `faf init` writes, and the listings lead with .FAF Context.**
+
+- **`faf_bi_sync` is now `faf_claude`.** It writes CLAUDE.md from `project.faf`, one direction, which is all it ever did. The old name still answers, so existing configs keep working.
+- **`faf_init` writes what `faf init` writes.** It runs faf-cli's own init on the folder: a valid file, scored from what is there, and the new project becomes the current one.
+- **The interop tools say what `sync` does.** `faf_agents`, `faf_cursor` and `faf_gemini` re-write their file from `project.faf`; `import` with `merge: true` brings a file back in.
+- **Surfaces corrected.** The docs page hero, the npm, MCP Registry, Glama and Smithery descriptions, the registry receipt, the birth certificate and dozens of tool strings now match 3.0.
+
+## The Compose Edition (3.0)
+
+**Compose, don't port: faf-mcp 3.0 runs on faf-cli 7.12 in-process — one scorer, one set of renderers, one injector — and every number, file and claim this package makes is true. Local stdio, 29 tools, Node 22+.**
 
-**The tools you actually need, up front.** faf-mcp now leads with **15 essential tools** by default — a clean, focused surface instead of a wall of options. Need everything? Set `FAF_TOOLS=all` for the full **29** (every tool stays callable by name either way). And every Core tool's description was rewritten so your AI picks the right one, first time.
+- **Composes faf-cli 7.12.** AGENTS.md, GEMINI.md, .cursorrules and CLAUDE.md are written by faf-cli's own renderers, repo enrichment and block injector — the same bytes `faf export` and `faf sync` write. `faf_auto` runs faf-cli's own update chain. The hand-ported renderers, the pre-v3 CLAUDE.md template and the local injector are gone.
+- **One score function.** `faf_auto`, `faf_go`, `faf_dna`, `faf_doctor` and `faf_claude` all report faf-cli's scorer on the bytes on disk — no local heuristics, no frozen birth score, no "0%".
+- **Nothing shells out.** The `which faf` detector, the exec fallback and the "install faf-cli first" banner are gone; nothing under `src/` imports `child_process`. A machine with an unrelated `faf` on PATH is no longer a problem.
+- **Every tool contract matches its handler.** Descriptions say what the tools do, schemas declare only flags that are read, failures carry their reason.
+- **The Mk3 engine is deleted.** 44 unreachable modules, ~15,900 lines; the tarball halves. `prebuild` clears `dist/` so nothing deleted ever ships again.
+- **Resource URIs** are `faf://context` and `faf://status`; `claude-faf://` remains readable as an alias for this release.
+- **Node 22 or newer.** 18 and 20 are end of life; the CI matrix runs 22 and 24 and a guard keeps the floor honest.
 
 ---
 
@@ -36,6 +56,8 @@ You maintain `.cursorrules`. Your teammate uses `AGENTS.md`. Someone on the team
 
 **faf-mcp is the dedicated MCP server for Cursor, Windsurf, Cline, VS Code, and every non-Claude platform.** One `.faf` file in your repo, synced to every format your team needs.
 
+**Context for Cursor & IDE agents:** faf-cli (v7.12) authors the files this server syncs — `bunx faf export --agents`, zero-install and git-native. See [FAF-CLI for Cursor & IDE agents 👀](https://github.com/Wolfe-Jam/faf-cli/blob/main/docs/faf-cli-for-agents.md).
+
 ```
                       project.faf
                            │
@@ -47,6 +69,10 @@ You maintain `.cursorrules`. Your teammate uses `AGENTS.md`. Someone on the team
 
 ### Quick Start
 
+**Cursor — one click:** [![Add .FAF Context to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=faf-mcp&config=eyJjb21tYW5kIjoiYnVueCIsImFyZ3MiOlsiZmFmLW1jcCJdfQ==)
+
+**Everywhere else:**
+
 ```bash
 bunx faf-mcp
 ```
@@ -67,30 +93,14 @@ Add to your MCP config:
 
 ---
 
-## Three Ways to Deploy
-
-| Door | Method | Best For |
-|------|--------|----------|
-| **Hosted** | [mcpaas.live](https://mcpaas.live) | Zero-install, point any MCP client to the URL |
-| **Self-Deploy** | [Deploy to Vercel](https://vercel.com/new?repository-url=https://github.com/Wolfe-Jam/faf-mcp) | Your own instance, full control |
-| **Local** | `bunx faf-mcp` | IDE integration via stdio transport |
-
-### Hosted (mcpaas.live)
+## Run It
 
-Point your MCP client to `https://ide.faf.one/mcp/v1` — no install, no config, no maintenance. Served from 300+ Cloudflare edges with sub-ms cold starts via 2.7KB Zig-WASM engine.
+faf-mcp runs locally over stdio. Point your IDE at one of these commands.
 
-### Self-Deploy (Vercel)
-
-Deploy your own MCP server on Vercel in one click. Once deployed, your server exposes:
-- `/health` — Health check
-- `/info` — Server metadata + tool list
-- `/mcp/v1` — MCP Streamable HTTP transport
-
-### Local (npm)
-
-```bash
-npx faf-mcp
-```
+| Method | Command |
+|--------|---------|
+| **npm** | `npx faf-mcp` |
+| **Bun** | `bunx faf-mcp` |
 
 ---
 
@@ -102,62 +112,36 @@ npx faf-mcp
 | `faf_cursor` | Cursor IDE | Import/export/sync .cursorrules |
 | `faf_gemini` | Google Gemini | Import/export/sync GEMINI.md |
 | `faf_conductor` | Conductor | Import/export directory structure |
-| `faf_git` | GitHub | Generate .faf from any repo URL |
+| `faf_git` | GitHub | Author .faf from any repo URL |
 
-```bash
-# Sync to all formats at once
-faf bi-sync --all
+```text
+# MCP tool calls — ask your IDE's AI
+# Write all four formats from project.faf
+faf_claude { all: true }
 
-# Generate .faf from any GitHub repo
+# Author .faf from any GitHub repo
 faf_git { url: "https://github.com/facebook/react" }
 ```
 
-**Core tier:** 15 essential tools shown by default; set `FAF_TOOLS=all` for the full **29** (every tool stays callable by name either way) · with CLI fallback · **9 test suites** · **7 bundled parsers**
+**Core tier:** 15 essential tools shown by default; set `FAF_TOOLS=all` for the full **29** (every tool stays callable by name either way) · **25 test suites** · **7 bundled parsers**
 
 ---
 
-## Cloud Sync
-
-Share your FAF context globally via [mcpaas.live](https://mcpaas.live):
+## Eternal Sync
 
-| Tool | Purpose |
-|------|---------|
-| `faf_cloud_publish` | Upload to cloud, get shareable URL |
-| `faf_cloud_fetch` | Pull context from cloud |
-| `faf_cloud_list` | List available souls |
-| `faf_cloud_search` | Search across souls |
-| `faf_cloud_share` | Generate share links |
-
-**Example Workflow:**
-```bash
-# Upload your project.faf
-faf_cloud_publish { soul_name: "my-project" }
-→ https://mcpaas.live/souls/my-project
-
-# Anyone can fetch it
-faf_cloud_fetch { soul_name: "my-project" }
-→ Context merged into local project.faf
-```
-
-**Zero-install sharing** - Recipients need no MCP setup. Served from 300+ Cloudflare edges with <1ms cold starts via 2.7KB Zig-WASM engine.
-
----
-
-## Eternal Bi-Sync
-
-Your `.faf` file and your platform context files stay synchronized in milliseconds.
+`project.faf` is the source. faf-mcp writes every tool's context file from it in milliseconds.
 
 ```
-project.faf  ←── 8ms ──→  .cursorrules / AGENTS.md / CLAUDE.md / GEMINI.md
+project.faf  ──── 8ms ───→  CLAUDE.md / AGENTS.md / .cursorrules / GEMINI.md
                     Single source of truth
 ```
 
-- Update either side → both stay aligned
-- `--all` flag syncs to all four formats at once
-- Zero manual maintenance
+- `faf_claude { all: true }` writes all four formats at once
+- `faf_agents`, `faf_cursor` and `faf_gemini` can also import an existing file: `merge: true` merges it into `project.faf`
+- Content outside the faf-managed block is preserved, byte for byte
 - Works across teams, branches, sessions
 
-AI assistants forget. They drift. Every new session, AI starts guessing again. Bi-sync means **context never goes stale**.
+AI assistants forget. They drift. Every new session, AI starts guessing again. One source means **context never goes stale**.
 
 ---
 
@@ -165,7 +149,7 @@ AI assistants forget. They drift. Every new session, AI starts guessing again. B
 
 | Tier | Score | Status |
 |------|-------|--------|
-| 🏆 **TROPHY** | 100% | AI never has to guess |
+| ✪ **TROPHY** | 100% | AI never has to guess |
 | ★ **GOLD** | 99%+ | 1 slot from Trophy |
 | ◆ **SILVER** | 95%+ | Close — keep going |
 | ◇ **BRONZE** | 85%+ | Interim — keep going |
@@ -199,8 +183,8 @@ Works on all platforms — stops web search, forces tool usage.
 |------|---------|
 | `faf_init` | Initialize project.faf |
 | `faf_score` | Check AI-readiness (0-100%) |
-| `faf_sync` | Sync context across platforms |
-| `faf_bi_sync` | Bi-directional .faf ↔ CLAUDE.md |
+| `faf_sync` | Reconcile project.faf with package.json / git (dry-run; `apply:true` writes) |
+| `faf_claude` | Write CLAUDE.md (+ AGENTS.md, .cursorrules, GEMINI.md) from project.faf |
 | `faf_read` | Parse and validate FAF files |
 | `faf_write` | Create/update FAF with validation |
 | **Interop Tools** | |
@@ -208,39 +192,64 @@ Works on all platforms — stops web search, forces tool usage.
 | `faf_cursor` | Import/export/sync .cursorrules |
 | `faf_gemini` | Import/export/sync GEMINI.md |
 | `faf_conductor` | Import/export directory structure |
-| `faf_git` | Generate .faf from GitHub repo URL |
-| **Cloud Tools** | |
-| `faf_cloud_publish` | Upload to mcpaas.live |
-| `faf_cloud_fetch` | Pull from cloud |
-| `faf_cloud_list` | List souls |
-| `faf_cloud_search` | Search souls |
-| `faf_cloud_share` | Generate share links |
-
-**Plus CLI fallback** (via faf-cli):
-- `faf readme` - Extract 6 Ws from README (+25-35% boost)
-- `faf human-add` - Non-interactive YAML merge (6Ws Builder)
-- `faf git` - GitHub repo analysis without cloning
-- And 40+ more commands...
+| `faf_git` | Author .faf from GitHub repo URL |
+
+**Built on faf-cli.** Every tool composes the bundled [faf-cli](https://www.npmjs.com/package/faf-cli) in-process — the same scorer, the same renderers, the same block injector the CLI uses. Nothing shells out to a `faf` on your PATH.
 
 ---
 
 ## Ecosystem
 
-- **[claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp)** — Claude Desktop (33 tools)
+- **[claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp)** — Claude Desktop
 - **[faf-cli](https://npmjs.com/package/faf-cli)** — Terminal CLI
 - **[faf-wasm](https://www.npmjs.com/package/faf-wasm)** — WASM SDK (<5ms scoring)
+- **[faf-wasm-gen](https://www.npmjs.com/package/faf-wasm-gen)** — Rust→WASM `project.faf` authoring engine, browser/edge (faf-wasm's authoring sibling)
+- **[faf-trinity](https://github.com/Wolfe-Jam/faf-trinity)** — reference MCP server exposing all three IANA FAF formats (context/memory/agent) together
 - **[faf.one](https://faf.one)** — Official website
+- **[docs/SKILLS-OVER-MCP.md](./docs/SKILLS-OVER-MCP.md)** — J1 Agent Skill `faf-ide` (stdio · skills/list · digests)
 
 ---
 
 If `faf-mcp` has been useful, consider starring the repo — it helps others find it.
 
+## Citation
+
+If you use `faf-mcp` or the `.faf` / `.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). *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{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 License — Free and open source
 
 ---
 
-**Zero drift. Eternal sync. AI optimized.** 🏆
+**Zero drift. Eternal sync. AI optimized.** ✪
 
 *"It's so logical if it didn't exist, AI would have built it itself" — Claude*

package/dist/src/faf-core/commands/agents.d.ts

@@ -1,8 +1,8 @@
 /**
- * Agents Command - v4.5.0 Interop Edition
+ * Agents Command — Interop (faf-mcp 2.0.0; ported from faf-cli 4.5.0 via claude-faf-mcp 4.5.0)
  *
  * Import/Export/Sync between AGENTS.md and project.faf
- * Bundled command — no CLI dependency required.
+ * Bundled command — no shell-out; export composes faf-cli in-process.
  */
 export interface AgentsCommandResult {
     success: boolean;

package/dist/src/faf-core/commands/agents.js

@@ -1,9 +1,9 @@
 "use strict";
 /**
- * Agents Command - v4.5.0 Interop Edition
+ * Agents Command — Interop (faf-mcp 2.0.0; ported from faf-cli 4.5.0 via claude-faf-mcp 4.5.0)
  *
  * Import/Export/Sync between AGENTS.md and project.faf
- * Bundled command — no CLI dependency required.
+ * Bundled command — no shell-out; export composes faf-cli in-process.
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };

package/dist/src/faf-core/commands/claude.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Claude Command — writes CLAUDE.md from project.faf, one direction.
+ *
+ * CLAUDE.md is faf-cli's render of project.faf (the same bytes `faf sync`
+ * pushes), injected with faf-cli's injector, so content outside the managed
+ * block survives. With agents / cursor / gemini / all it also writes
+ * AGENTS.md, .cursorrules and GEMINI.md. Nothing here reads CLAUDE.md back
+ * into project.faf. Backs the `faf_claude` tool, named `faf_bi_sync` before
+ * 3.0.1; the old name claimed a two-way sync this code never did.
+ */
+export interface ClaudeExportOptions {
+    json?: boolean;
+    agents?: boolean;
+    cursor?: boolean;
+    gemini?: boolean;
+    all?: boolean;
+}
+export interface ClaudeExportResult {
+    success: boolean;
+    direction: 'faf-to-claude' | 'none';
+    filesChanged: string[];
+    conflicts: string[];
+    duration: number;
+    message: string;
+}
+/**
+
+/**
+ * Write CLAUDE.md (and any requested IDE formats) from project.faf.
+ */
+export declare function claudeExportCommand(projectPath?: string, _options?: ClaudeExportOptions): Promise<ClaudeExportResult>;

package/dist/src/faf-core/commands/{bi-sync.js → claude.js}

@@ -1,8 +1,13 @@
 "use strict";
 /**
- * 🔗 Bi-Sync Engine - Mk3 Bundled Edition
- * Revolutionary project.faf ↔ CLAUDE.md Synchronization
- * v4.5.0: Added agents/cursor/gemini/all flags for multi-format sync
+ * Claude Command — writes CLAUDE.md from project.faf, one direction.
+ *
+ * CLAUDE.md is faf-cli's render of project.faf (the same bytes `faf sync`
+ * pushes), injected with faf-cli's injector, so content outside the managed
+ * block survives. With agents / cursor / gemini / all it also writes
+ * AGENTS.md, .cursorrules and GEMINI.md. Nothing here reads CLAUDE.md back
+ * into project.faf. Backs the `faf_claude` tool, named `faf_bi_sync` before
+ * 3.0.1; the old name claimed a two-way sync this code never did.
  */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
@@ -38,75 +43,21 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fafToClaudeMd = fafToClaudeMd;
-exports.syncBiDirectional = syncBiDirectional;
+exports.claudeExportCommand = claudeExportCommand;
 const yaml_1 = require("../fix-once/yaml");
 const path = __importStar(require("path"));
 const fs_1 = require("fs");
 const file_utils_1 = require("../utils/file-utils");
 const agents_js_1 = require("./agents.js");
-const inject_1 = require("../inject");
 const cursor_js_1 = require("./cursor.js");
 const gemini_js_1 = require("./gemini.js");
+const faf_cli_bridge_js_1 = require("../../utils/faf-cli-bridge.js");
 /**
- * 🔄 Convert project.faf YAML content to CLAUDE.md Markdown format
- */
-function fafToClaudeMd(fafContent) {
-    try {
-        const fafData = (0, yaml_1.parse)(fafContent);
-        let claudeMd = `# 🏎️ CLAUDE.md - ${fafData.project?.name || 'Project'} Persistent Context & Intelligence\n\n`;
-        // Project State
-        if (fafData.project) {
-            claudeMd += `## PROJECT STATE: ${fafData.context_quality?.overall_assessment || 'ACTIVE'} 🚀\n`;
-            if (fafData.project.goal) {
-                claudeMd += `**Current Position:** ${fafData.project.goal}\n`;
-            }
-            claudeMd += `**Tyre Compound:** ULTRASOFT C5 (Maximum Performance)\n\n`;
-            claudeMd += `---\n\n`;
-        }
-        // Core Context
-        claudeMd += `## 🎨 CORE CONTEXT\n\n`;
-        if (fafData.project) {
-            claudeMd += `### Project Identity\n`;
-            claudeMd += `- **Name:** ${fafData.project.name || 'Unknown'}\n`;
-            if (fafData.instant_context?.tech_stack) {
-                claudeMd += `- **Stack:** ${fafData.instant_context.tech_stack}\n`;
-            }
-            claudeMd += `- **Quality:** F1-INSPIRED (Championship Performance)\n\n`;
-        }
-        // Technical Context
-        if (fafData.instant_context) {
-            claudeMd += `### Technical Architecture\n`;
-            if (fafData.instant_context.what_building) {
-                claudeMd += `- **What Building:** ${fafData.instant_context.what_building}\n`;
-            }
-            if (fafData.instant_context.main_language) {
-                claudeMd += `- **Main Language:** ${fafData.instant_context.main_language}\n`;
-            }
-            claudeMd += `\n`;
-        }
-        // Context Quality
-        if (fafData.context_quality) {
-            claudeMd += `### 📊 Context Quality Status\n`;
-            claudeMd += `- **Overall Assessment:** ${fafData.context_quality.overall_assessment || 'Good'}\n`;
-            claudeMd += `- **Last Updated:** ${new Date().toISOString().split('T')[0]}\n\n`;
-        }
-        // Championship Footer
-        claudeMd += `---\n\n`;
-        claudeMd += `**STATUS: BI-SYNC ACTIVE 🔗 - Synchronized with .faf context!**\n\n`;
-        claudeMd += `*Last Sync: ${new Date().toISOString()}*\n`;
-        claudeMd += `*Sync Engine: F1-Inspired Software Engineering*\n`;
-        claudeMd += `*🏎️⚡️_championship_sync*\n`;
-        return claudeMd;
-    }
-    catch (error) {
-        throw new Error(`Failed to convert .faf to CLAUDE.md: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
+
 /**
- * 🔗 Main Bi-Sync function
+ * Write CLAUDE.md (and any requested IDE formats) from project.faf.
  */
-async function syncBiDirectional(projectPath, _options = {}) {
+async function claudeExportCommand(projectPath, _options = {}) {
     const startTime = Date.now();
     const result = {
         success: false,
@@ -130,27 +81,38 @@ async function syncBiDirectional(projectPath, _options = {}) {
         const claudeMdExists = await (0, file_utils_1.fileExists)(claudeMdPath);
         // Read .faf content
         const fafContent = await fs_1.promises.readFile(fafPath, 'utf-8');
-        const fafData = (0, yaml_1.parse)(fafContent);
-        const currentScore = fafData.faf_score || '0%';
+        (0, yaml_1.parse)(fafContent); // still validates the YAML before anything is written
+        // The score in the message is the real one — faf-cli's scorer on the
+        // bytes read — not a `faf_score` key nothing ever writes.
+        const { scoreFafYaml, readFaf, renderClaudeMd, writeClaudeMd } = await faf_cli_bridge_js_1.fafCli;
+        let currentScore = 'unknown';
+        try {
+            currentScore = `${scoreFafYaml(fafContent).score}%`;
+        }
+        catch {
+            /* scorer unavailable — say so rather than invent a number */
+        }
         if (!claudeMdExists) {
-            // Create CLAUDE.md from project.faf
-            const claudeMdContent = fafToClaudeMd(fafContent);
-            await (0, inject_1.injectFafBlock)(claudeMdPath, claudeMdContent);
+            // CLAUDE.md is faf-cli's render of project.faf — the same bytes
+            // `faf sync` writes — injected with faf-cli's injector. The pre-v3
+            // template that lived here dropped Stack and every human_context slot.
+            writeClaudeMd(projectDir, renderClaudeMd(readFaf(fafPath)));
             result.success = true;
             result.direction = 'faf-to-claude';
             result.filesChanged.push('CLAUDE.md');
-            result.message = `CLAUDE.md created! Bi-sync now active! FAF Score: ${currentScore}`;
+            result.message = `CLAUDE.md written from project.faf. FAF Score: ${currentScore}`;
         }
         else {
-            // Both files exist - update CLAUDE.md from project.faf
-            const claudeMdContent = fafToClaudeMd(fafContent);
-            await (0, inject_1.injectFafBlock)(claudeMdPath, claudeMdContent);
+            // CLAUDE.md is faf-cli's render of project.faf — the same bytes
+            // `faf sync` writes — injected with faf-cli's injector. The pre-v3
+            // template that lived here dropped Stack and every human_context slot.
+            writeClaudeMd(projectDir, renderClaudeMd(readFaf(fafPath)));
             result.success = true;
             result.direction = 'faf-to-claude';
             result.filesChanged.push('CLAUDE.md');
-            result.message = `Files synchronized! Perfect harmony achieved! FAF Score: ${currentScore}`;
+            result.message = `CLAUDE.md refreshed from project.faf. FAF Score: ${currentScore}`;
         }
-        // v4.5.0: Chain additional format exports if requested
+        // Chain additional format exports if requested
         const doAgents = _options.agents || _options.all;
         const doCursor = _options.cursor || _options.all;
         const doGemini = _options.gemini || _options.all;
@@ -162,7 +124,7 @@ async function syncBiDirectional(projectPath, _options = {}) {
                 }
             }
             catch {
-                // Non-fatal — CLAUDE.md sync already succeeded
+                // Non-fatal — the CLAUDE.md write already succeeded
             }
         }
         if (doCursor) {
@@ -188,15 +150,15 @@ async function syncBiDirectional(projectPath, _options = {}) {
             }
         }
         if (result.filesChanged.length > 1) {
-            result.message += ` | Also synced: ${result.filesChanged.filter(f => f !== 'CLAUDE.md').join(', ')}`;
+            result.message += ` | Also wrote: ${result.filesChanged.filter(f => f !== 'CLAUDE.md').join(', ')}`;
         }
         result.duration = Date.now() - startTime;
         return result;
     }
     catch (error) {
         result.duration = Date.now() - startTime;
-        result.message = error instanceof Error ? error.message : 'Sync failed';
+        result.message = error instanceof Error ? error.message : 'CLAUDE.md write failed';
         return result;
     }
 }
-//# sourceMappingURL=bi-sync.js.map
+//# sourceMappingURL=claude.js.map