# Changelog All notable changes to claude-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). ## [7.0.1] - 2026-09-30 **faf-cli 8.0.1 inside: pnpm installs work, and fast-uri is out of two moderate advisories.** Patch — inherits The Always33 Edition. 513 tests. ### Fixed - **faf-cli 8.0.1.** faf-cli 8.0.0 pointed at a `vendor/` folder inside its own package, so pnpm installs of claude-faf-mcp (and Glama's pnpm build) stopped with `ERR_PNPM_LINKED_PKG_DIR_NOT_FOUND`. The lockfile and the Claude Desktop `.mcpb` now carry faf-cli 8.0.1, which gets `faf-scoring-kernel` from npm. `package.json` keeps `faf-cli ^8.0.0`. - **fast-uri 4.2.1** (runtime, through `ajv`): out of GHSA-hrr3-gc8f-f4qj and GHSA-jvvf-x445-j334, both moderate. The override is now `>=4.1.5`, the first release outside both. `npm audit` reports 0 vulnerabilities. - `brace-expansion` 1.1.21 and 2.1.7 (dev only, #128) and `ip-address` 10.7.2. ### Tests - #80 reads `npm pack --json` from npm 10 (an array) and npm 12 (an object keyed by name). - The major-release callout check names the major (7.0.0), so a patch keeps it. ## [7.0.0] - 2026-09-26 — The Always33 Edition **One engine, one number: claude-faf-mcp 7 scores with faf-cli 8's always-33 kernel — the same score faf-cli and faf-kernel give.** 513 tests. **7.0.0 is a major release because scores can move.** A `.faf` without the 12 enterprise `slotignored` markers now counts them as empty (21 filled = 64%). Run `faf_auto` — it writes the markers and the score returns (a v7-era faf-python-sdk file: 56% → ✪ 100%). Anything that gates on `faf_score` should re-check its threshold. ### Changed - **The always-33 engine.** claude-faf-mcp composes **faf-cli ^8.0.0** (was ^7.13.1, which could never resolve 8.x). Every tool's score is faf-cli 8's `scoreFafYaml`: all 33 Mk4 slots, one Rust kernel (`faf-scoring-kernel` 3.0.0). Verified live: `faf_score` on faf-python-sdk 56, mcp-context-card 56, faf-cli ✪ 100 — identical to faf-cli 8.0.0 and the reference always-33 scorer. - **The 12 enterprise slots stay in view.** faf-cli fills the 21 base slots and marks the 12 enterprise slots `slotignored` unless your app-type uses them; `faf_score` scores against all 33, and `slotignored` slots drop out of the denominator. - `tbd` and `todo` (any case) count as empty (faf-cli 8). - Compose floor: `faf-cli ^8.0.0`, pinned by `tests/wjttc-600-r2-closed-list.test.ts` (R2-8). ### Tests - The 100% fixtures are written the faf-cli way — 21 slots + the 12 enterprise markers. ## [6.0.0] - 2026-09-13 — The Earned Badge Edition **Every badge earned, none claimed: claude-faf-mcp 6.0 composes faf-cli, touches only what it wrote, and every tool tells the truth — one score, facts from repo, nothing from your PATH.** **6.0.0 is a major release.** It needs Node 22 or later. Four tools and the interop imports are retired (see Removed). The `.mcpb` runs the server bundled inside it. The npx config and the SessionStart hook stay unpinned, so an install that runs `npx -y claude-faf-mcp` moves to 6.x on its next start. ### Security - Every read of project context and every write goes through faf-cli's safe path. A project.faf, CLAUDE.md, AGENTS.md, soul.fafm, .faf-dna, MEMORY.md or .claude/settings.json that is a link out of the project is refused: never read into a reply, never written through (faf_status, faf_dna, faf_sync, faf_auto, faf_etch, faf_tri_sync, faf_setup and the SessionStart hook). - The copilot and conductor exports make their folder inside the project, and a `.github` or `conductor` that links out of it is refused. - faf_debug no longer writes and deletes a probe file to test write access. It asks the OS, so a `.claude-faf-test` of yours, or a link by that name, is left alone. - Correction to the 5.x path-confinement note below: it covered only the `path` argument. A context file that was itself a link out of the project was still followed until this release. - One path resolver for every tool. Your home folder and the filesystem root are refused by faf-cli's device-and-inode check, so no other spelling of home (upper case, a link) gets past it. It covers every writer and the SessionStart hook, and it refuses before the active project moves: a refused call leaves the active project where it was. - faf_go answers take only slot paths faf-cli knows (its interview and its slot table), the caller's own keys, and text. `__proto__`, `constructor` and `prototype` are refused at any depth, so an answer can no longer turn on another tool's `force` or change its path. One bad key refuses the whole call, and nothing is written. - Tool arguments are read as the caller's own keys only: a flag or a path the caller did not send is never read from Object.prototype. - faf_read and faf_list reach only the active project and FAF_ALLOWED_ROOTS: no temp folders, never your home folder or the filesystem root. A relative path resolves against the active project. faf_list is confined like faf_read and lists a link without following it. (The 5.x note below said cwd plus the system temp folders.) - faf_git checks out a repo's links as plain files, so a link in a repo can never make faf read a file outside the clone. - A test clones a real repo whose README.md is a link to a secret file outside it: the secret's text is in no reply and no file. Without `core.symlinks=false` the same test fails. - The registry workflows pin mcp-publisher (v1.8.1) and check its sha256, pin trufflehog to a commit, pass the DNS key through the environment (never a command line), and pass the sibling workflow's inputs through the environment instead of into the script. - The dependency tree passes `npm audit --audit-level=high` again: js-yaml 4.3.2 (through eslint, a dev dependency) and hono 4.13.7 (through @modelcontextprotocol/sdk; the override floor is now >=4.13.5), and tmp >=0.2.6 for @anthropic-ai/mcpb's prompt library. ### Fixed - Every write is atomic. A full disk, a quota or a read-only file leaves the file exactly as it was, and the message says "not written; original kept". - faf_human_add, faf_go answers and faf_readme edit project.faf in place through faf-cli. Comments, key order, exact values (`1.10`, a 20-digit id, `0x1F90`), anchors and your own `_meta` survive, and a change that changes nothing writes nothing. - faf_auto names every value the file held that the fill changed, instead of saying "existing values kept". A typed None or placeholder word is an empty slot and scores 0: in a tech slot the app-type uses, only a repo fact replaces it, and with no fact it stays as typed; in a tech slot the app-type leaves out, faf_auto writes `slotignored`; a 6W keeps your words (faf_go asks). - faf_auto reports each file on its own ("project.faf updated; CLAUDE.md not written: …"), so a CLAUDE.md that cannot be written never hides a project.faf that was. - faf_agents, faf_cursor, faf_gemini and the copilot export no longer refuse an existing file or take `force`. They put faf's block on top (or update it in place) and keep every other byte. - faf_etch and faf_recall use faf-cli's soul. A hand-kept index, comments, the version, facts or sessions in another shape and unknown keys survive an etch; re-etching an id merges into that fact; faf_recall prints bare-string facts; faf_etch creates no folders. The local soul copy is gone. - faf_conductor writes one faf-managed block into each conductor/ file and keeps every line you wrote. `force` is gone. The content comes from project.faf's own keys: goal, language, stack, commands and the 6Ws. - faf_readme apply fills only empty human_context slots, never replaces a value you wrote, lists what it filled, and writes nothing when nothing changed. `force` is gone. - faf_quick builds on faf-cli's detection: no invented TypeScript or "cloud", no timestamp, server-version or `initialized_by` keys, and a framework goes in stack.frontend or stack.backend only when faf-cli knows which (otherwise it says so). It refuses a folder that already has a project.faf or .faf (use faf_auto) and your home folder. `force` is gone. - Advice points at the fix. A YAML error names the file:line:col to edit by hand, a comments-only file is called "no keys", and no message tells you to force or recreate a file you wrote (faf_score, faf_doctor, faf_init, faf_sync and the exports). - faf_init `force: true` replaces project.faf with a fresh one, after copying the old file to `project.faf.bak-`. With faf-cli 7.13 it had started to merge instead. Without force an existing file is left alone. - faf_setup removes only the hook whose command is exactly faf's; a user hook that mentions `claude-faf-mcp --session-refresh` stays. It refuses a `hooks` or `SessionStart` of the wrong shape instead of replacing it, previews a removal unless `confirm: true`, and rewrites settings.json only when it is laid out the way faf writes JSON (otherwise it gives the entry to add by hand). It refuses the home folder, whose .claude/settings.json is your user settings, and every message names the project settings. - faf_tri_sync writes MEMORY.md through faf-cli's Claude-memory writer, at the path Claude Code reads: its id for the project's canonical git root (every character outside a-z, A-Z, 0-9 becomes "-"), under CLAUDE_CONFIG_DIR when set. Only faf's block changes, Claude's notes keep every byte (CRLF and a BOM included), and "kept" is reported only after the file is read back. The local MEMORY.md port is gone. - faf_git no longer writes over an existing project.faf. It refuses before fetching anything and points to faf_auto. - A relative path (".", "..", "./app") resolves against the active project, never against ~/Projects. faf_init refuses a name with no letters or digits. - A path that does not exist is an error ("path not found") in faf_context and every other tool, and the active project stays where it was. faf_etch creates no folders. - Starting the server creates no folder. A host that starts it at "/" gets an existing ~/Projects, or the home folder, and the writers ask for a path. - The older `project: ` (a string, a number or a boolean) is lifted to project.name once, where project.faf is read. faf_go keeps the name, and faf_sync, the SessionStart hook, the exports and faf_tri_sync title everything with it. - faf_init, faf_score, faf_sync and faf_doctor name the older `project: ` shape and point to faf_auto, which moves it to project.name. - The CLAUDE.md that claude-faf-mcp 4.5.0–5.22.1 wrote with no markers ("AI Telemetry Link … STATUS: BI-SYNC ACTIVE") is taken out from below faf's block only when faf can prove it wrote every line of it. A file with any line of yours is left as it is, and the reply says so. - One .faf finder, faf-cli's: project.faf, else .faf, in the folder and then one level up. Every reader uses it and names the file it read, and the exports write next to that file. The writers write /project.faf exactly, and name the .faf above it they did not fill. The two local finders are gone, one of which walked up ten folders. - faf_auto in a folder with only the older .faf writes project.faf from it, keeps every value, fills the empty slots and leaves the .faf as it was. - faf_git composes faf-cli's `faf git`. faf-cli checks the URL, a shallow git clone fetches the repo into a temp folder, and faf-cli authors the .faf and scores it. The score in the reply is faf-cli's, where it used to claim 100% for a file faf-cli scored 14–24%. It writes only a new project.faf, never in your home folder. - faf_dna reads the .faf-dna with faf-cli's FafDNAManager and writes nothing. faf_init and faf_quick write the birth certificate and faf_auto and faf_go add each new score, in faf-cli's own shape, so `faf auto` and `faf dna` keep working on the file. - faf_formats shows the formats faf-cli finds in the project folder, each with its file, and a dry run of what faf_auto would write. The canned recommendations and the "Intelligence Score" are gone. With faf-cli 7.13 a parent folder's package.json or tsconfig.json no longer shows up in a subfolder. - faf_go answers report faf-cli's score of the file just written. - One score everywhere: faf_go, faf_doctor and the SessionStart heartbeat report faf-cli's scoreFafYaml, the number faf_score shows. faf_go no longer says "100% GOLD CODE" when its Table-of-8 is filled: it is complete only at 100%, and below that it says where it stopped and what fills the rest. The local scorer is gone. - faf_go names faf_auto only for the slots faf_auto's own dry run would fill or mark slotignored (the dry run faf_formats shows). When it would write none, faf_go names every slot still empty and takes them as answers (`answers: {"stack.hosting": "…"}`), so faf_go and faf_auto no longer send you back and forth. The faf prompt says the same. - **Every empty slot says what fills it — "fact from repo".** faf_doctor, faf_score (details) and faf_go label each empty slot from faf_auto's own dry run: `fact from repo: ` when the repo holds it, `no fact in repo: answer it (faf_go), or fix project.type if it doesn't apply`, `yours: faf_go asks` for a 6W, or `the app-type leaves it out: faf_auto marks it slotignored`. faf_auto is named once, only when it has a fact to write. The dry run now reads project.faf exactly as faf_auto does, so a type faf fell back to (`# found: no classifying signals — fallback`) never makes faf_go send you back to a faf_auto with nothing to write. - faf_score prints populated/active slots ("17/17" on a Trophy), as faf-cli and faf_init do, never populated/total. - faf_trust runs faf-cli's validateFaf first: a list, a scalar or a file missing faf_version or project.name gets no receipt and an error naming what is missing. - faf_doctor lists faf-cli's validateFaf errors, each with its fix, and faf-cli's score with every empty slot and the tool that fills it (faf_auto or faf_go). It no longer calls such a file ".faf structure is valid", sets a "70%+" target or says "championship-ready". - faf_go's JSON gives `score` and `currentScore` as null when the score is unknown (an About repo with no about.source_score), never -1; `scoreText` still says "unknown (—)". - A score faf-cli cannot know (an About repo with no about.source_score) shows as "unknown (—)" in faf_score, faf_trust, faf_doctor, faf_check, faf_auto, the resources and the heartbeat, never "-1%", and gets no trust receipt. - The faf_trust receipt names the project (project.name, else its folder) as its subject; the server that emitted it is on its own "by" line. - The ✪ mark appears only at 100%. The trophy emoji is stripped like any other emoji instead of becoming ✪, the faf_bench receipt line is plain, and the next-tier hint names the tier without its glyph. - The parity claim is true: faf-parity/v1 is claude-faf-mcp's own spec, which no other engine computes yet, and you check it with sha256(projection) === parityHash. - faf_check reports faf-cli's validateFaf verdict and the scorer's state for every slot, the 6Ws one by one, instead of a "Quality: N%" based on string length. - AGENTS.md, .cursorrules, GEMINI.md and .github/copilot-instructions.md are faf-cli's renders written by faf-cli's writers, the same bytes `faf export` writes (AGENTS.md and GEMINI.md enriched from the repo). No more "slotignored" printed as a value, "Deployed:" for the 6W where, a one-line GEMINI.md or a daily date line. - faf_sync names every requested file it could not write, with the reason, and returns an error instead of leaving it out of "Files written". - Both resources read the active project's .faf with the bundled faf-cli: their score is faf_score's, and reading one never runs a program or writes in your home folder. - faf_debug reports the bundled faf-cli version, not whatever `faf` is on PATH, and no longer tells you to install faf-cli. - Every tool's arguments are checked against its input schema before it runs: a wrong type, a missing required argument, an unknown argument or an action outside the list returns an error and runs nothing. `faf_agents {action: "bogus"}` used to write AGENTS.md. - A tool that fails returns an error result with a readable line, never a JSON-RPC -32603. An unknown tool or prompt is -32602 and an unknown resource -32002. - faf_tri_sync with no project.faf returns an error: nothing was written. - faf_auto and faf_etch carry destructiveHint: true: faf_auto can replace a typed None already in a slot, and an etch on an existing id changes that memory. - Tool annotations match what each handler does: faf_init (force), faf_human_add and faf_go answers are destructive, only tools that never write a file are read-only, every tool has idempotentHint, and every tool has a title. - Tool descriptions say what each handler does and returns: `faf` reads only and returns the steps, faf_about promises no bridges, faf_status says it shows the first 20 lines, faf_go lists the eight things it asks, and "Mk4 engine" is gone. - MCP output gives MCP advice ("faf_score (details: true)"), never `faf score` (CLI). faf_score no longer suggests marking empty slots slotignored. - faf_read returns its metadata in `_meta` instead of a top-level `metadata` key. - The `faf` tool names the project from project.faf (or faf-cli's detection) and its first step runs faf_auto for an existing project.faf too. - faf_bench names the older `project: ` shape, which faf-cli reads no name from. - The .mcpb runs its own bundled code: manifest.json starts `node ${__dirname}/dist/src/index.js` instead of `npx -y claude-faf-mcp`, and pack:mcpb no longer deletes ajv-formats, which the bundled server needs to start. - pack:mcpb is one chain joined with `&&`: a missing file or a failed step stops the pack instead of being swallowed by `2>/dev/null;`. - `npm run verify:mcpb` packs the bundle, unpacks it with mcpb's own unpacker, starts the server inside it the way a host does, and checks initialize, tools/list and faf_score. `--record` then writes the bundle's sha256 into server.json; nothing else writes it. - scripts/gen-server-card.js refuses to write server.json for a new version without the new bundle's sha, so a release can no longer publish the old bundle's sha on the new URL. - The registry workflow downloads the release .mcpb, checks its sha256 against server.json, checks the version inside it, and starts it, before anything is published; after publishing it reads the entry back. - server.json's title comes from faf-cli's registryTitle, and its icons from this repo's own assets/icons (they pointed at the faf-mcp repo). - scripts/sync-version.js writes every version stamp and tool count from package.json and the live tools/list: project.faf, manifest.json, agent.fafa, the server card, server.json, the README's .mcpb link, the landing page and the Core counts. A test holds every one to its source. - The README's .mcpb link names the release for its own version (it used a latest/download URL with a fixed file name, which breaks at the next release). - agent.fafa's tool tiers are the real ones (Core 14; 30 with FAF_TOOLS=all), not "planned, ~17 core", and its version is the package's. - The .well-known server card says the package version (it said 5.23.0, which never shipped). - CI's Status job reports each job's real result and fails when one failed; it no longer prints "Passed" whatever happened. - CI's lint and type-check block a merge. `npm run lint` fails on any error and on more warnings than today's 272. The format check that needed prettier (never a dependency) is gone. - CI's build check looked for a file that no longer exists; it now checks the bin, main and the handlers. - `npm test` also points TMPDIR, TMP and TEMP at a new temp folder for each run and fails if a test leaves anything in it; tests/copilot-grade.test.ts now removes the folders it makes. - The test suite is hermetic: `npm test` runs bun with a temp HOME and fails if a test writes into the checkout or leaves a file in that HOME. Tests no longer write into the real ~/Projects or HOME, use fixed /tmp paths, or depend on how deep the checkout sits. - Tests that could not fail now can: no `fail()` (bun has none), no assertion that only runs in a catch the call never reaches, no `expect(true)`. Wall-clock limits moved to the performance suite, which is observability, not a gate. - faf, faf_trust, faf_recall, faf_context, faf_setup, faf_cursor, faf_gemini, faf_tri_sync and both resources are tested through a real MCP round trip, including the MEMORY.md marker cases. CI holds a coverage floor on the totals over src/ (scripts/check-coverage.mjs); it only rises. - faf_about states facts: the format, the media type, the versions and where to start. The speed, reach and mood lines are gone. ### Removed - `faf_clear`, `faf_friday`, `faf_guide` and `faf_write` are retired: they are no longer listed, and a call by name returns an error with one line saying what to use instead. - `faf_chat` (retired in 5.7.0) now answers the same way: an error with one line. - `faf_check` has no `protect` / `unlock` any more and never writes `_protected_fields` into project.faf. No writer ever read that key, so nothing was ever locked. - The AGENTS.md, .cursorrules, GEMINI.md and conductor/ imports into project.faf are gone. `action: "import"` returns an error, so these tools can no longer rewrite a project.faf, or a parent folder's, from those files. Export and sync stay. - 41 source modules that no tool could reach (the old Mk3 commands, the Mk3 FafCompiler scorer, the tool registry, the visibility config, the unused licensing gate, the fuzzy detector), and the tests and scripts that only exercised them. The engine adapter keeps only the commands a tool calls. - The `bi-sync` / `bisync` engine aliases, which no tool called. - esbuild, @upstash/redis and faf-scoring-kernel are no longer dependencies, so installs are smaller and no longer run esbuild's install script. - mcp-registry-entry.json, faf-mcp-config.json, .npmignore and .mcpbignore are out of the tree (the tag `archive/cfm-v5-surface` keeps them). - The GitHub-API port behind faf_git — its GitHub extractor, its own .faf writer and its slot counter, about 1,050 lines — and its own scorer. faf_git no longer reads GITHUB_TOKEN or GH_TOKEN. - The PATH detector (`which faf` and `faf --version` at every start), the shell-out that ran it and the "faf-cli REQUIRED FIRST" startup banner. Nothing is run from PATH. - The file:// resource: it answered any URI with a placeholder line and read nothing. - claude-faf-mcp's own AGENTS.md, .cursorrules, GEMINI.md and Copilot renderers, and its local scorer. - `fafEnginePath` in the server config: there is no engine on PATH to point at. - docs/ is out of the tree (copied to the PLANET-FAF archive first; the tag `archive/cfm-v5-surface` keeps it). claude.faf.one served all of it, including internal evaluations, a press release and pages with removed tools. - The README's badge and footer line claiming an Anthropic MCP listing, the manifest's "Merged in Anthropic MCP ecosystem", and the old "standalone, zero CLI dependencies" and "only one production dependency" claims. - examples/test-project/project.faf, a legacy fixture with the maintainer's absolute path: step 1 of the example now creates the file. - The `f1-inspired` package keyword, and the `format` / `format:check` scripts (prettier was never installed). - tests/stress-test-v120.sh, which called files that no longer exist at the maintainer's absolute path. ### Changed - faf-cli `^7.13.1` (7.13.1 carries faf-cli's security patch for links in detection, and faf-cli's own output names a slot the app-type leaves out `slotignored`). A file with no faf markers always gets the faf block on top with every original byte kept below it, an old stamp-led faf file included. - The npm package ships only dist (no source maps), the icons, scripts/postinstall.js, project.faf and the listed docs. Dev scripts no longer ship. - The package `main` is now dist/src/server.js, which starts nothing when imported. The `claude-faf-mcp` bin still starts the server. - faf-cli loads through a plain `import('faf-cli')`; the loader that walked up directories to find it is gone. - scripts/verify-fafa.js checks the A2A card with faf-cli's `buildA2ACard`; the local copy is gone. - `npm run dev` works: it runs the server from source with bun. - `npm run lint` quotes its glob, so ESLint checks every file under src/, not just the first level. - faf_git needs git on PATH, because it clones the repo. Its description says it uses the network. - Core 14: faf_setup and faf_tri_sync are listed by default, so every tool the faf prompt, the README onboarding and the .mcpb manifest name is on a default install. - The prompts are `faf` and `faf-bench`, with no leading slash; `/faf` and `/faf-bench` still answer in 6.x. The faf prompt starts with faf_score, and faf-bench reads project.faf with faf_context `{ detail: true }`, which now returns the file's text. - manifest.json lists the Core 14, led by faf_init, and declares the two prompts. - manifest.json's long description names only what a default install lists: the faf_git line (a .faf from a GitHub repo, with its example) and the README 6Ws line are gone; both tools need FAF_TOOLS=all. - The server no longer advertises listChanged for tools or resources: no list changes while it runs. - Node 22 or later: engines.node and the manifest runtime are `>=22.0.0`, and scripts/check-engines.mjs holds them to the lowest Node in CI. It runs in CI and in prepublishOnly, which now builds, tests and checks it. - CI tests Node 22 and 24 on ubuntu, macOS and Windows, and packs the npm tarball, installs it in a temp folder and starts its bin (initialize, tools/list, faf_score) on each. - @anthropic-ai/mcpb is pinned as a dev dependency (2.1.2); pack:mcpb installs the bundle's dependencies with `npm ci`, from the lockfile. - claude.faf.one serves only public/index.html, written by scripts/build-landing.mjs from package.json and project.faf: no Trust Edition overlay, no Mk3.1 fallback line, a real og:image, and a privacy link to PRIVACY.md. The Cloudflare Worker moved from src/index.js to worker/index.js. - mcpaas.live/claude/mcp/v1 is no longer given as this server's hosted endpoint in the README Quick Start, agent.fafa, smithery.yaml or the landing page: it is MCPaaS, a separate server with its own tools. PRIVACY names it that way. - One install path: the README config is `npx -y claude-faf-mcp` (the global bin and bunx are alternatives), and the README says the npx config and the hook are unpinned. - PRIVACY lists every file claude-faf-mcp writes and what faf_git sends; SECURITY lists the real dependencies and the real file access; SUPPORT and CONTRIBUTING give instructions that work (Node 22, bun, dist/src/index.js, debugging with faf_debug and the MCP Inspector, one Discussions URL). - CHANGELOG history keeps its entries; the lines that claimed an official Anthropic registry listing and validation are corrected to what they were, a community README entry. Banned words and the trophy emoji are gone from the work surfaces. - project.faf names only the stdio transport (the endpoint of MCPaaS, a separate server, stays in surfaces.declared) and no command that does not exist; CLAUDE.md is re-rendered from it (no "BI-SYNC" footer). ## [5.22.1] - 2026-08-19 Patch — inherits The Projector Floor. ### Fixed - **README H1 said "The Compose Edition" instead of "The Projector Floor."** The 5.22.0 release commit updated CHANGELOG.md and the README's own What's New blockquote correctly but missed the H1 title line — npm bakes README into the tarball at publish, so the stale title was live. No functional change. ## [5.22.0] - 2026-08-18 — The Projector Floor A2A mapper uses faf cards — https://faf.one/context, same fafContextBlock() as MCP. Not raw provenance. ### Changed - **Compose faf-cli `^7.8.0`** (was `^7.7.0`). Inherits `faf cards` / `generateA2ACard` by construction. - **`fafaToA2ACard`** is a thin adapter: `opts.url` is the door; params are `fafContextBlock()` (or `generateA2ACard` when exported). Extension URI is `https://faf.one/context`, never `https://one.faf/context`. Unofficial `provenance.version` is dropped. ### Tests - **`tests/fafa-a2a-card.test.ts`** — URI + block lock. `tests/wjttc-edition-compose.test.ts` still the language-rail E2E. ### Notes / non-claims - **Claim:** A2A params === `fafContextBlock()`; URI is the dereference `https://faf.one/context`. - **Do NOT claim:** CFM serves a live A2A endpoint · invents a door · replaces A2A or MCP cards. - **Kill line:** one projector, every door. - `server.json` product `title` stays **Claude FAF**. ## [5.21.0] - 2026-08-11 — The Compose Edition Language Editions arrive by composition — pin faf-cli ^7.7.0 so Core `faf_auto` inherits the CLI rail (Dart · Go · C# · JVM · Ruby · Swift); Core 12 tools; `faf_enhance` removed. ### Changed - **Compose faf-cli `^7.7.0`** (was `^7.2.0`, lock was 7.2.0). Turbo-Cat / `faf_auto` / `faf_formats` inherit **by construction** the language Edition rail already shipped on the CLI: - **7.2.1** Dart/Flutter knowledge v2 · **7.3** Go · **7.4** C# · **7.5/7.5.1** JVM · **7.6** Ruby · **7.7** Swift - Kill lines apply (e.g. `go.mod` alone ≠ backend, `Package.swift` alone ≠ app) — no forked detectors in CFM. - **Precedent for sibling MCPs:** pin `faf-cli` to the same floor as npm latest when Editions land; do **not** re-implement language detection in the MCP. Composition is the product. See `docs/compose-faf-cli.md`. ### Removed - **`faf_enhance`** — removed from the MCP surface (and the bundled enhance command). AI rewrite of a filled `project.faf` was a silent DNA clobber; stack/human fill stays on `faf_auto` / `faf_go`. Aligns with faf-cli (enhance already gone there). Core tier is **12** tools. ### Tests - **`tests/wjttc-edition-compose.test.ts`** — permanent E2E that `faf_auto` / `faf_formats` surface faf-cli Edition signals (Go · Ruby · Swift · C# · bare JVM, no Spring leak). ### Fixed - **Test isolation** — suite no longer mutates repo-root `project.faf` via sticky adapter cwd (`faf_human_add` fixture). ## [5.20.0] - 2026-06-30 — The GitHub Registry Edition claude-faf-mcp joins GitHub's MCP Registry — discoverable in VS Code — as **Claude FAF**, its display title now emitted from `project.faf`, single-sourced and idempotent. ### Added - **`title` is now an emitted server-card field.** `scripts/gen-server-card.js` reads `project.title` from `project.faf` and composes it into `server.json` — so GitHub's MCP Registry (github.com/mcp, which powers VS Code's MCP discovery) shows **Claude FAF** instead of the auto-derived "Faf Claude Faf". `title` joins `name` and `_meta` as a single-sourced, never-hand-authored field; the BRAKE B1 idempotency test enforces emitted == live. ### Changed - `project.faf` gains `project.title: Claude FAF` — the single source for the display title, distinct from `project.name` (which drives the `one.faf/claude-faf-mcp` registry id). - `server.json` gains `repository.id` (GitHub repo node-id) — anti-resurrection hardening recommended by the MCP registry server-card best-practices. ## [5.15.0] - 2026-06-26 — The Instructions Edition CFM writes the file Copilot reads — done right. `.github/copilot-instructions.md` is now genuine, distinct Copilot instructions, not the AGENTS.md content reused. ### Changed - **`.github/copilot-instructions.md` is now Copilot-grade** — a CFM-native emitter replaces the AGENTS.md clone (`copilotExportCommand` no longer reuses `agentsExport`): a prose project overview, a `## Build & run` command section (build/CI as imperative commands), and the "broadly applicable / every request" framing GitHub's custom-instructions spec calls for. Distinct from AGENTS.md (which it outranks in-repo), reusing CFM's existing well-labelled stack. Per the FAF/WJTTC/TAF boundary, build/CI come from FAF context; testing is not a FAF slot. ## [5.14.1] - 2026-06-25 — The Copilot Edition Reachability fix: the Copilot emit now lives on the Core `faf_sync` tool. In 5.14.0 the `copilot` flag was wired only onto `faf_bi_sync`, which isn't in the default 13-tool surface — so a default user couldn't reach the headline feature. `faf_sync` now carries every format flag, and the redundant `faf_bi_sync` is retired. ### Changed - `faf_sync` (Core) gains `agents` / `cursor` / `gemini` / `copilot` / `all` flags — syncs `.github/copilot-instructions.md` (and AGENTS.md / .cursorrules / GEMINI.md) straight from `.faf`, reachable from the default surface. A bare `faf_sync` stays CLAUDE.md-only (unchanged default behaviour). ### Removed - `faf_bi_sync` — collapsed into `faf_sync`. It was never truly bidirectional (one-way `.faf → CLAUDE.md` + format exports), and every capability now lives on `faf_sync`. Tool surface: 13 Core, 35 with `FAF_TOOLS=all` (was 36). ### Added - WJTTC regression guard: `faf_sync` with `copilot:true` writes `.github/copilot-instructions.md` (in-process, asserts the file materializes) — the test that would have caught the 5.14.0 gap. ## [5.14.0] - 2026-06-24 — The Copilot Edition FAF now writes the file GitHub Copilot reads — from inside Claude. `faf_bi_sync` syncs `.github/copilot-instructions.md`, GitHub Copilot's widest-surface instruction file, straight from your scored `.faf`. ### Added - `faf_bi_sync` gains a `copilot` flag (and `all` includes it) — syncs `.github/copilot-instructions.md`, GitHub Copilot's repository-wide custom-instructions file, honored by default across web chat, code review, VS Code, JetBrains, Copilot CLI, and the coding agent. Non-destructive, auto-creates `.github/`. ### Fixed - `faf_bi_sync` now forwards every format flag (`agents`/`cursor`/`gemini`/`copilot`/`all`) through to the engine — they were advertised in the tool schema but silently dropped, so multi-format sync via the tool never actually fired. ## [5.13.0] - 2026-06-22 — 🧡 The Heartbeat Edition Persistent Project Context with Memory, looped for you. The SessionStart heartbeat now surfaces the intent delta — the goal and 6Ws the code can't carry — so every Claude Code session opens grounded in what your project *means*, not just what it contains. ### Added - **Heartbeat intent delta** — the SessionStart heartbeat now appends `· +N intent the code can't carry`, where `N` counts the populated human-intent slots (`project.goal` + the 6Ws, `slotignored` excluded). A live `.faf` reports e.g. `faf: context ✪ 100% — fresh · +7 intent the code can't carry`; with no intent slots filled, the suffix is omitted. A structural count of what only a human can give or confirm — never a fabricated benchmark number. - **README — "For Claude Code teams"** — how the committed `.faf` plus the SessionStart hook give every teammate's Claude the same grounding on `git clone`. ### Changed - **Tagline** — "Persistent Project Context with Memory, looped for you" (Context + Memory + the loop). ### Removed - **Two dead registry workflows** (`mcp-registry-publish.yml`, `publish-mcp-registry.yml`) — redundant io.github GitHub-OIDC auto-publish, superseded by the manual one.faf DNS publish in `/pubpro`. ### Registry - **One canonical listing** — the duplicate `io.github.Wolfe-Jam/claude-faf-mcp` is deprecated in favour of `one.faf/claude-faf-mcp` (DNS-verified); the `one.faf/context` receipt ships with this publish. ## [5.12.0] - 2026-06-21 — The Proof Edition `faf_bench` proves FAF's grounding lift in-session — a cold-vs-`.faf` benchmark with a mechanical `✪` receipt — and `faf_go` now bootstraps from a cold repo (init → auto → 6Ws). ### Added - **`faf_bench`** — the in-session AI-grounding benchmark, promoted to lead the Core tier. It derives a question set from the `.faf`, has the model answer them cold (no context) and with the `.faf`, grades mechanically (no judge — the `.faf` is the answer key), and emits a `✪` receipt showing the grounding delta. Proof you can run, in-session — not a pitch. - **`/faf-bench` prompt** — the honest two-pass session protocol: cold-blind first, never invents token counts, never presents the cold pass alone as a verdict. ### Changed - **`faf_go` now bootstraps a cold repo** — if no `project.faf` exists it runs `faf_init` → `faf_auto` first, then the 6Ws, so one call takes a bare repo to a real score. - **Core tier is now 13 tools** (`faf_bench` leads the default surface; `faf` stays Extended to keep the Glama-scored default surface coherent — AAA protected). ### Tools - **36 total** — 13 Core (advertised by default), the rest Extended via `FAF_TOOLS=all`. ## [5.11.0] - 2026-06-17 — The Distilled Edition claude-faf-mcp, distilled — a curated Core of 12 self-documenting tools, with the interview, README extractor, and server-card all composed from faf-cli's single source (no forks), and faf_go's new Table-of-8 where your goal seeds the 6Ws. Fewer tools, nothing forked, nothing guessed. ### Changed - **Core tier — a distilled 12-tool surface.** `tools/list` now advertises a focused **Core of 12** by default (`faf_init`, `faf_auto`, `faf_go`, `faf_enhance`, `faf_score`, `faf_doctor`, `faf_sync`, `faf_context`, `faf_trust`, `faf_about`, `faf_etch`, `faf_recall`). The other 23 stay one flag away — set `FAF_TOOLS=all` to expose every tool. Dispatch is unchanged, so Extended tools remain callable by name even when un-advertised. The 12 Core descriptions were rewritten verb-first (what it does · what it returns · when to use vs which sibling). - **`faf_go` — the Table-of-8.** The interview now seeds the 6Ws from your project goal and presents the full Table-of-8 — seeded rows are confirm-or-edit suggestions, empties are asked — single-sourced from faf-cli's `buildTableOf8`. ### Added - **`server.json` emitter** — `npm run gen:server-card` composes the registry identity (`one.faf/*` name + the `one.faf/context` `_meta` block) from faf-cli; `server.json` is now regenerable from a single source instead of hand-authored. `--sha` stamps the real `.mcpb` `fileSha256` at release. ### Removed - The local README extractor — `faf_readme` now composes faf-cli's `relentlessContext` (compose-not-fork; one less forked path). ## [5.10.0] - 2026-06-17 — The Dart Edition **claude-faf-mcp now reads Dart & Flutter — it knows a Flutter app from a pure-Dart CLI.** Detection by composition: because CFM composes faf-cli's Turbo-Cat (The Sourced Edition), faf-cli 6.13.0's content-aware, pubspec-driven Dart classifier arrives by construction — no forked parser, no drift. ### Added - **Dart & Flutter detection, by composition.** `faf_formats` / `faf_auto` now surface Dart and Flutter projects correctly via faf-cli's single-source Turbo-Cat: a Flutter app reads as Flutter (state + routing detected), a pure-Dart CLI reads as Dart — **not** mis-flagged as Flutter — and a Dart MCP server / backend surfaces its `api_type` and framework. No forked pubspec parser; the classifier lives once in faf-cli and CFM composes it. The doctrine-pure fix for the drift a Dart/Flutter expert flagged publicly. ### Changed - **Composes `faf-cli` `^6.13.0`** (from `^6.10.1`) — the release carrying the content-aware Dart classifier in Turbo-Cat. ### Security - **`npm audit fix`: `hono` → 4.12.25, `js-yaml` → 4.2.0.** Clears the 🔒 Security Audit CI gate (`hono` path-traversal / CORS / cookie advisories — high; `js-yaml` quadratic-complexity DoS — moderate). `npm audit` now reports 0 vulnerabilities; both semver-safe patch bumps, the hono HTTP-SSE transport unaffected. 35 tools. 572 tests, 0 fail. Zero-Config — one-click `.mcpb`, no terminal, no JSON config. ## [5.9.1] - 2026-06-14 Patch — inherits The Sourced Edition. ### Changed - **Registry namespace → `one.faf/*`.** `claude-faf-mcp` now publishes to the MCP Registry as `one.faf/claude-faf-mcp` (from `io.github.Wolfe-Jam/claude-faf-mcp`) — the DNS-verified `one.faf` namespace (reverse-DNS of `faf.one`) in place of the personal GitHub namespace. The FAF context block now rides `server.json` `_meta` under `io.modelcontextprotocol.registry/publisher-provided` — emitted by faf-cli (`registryMeta`), honest-first: no score baked, it points to the `.faf` and asserts determinism (verify, don't trust). ### Fixed - **`faf_go` is the 6Ws interview, not the full slot interview.** The guided interview now correctly uses `SIX_WS_INTERVIEW` (8: name + goal + 6Ws) instead of `INTERVIEW` (16) — language and stack are sourced, never asked of the human. ## [5.9.0] - 2026-06-12 — The Sourced Edition **Every answer comes from one source.** claude-faf-mcp now composes faf-cli's single-source engines — the 6Ws interview and Turbo-Cat detection — instead of carrying its own copies that drift. Fills come from real evidence or stay honestly empty; nothing is guessed. FAF don't lie, by construction. ### Changed - **`faf_go` composes the canonical interview.** The guided interview is now sourced from faf-cli's public `INTERVIEW` / `interviewForMissing` (shipped in faf-cli 6.9.0) — the hand-maintained local question registry is deleted, so question text and options can never drift from the kernel. Only missing AND active slots are asked (`slotignored` is skipped), so the full canonical set never means more questions on screen. - **Turbo-Cat detection composes faf-cli.** `faf_formats` and `faf_auto` now use faf-cli's single-source Turbo-Cat (`turboCatScan` / `turboCatSlots`, ~200 formats; faf-cli 6.10.1) — the local 25-entry copy (`discoverFormatsInternal`) is deleted. Detection that's correct and can't drift: a server with an `mcpb` `manifest.json` is detected as what it is, not mis-flagged as a Chrome extension. - **The `/faf` prompt drives to a *verified* 100%, and maintains it.** It now runs `faf_trust` to attest the score with the `✪` parity receipt, offers `faf_setup` to keep 100% fresh every session, and reports the quiet `✪` seal. Its lead rule: fill only from sourced evidence — never guess; hand the human, plainly, only what only they can answer. ### Removed - **The v5 guessing extractor.** The legacy human-context extractor inferred slots from the project name / tech stack (writing `INFERRED`/`DEFAULT` placeholders into empty slots). Removed; replaced by a sourced-or-empty README extractor, verified by a test that proves it cannot fabricate. No-guess is now structural, not accidental. 35 tools live. 567 tests, 0 fail. Composes faf-cli `^6.10.1`. ## [5.8.0] - 2026-06-11 — The Trust Edition **Claude Code-native context that just works.** Five pillars, one theme: the experience an agent can parse and a human can read (quiet + typed), the proof a third party can verify (parity hash + ✪ receipt), and the integration that earns "native" (the session hook). Plus enhanced interop — your files get enhanced, never replaced. ### Added - **Native SessionStart hook (`--session-refresh`).** One cheap, deterministic action at every Claude Code session start: refresh CLAUDE.md's faf-managed block from project.faf, then hand over the baton — a one-line heartbeat carrying the quiet-ladder seal and score (`faf: context ✪ 100% — fresh`). Freshness-gated (no write, no mtime churn when current), never throws, always exit 0; non-faf directories stay fully silent. - **`faf_setup` (tool #35).** The explicit hook installer. Preview by default — shows the exact settings JSON and path, writes nothing; `confirm: true` merges non-destructively into the project's `.claude/settings.json` (every existing key and hook preserved, idempotent); `remove: true` takes out exactly the faf hook. Malformed settings are surfaced, never overwritten. - **Determinism parity hash.** `faf_score` (and `faf_trust`) now carry an engine-agnostic `parity` receipt: a SHA-256 over the canonical score projection, bound to the input bytes — any conformant engine (faf-cli, the Rust kernel, this server) reproduces it, and a third party can verify `sha256(projection) === parityHash`. Falsifiable, not self-asserted. - **The ✪ trust receipt.** `faf_trust` emits a render-identical, no-emoji, self-verifying score+parity artifact (text + structuredContent) — a receipt that means the same thing in a terminal, a CI log, and a report. - **Typed structured output across the data tools.** `faf_context`, `faf_list`, `faf_formats`, `faf_dna`, `faf_doctor`, `faf_check` join `faf_score`/`faf_status` with `outputSchema` + `structuredContent` on every return path (text retained for back-compat). ### Changed - **Quiet output, everywhere, always.** Tool results and descriptions carry no emoji — plain, parseable, scriptable. Tier glyphs use the quiet ladder `♡ ○ ● ◇ ◆ ★ ✪` (geometric symbols, render-identical); ✪ is the Trophy seal. One predictable output format, no toggle. - **The CLAUDE.md block faf writes is quiet too.** The native faf→CLAUDE.md renderer now emits the canonical format (`What This Is / Stack / Context`) — no emoji, no brand voice — matching faf-cli's export, since the session hook makes that block part of every session's context. `slotignored` slots stay invisible. ### Fixed - **Enhanced interop — your files are enhanced, never replaced.** The interop tools (`faf_agents`, `faf_gemini`, `faf_cursor`, `faf_sync`) overwrote AGENTS.md, GEMINI.md, .cursorrules, and CLAUDE.md wholesale — anything you'd written was lost. Now every write goes through a non-destructive injector: a structured `.faf` block owns the top of the file, everything you've written below is preserved, re-runs update the block in place (idempotent), and existing faf-written files upgrade cleanly in one pass. A build-failing write-guard makes the old behavior impossible to reintroduce. - **`faf_trust` works again.** It shelled out to a `faf trust` subcommand that no longer exists in faf-cli (every call errored); now a self-contained local attestation. 35 tools live. 547 tests, 0 fail. ## [5.7.2] - 2026-06-11 — The Canonical Edition ### Security - **Path confinement on every caller-supplied `path` argument (CWE-22 / CWE-73 / CWE-200).** The shared `getProjectPath()` chokepoint (feeding the `.faf` tools) and the `faf_read` / `faf_write` file tools resolved a caller path straight into a filesystem read/write with no confinement — so an absolute path or `../` traversal could read any file the server process could read (e.g. `/etc/passwd`, `~/.ssh/id_rsa`) or write outside the project. New `safe-path.ts` confines reads to `.faf` / `.fafm` context files and general file ops to the project root (cwd + system temp; override with `FAF_ALLOWED_ROOTS`), canonicalizes through symlinks (closing the symlink bypass for the `path` argument; see the 6.0.0 correction: a context file that was itself a link was still followed), and rejects traversal/absolute escapes; `callTool()` gains a central PATH-DENIED guard. Identified by the maintainers during a sibling-server audit prompted by the coordinated disclosure of the same class of issue in `grok-faf-mcp` by Zhihao Zhang (Worcester Polytechnic Institute). Adds a security regression suite (incl. symlink bypass). ## [5.7.1] - 2026-06-10 — The Canonical Edition Typed structured output and one-click registry install — the reliability layer made machine-readable. ### Added - **MCP `structuredContent` + `outputSchema`** on `faf_score` and `faf_status` — typed structured results (score, tier, populated/empty/ignored/total, next tier; status, filename, path) returned alongside the human-readable text on every path. Spec 2025-06-18; text retained for backward compatibility. - **`mcpb` registry package** in `server.json` — one-click Claude Desktop install from the MCP registry, pointing at the released `.mcpb` with its SHA-256. ### Fixed - **README one-click link** pointed at `claude-faf-mcp-5.5.2.mcpb` (404 on the current release) → now the live bundle. ### Changed - **No stale version references** — faf-cli bumped to `^6.8.0` (latest); `project.faf` `faf_version` corrected to `2.5.0` (matches the latest tooling / base tier, not the enterprise 33-slot marker); `docs/index.html` version badge and a hardcoded server-info version string now track the package version. ## [5.7.0] - 2026-06-09 — The Canonical Edition The original FAF MCP, made canonical: the registry remote now hits the live Cloudflare edge directly (no Vercel/SSE redirect), the redundant `faf_chat` shim is retired (the host is your chat) — consolidated into 32 must-have tools. ### Fixed - **`server.json` `remotes`** — `sse → claude-faf-mcp.vercel.app/sse` → `streamable-http → https://mcpaas.live/claude/mcp/v1`. The Vercel/SSE URL only 308-redirected to the edge; strict SSE health-checks could choke on the redirect-to-streamable-http. Now points at the canonical edge directly (same fix grok-faf-mcp carried in 1.5.1). ### Changed - **`faf_chat` retired** (was a stranded branch) — un-advertised from `tools/list`; the host (Claude Desktop / Claude Code) *is* the chat, and the old body shelled `faf chat` which faf-cli no longer ships. Kept as a deprecation **stub** (still callable → clear "retired" notice, never "unknown tool"). **Tool count 33 → 32.** Mirrors grok-faf-mcp's fleet retire. - **CI: `faf-taf-git` → v2.2.0** (was a stranded branch) — dropped the bun→jest shim in `.github/workflows/ci.yml`. No breaking changes; `faf_chat` callers get a graceful deprecation notice. ## [5.6.2] - 2026-06-08 MCP capability completeness — the stdio server now answers every capability it advertises. Strict clients (Claude Desktop, Cursor) and Glama's Inspector probe each advertised capability; a `-32601` flags the server even when tools work. ### Fixed - **`resources/templates/list` now returns `{ resourceTemplates: [] }`** instead of `-32601`. Registered `ListResourceTemplatesRequestSchema` (`src/server.ts`). - **Dropped unbacked `subscribe: true`** from the advertised `resources` capability (no subscribe handler exists) → `resources: { listChanged: true }`. `/info` payload aligned. `prompts` was already backed — unchanged. No tool changes. Repo hygiene (prior): removed 41MB of committed build artifacts. ## [5.6.1] - 2026-05-26 Loop closed on truthful, single-sourced scoring. The active MCP handler now reads faf-cli's real scorer directly — same path the championship layer was already on, same number `faf score` (CLI) and faf-mcp 2.1.1 emit. ### Fixed - **`faf_score`** — now calls faf-cli's `scoreFafYaml` (the IANA-spec scorer) directly, replacing the FafCompiler-based path. Output reformatted to the canonical tier card with `FAF SCORE: /100 (%)`, progress bar, populated/total slot count, and the next-tier hint. The banned medal / colored-circle tier ladder (🥇🥈🥉🟢🟡🔴🤍) is gone from this surface — only canonical Unicode tier glyphs (★ ◆ ◇ ● ○ ♡) remain. - **Invalid `.faf` handling** — `0/100 (0%) ○ INVALID` for parse failures, `○ UNREADABLE` for fs errors, `♡ no .faf` for absence. Honest zero with a diagnostic, never a fake score, never a crash. ### Tests - **WJTTC AERO Phase 2** — score-parity assertion tightened to TRUE parity: MCP `faf_score` numeric == faf-cli `scoreFafYaml(...).score` on the same YAML. Determinism + repeatability tests retained as high-signal companions; FINDING comment retensed from v5.6.0 observation → v5.6.1 resolved. ## [5.6.0] - 2026-05-25 ✪ **FAF-binary scoring lands in Claude Desktop.** The real FAF engine — faf-cli's WASM scoring kernel — now powers every score in claude-faf-mcp. What you see is the exact, deterministic score your AI and `faf score` read. One engine, one number, across the whole FAF family. ### What's new - **Real-engine scoring, everywhere** — `faf_score`, `faf_show`, `faf_status` and the footer all run on faf-cli's binary scorer. Deterministic: identical every time. - **`faf_display` renders the genuine `project.html`** — straight from faf-cli's renderer, byte-identical to `faf show`. The exact view your whole team sees. - **Canonical tiers, live in Claude Desktop** — the official ✪ ★ ◆ ◇ ● ○ ♡ ladder. ### Under the hood - **faf-cli ^6.7.1** — built on faf-cli's typed public API: the real scorer + the project.html renderer, as the single source of truth. ## [5.5.2] - 2026-05-03 ### Added - **Postinstall star CTA** — runs once on `npm install -g claude-faf-mcp` after the success confirmation. Quiet, no throws, no spam. ### Changed - **displayName standardized** to `.faf 🐘` — pairs the constant elephant family mark with each surface's modifier in MCP client lists (matches grok-faf-mcp's `.faf 🐘⚡️ for Grok` pattern). - **Package description aligned** to "Persistent project context for AI" — the canonical positioning across the FAF family. npm and MCP Registry catalogs both pick this up. - **Branding pass** — README scoring table now uses geometric tier symbols (★ ◆ ◇ ● ○ ♡) matching `faf-cli/src/core/tiers.ts`; decorative emojis stripped from CLI surfaces. - **manifest.json description** sharpened to "Persistent project context that survives sessions, works across AI tools, and eliminates re-explaining" — strengthens the user-facing pitch in Claude Desktop's Extensions catalog. ### Fixed - **vercel.json restored** — fixes the "No Output Directory" deploy error that surfaced after a prior cleanup pass. claude-faf-mcp.vercel.app builds cleanly again. - **MCP Registry hygiene** — server.json metadata pass for cleaner Registry listing. ### Internal - CI Performance Check job is now non-gating — perf tests report but don't block main CI. Restores red-means-real signal integrity. - **Perf-check fake-fail eliminated** — `test:performance` now overrides `testPathIgnorePatterns` so Jest actually picks up `tests/performance.test.ts`. Workflow had been silently exit-1'ing on "No tests found" for months, painting a fake red X on every commit. Real perf gate restored: 10/10 perf tests pass in 14s ("Championship Performance Achieved"). - Removed `npm publish` from CI workflow (#50). /pubpro is the single source of truth for shipping; CI validates only. - Removed `publish-mcp.yml` auto-publisher. Same doctrine: CI validates, pubpro publishes — never both. - Weekly npm audit auto-fix kept current. ### Notes - Docs + branding + CI hygiene patch — no MCP protocol changes, no breaking changes for tool users. Safe upgrade for all consumers. - First release after the FAF Foundation alignment sweep (`.faf 🐘` family mark, "Persistent project context" tagline, three-reader tree). --- ## [5.5.1] - 2026-04-19 ### Docs - **README hero now promotes one-click `.mcpb` install** — the Extension Edition's headline feature is finally in the README visitors land on. Download-and-double-click is the primary path; npm/copy-paste kept as alternatives. - **v5.5.0 release asset** — `.mcpb` bundle uploaded to GitHub release for direct download via `releases/latest/download/`. Docs-only release; code unchanged from v5.5.0. --- ## [5.5.0] - 2026-04-15 — The Extension Edition ### Added - **Desktop Extension (.mcpb)** — one-click install for Claude Desktop. No JSON config, no terminal. Drag and click. - **`pack:mcpb` build script** — repeatable .mcpb packaging with production deps only (6.2MB bundle) - **`destructiveHint` annotations** on all 32 tools, for the Connectors Directory's annotation requirement - **`examples/test-project/`** — sample project for directory reviewers and user onboarding - **WJTTC v5.5.0 report** — 67/67 tests, 100% pass rate across all three tiers ### Changed - **manifest.json** — synced to v5.5.0, fixed icon path to 512px PNG - **SECURITY.md** — updated supported versions (5.x, 4.x) and date ### Removed - 27 tracked junk files (test debris, Python artifacts, old WJTTC reports, victory-lap.txt) - `servers/` submodule (28MB Anthropic monorepo copy) - `vercel.json`, `server.json`, `setup.py`, `requirements.txt` (leftovers) - Backup files (`*.backup`) --- ## [5.4.0] - 2026-04-13 — The Conductor Edition ### Added - **`/faf` MCP Prompt** — type `/faf` in Claude Desktop and it drives your project to 100% automatically. Check → Score → Improve → Sync → Lock ✪ - Relentlessly seeks 100%. Does not stop until the score is Trophy. - Syncs `.faf` ↔ `CLAUDE.md` ↔ `MEMORY.md` on completion. - Optional `path` argument for non-current-directory projects. - "Claude is now optimized for [project name]. FAF defines. MD instructs. AI codes." - **Prompts capability** added to MCP server — `prompts/list` and `prompts/get` now registered ### Changed - Removed `faf_what` — redundant with `faf_about` (32 tools, zero redundancy) - Tool count: 33 → 32 MCP tools --- ## [5.3.2] - 2026-04-12 — 32 Tools, Zero Redundancy ### Changed - Removed `faf_what` — redundant with `faf_about` (which covers the same ground with more depth) - Tool count: 33 → 32 MCP tools --- ## [5.3.1] - 2026-04-12 — tri-sync Free for Claude Desktop Users ### Changed - **tri-sync is now free for all Claude Desktop users** — `.faf` ↔ `CLAUDE.md` ↔ `MEMORY.md` in one command. Nelly never forgets — and now she's free for all builders 🐘 - Removed Pro gate from `faf_tri_sync` — no trial, no friction, no paywall - Pro feature, free for developers. Teams & Enterprise: [faf.one/pro](https://faf.one/pro) (plans) - **FAF defines. MD instructs. AI codes.** — core messaging added to README ## [5.3.0] - 2026-04-10 — Analytics + Security ### Added - **Persistent all-time analytics** via Upstash Redis — download and usage stats tracked across sessions - **Smithery sandbox support** — `server-card.json` for Smithery.ai marketplace listing - **Glama ecosystem linking** — `glama.json` updated with related servers for cross-discovery ### Fixed - Security: resolve `path-to-regexp` and `yaml` vulnerabilities (npm audit) - Security: fix `flatted` prototype pollution vulnerability (GHSA-rf6f-7fwh-wjgh) - CI: case-insensitive assertion fix for React detection in `faf_quick` tests ## [5.2.0] - 2026-03-10 — Enhanced Scoring ### Changed - **FafCompiler scoring engine** — `faf_score` now powered by the same FafCompiler that drives faf-cli - Type-aware precision: CLI (9 slots), fullstack (21 slots), web-app, API — each scored correctly - Section breakdown with project/stack/human percentages and next milestone - Real error diagnostics replace generic messages - CI hardened: deprecated actions fixed, dependabot replaced by automated audit ### Added - **40-test WJTTC compiler scoring edge case suite** across 5 tiers - Test count: 351 → 391 (12 suites, 2,346 executions per push) - **README rewrite** — 3Ws/6Ws onboarding (Uber, Airbnb, Slack, Venmo examples), categorized tools, 🐘 Nelly branding ## [5.1.0] - 2026-03-04 — 🐘🧡 Nelly Edition ### Added - **Tool #33: `faf_tri_sync`** — Sync project.faf to Claude MEMORY.md (Pro feature) - `export`: writes .faf context into MEMORY.md (merges, preserves Claude's own notes) - `status`: shows MEMORY.md state (lines, FAF section, Claude notes) - Pro-gated: 14-day free trial, then $3/mo · $19/yr · $29/yr Global - Same `~/.faf/license.json` gate as faf-cli — one key works everywhere - bi-sync stays free forever; tri-sync adds RAM (MEMORY.md persistence) ### Changed - Tool count: 32 → 33 - Version bump: 5.0.0 → 5.1.0 ## [5.0.0] - 2026-03-04 ### Added - **Tool annotations on all 32 tools** — title, readOnlyHint, destructiveHint, openWorldHint per MCP spec - **PRIVACY.md** — privacy policy (local-only processing, no telemetry, no tracking) - **manifest.json** — Desktop Extensions manifest (manifest_version 0.3) - **Non-developer section** in README — 3-step install for Claude Desktop users - **Privacy section** in README linking to PRIVACY.md ### Changed - **Desktop Edition** — ready for Claude Desktop Extensions submission - Tool descriptions updated: "THE JPEG for AI" → "project DNA for AI" - manifest.json and PRIVACY.md included in npm tarball ### Why Major Version Tool annotations change the MCP contract surface. All 32 tools now expose structured metadata (title, readOnlyHint, destructiveHint, openWorldHint) that clients can use for UI, permissions, and safety classification. ## [4.5.1] - 2026-03-04 ### Fixed - **Tool count accuracy** — README, server.json, and postinstall now reflect 32 active MCP tools - **Removed ghost tool** — `faf_sixws` removed from README (not implemented in tools.ts) - **Stale handler reference** — project.faf now points to `src/handlers/tools.ts` ### Changed - **MCP SDK** bumped from `^1.20.1` to `^1.27.1` - **Tarball trimmed** — source maps excluded, 0 `.map` files shipped ## [4.5.0] - 2026-02-27 ### Added - **AI Format Interop** — 5 new MCP tools for cross-platform AI context - `faf_agents`: Import/export/sync AGENTS.md (OpenAI Codex / Linux Foundation) - `faf_cursor`: Import/export/sync .cursorrules (Cursor IDE) - `faf_gemini`: Import/export/sync GEMINI.md (Google Gemini CLI) - `faf_conductor`: Import/export Conductor directory structure - `faf_git`: Extract .faf context from any public GitHub repo URL - **Bi-sync `--all` flag** — Sync project.faf to all formats at once (CLAUDE.md + AGENTS.md + .cursorrules + GEMINI.md) - **7 bundled parsers** — All parser logic runs standalone, zero CLI dependency - agents-parser, cursorrules-parser, gemini-parser, conductor-parser - `github-extractor`, `faf-git-generator`, `slot-counter` - **95 new tests** across 7 WJTTC tiers (Parser Units, Import/Export, MCP Integration, Engine Adapter, Security, Performance, Roundtrip) - Tool count: 56 → 61 (25 core + 36 advanced) ### Changed - Upgraded bi-sync engine with `agents`, `cursor`, `gemini`, `all` options ## [4.1.3] - 2026-02-15 ### Fixed - **Remove 105% scoring system** - Align with official FAF tier system (0-100%) - Remove Easter egg logic that awarded 105% for rich .faf + CLAUDE.md - Update to Trophy (100%) as perfect score - 🍊 Big Orange is now a BADGE awarded separately, not a calculated score - Update tests and documentation to reflect correct tier system - Fixes alignment with FAF standard where scores range 0-100% ### Changed - Updated faf-cli dependency to v4.4.0 ## [4.1.2] - 2026-02-09 ### Fixed - Fixed npm install hang that prompted for `npm fund` input - Postinstall script now uses /dev/tty for direct terminal output - Install completes smoothly without user interaction required ## [4.1.1] - 2026-02-09 ### Fixed - Improved postinstall UX with clear success message - Shows version number, tool count, and quick test command - Replaced promotional language with professional, useful output - Ensures scripts directory included in published package ## [4.1.0] - 2026-02-09 ### Changed - Updated faf-cli dependency from v3.2.6 to v4.3.0 - Now includes Voice API Edition features (v4.2.0) - Now includes Foundation Layer features (v4.0.0) ### Added - **faf_sixws** - 6Ws Builder integration - Interactive web form at faf.one/6ws - CLI paste-back workflow - Answer 6 questions to create AI-ready context - Works with Claude, Gemini, Grok, Cursor, Codex, WARP - **faf_human_add** - Complete 6Ws Builder workflow - Merge YAML from faf.one/6ws web form - Set individual fields (who/what/where/why/when/how) - Non-interactive bundled command (MK3 engine) - Instant score boost (+25-35% typical) - **faf_readme** - Auto-extract context from README.md - Intelligent pattern matching for 6 Ws extraction - Confidence scoring for extracted fields - Extract-only mode (preview what's found) - Auto-merge mode (add to project.faf) - Overwrite mode (replace existing fields) - Same score boost as manual entry (+25-35%) - Zero manual work required - Support for eternal voice memory (xAI Grok integration) - IANA-registered format features (application/vnd.faf+yaml) ### Fixed - All 212 tests passing - WJTTC MCP Certification: Championship Grade - Performance optimizations from latest CLI ## [4.0.0] - 2026-01-25 ### Added - **faf_go** - Guided interview to Gold Code (100% AI-Readiness) - Two-phase operation: returns questions, then applies answers - 13 fields in question registry (project.*, human_context.*, stack.*) - Priority ordering for optimal question flow - Structured JSON output for Claude's AskUserQuestion - **faf_auto** - ONE COMMAND TO RULE THEM ALL - Zero to Championship AI context instantly - Creates project.faf if missing - Runs TURBO-CAT format discovery - Extracts human context from README - Creates CLAUDE.md for bi-sync - Shows before/after score with timing - **faf_dna** - DNA Journey Tracking - Shows evolution from birth to current (22% → 85% → 99%) - Creates birth certificate on first run - Displays milestones and growth stats - Motivational messages based on progress - **faf_formats** - TURBO-CAT Format Discovery - Discovers 24+ known format files in project - Extracts intelligence from package.json - Writes the stack signature - Provides slot fill recommendations - Returns JSON or human-readable output - **faf_quick** - Lightning-fast .faf creation - One-liner format: "name, description, language, framework, hosting" - Auto-detects project type from inputs - Minimum: name and description - **faf_doctor** - Health check for .faf setup - Diagnoses common issues - Checks .faf validity, CLAUDE.md, project files - Provides fix suggestions ### Changed - **Major version bump to match faf-cli v4** - Tool count increased from 21 to 27 - Added internal helpers: `discoverFormatsInternal()`, `calculateSimpleScore()`, `detectProjectTypeFromQuick()` - Added WJTTC v4.0.0 test suite (49 tests across 3 tiers) - Total test count: 212 ## [3.3.10] - 2025-01-24 ### Fixed - **faf_enhance MCP tool** - Fixed "undefined" error when tool returned results (#3) - Changed property access to check `.message` before `.output` in EnhanceResult ## [3.3.9] - 2025-01-23 ### Changed - Removed Discord links from README (no longer active) - Added MCPaaS to ecosystem links ## [3.3.8] - 2025-01-20 ### Added - **Glama MCP Directory** - Added glama.json for marketplace listing - **Smithery Marketplace** - Added smithery.yaml with metadata ### Changed - README reframed around lifecycle value and Gold Code messaging - Added Without/With FAF pain point comparison to README - Cleanup: Removed Discord scripts, added .mcpb package ## [3.3.7] - 2025-12-22 ### Added - **TYPE_DEFINITIONS Scoring Parity** - Ported from faf-cli v3.2.5 - 94 project types + 38 aliases for accurate slot-based scoring - Single source of truth for project type detection - Ensures MCP scoring matches CLI scoring exactly ### Changed - Scoring engine now uses TYPE_DEFINITIONS for slot applicability - Improved type detection for CLI, fullstack, library, and other project types ## [3.3.6] - 2025-12-17 ### Added - **WJTTC MCP Certification Standard** - 7-tier certification system for MCP servers - Tier 1: Protocol Compliance (MCP spec 2025-11-25) - Tier 2: Capability Negotiation - Tier 3: Tool Integrity - Tier 4: Resource Management - Tier 5: Security Validation - Tier 6: Performance Benchmarks (<50ms operations) - Tier 7: Integration Readiness - **wjttc-mcp.test.ts** - Comprehensive MCP certification test suite - Performance metrics (tool list, tool call, file ops, concurrent ops) - Memory growth tracking - Full certification report output - **WJTTC-MCP-v3.3.6-REPORT.json** - Machine-readable test results ### Changed - Test suite now outputs WJTTC certification level (CHAMPIONSHIP GRADE) - All 5 test suites passing (visibility, performance, security, wjttc-mcp, desktop-native) ## [3.3.4] - 2025-12-01 ### Added - **Subsite Auto-Detection** - Smart scoring for static HTML subsites - Pattern detection: No `package.json` + has `index.html` - Auto-ignores package.json-derived stack slots (backend, api_type, runtime, database, etc.) - Subsites can achieve 100% score without manual configuration - Auto-fills: `stack.frontend`, `stack.hosting`, `stack.build`, `stack.cicd` - Ideal for landing pages, demos, documentation subsites - **Path Context Enhancement** - All action tools now support explicit `path` parameter - `faf_context` tool for explicit session context management - Auto-set context when reading .faf files via `faf_read` - Session state persists for subsequent calls - **faf_human_add** - Renamed from `faf_human_set` for consistency with CLI ## [3.3.3] - 2025-11-27 ### Fixed - **Tier System Alignment** - Synchronized Mk3 tier system across all code paths - JSON output now uses canonical tier names (Trophy, Gold, Silver, Bronze, Green, Yellow, Red, White) - Fixed 0% edge case to show White tier (🤍) - All scorecard renders now use unified `getScoreMedal()` function - **Removed Unauthorized Branding** - Cleaned up hallucinated racing terminology - Removed "Championship", "Podium Edition", "Race ready", "Pit Stop" from user-facing output - Tool descriptions updated to neutral language - Help text now shows proper Mk3 tier system - **README Cleanup** - Removed the racing branding, aligned with code changes ## [3.3.2] - 2025-11-16 ### Fixed - Updated Discord community invite link to working URL (never expires) ## [3.3.1] - 2025-11-12 ### Changed - **README Simplification** - Minimalist Quick Start following Claude Code's clean approach - "Copy and paste this to Claude/your AI" - Zero friction installation - Single-line config instruction (no verbose JSON blocks) - npm as primary install method (traffic/discovery optimized) - Desktop Extension as one-click alternative - **Strategic Positioning** - Optimized for npm search ranking and discoverability - Removed Projects Convention section (moved to docs) - Removed Troubleshooting section (moved to docs) - Clean, professional landing page ### User Experience This release perfects the installation messaging: users get ultra-minimal instructions while we maintain maximum npm download metrics for ecosystem discoverability. ## [3.3.0] - 2025-11-12 ### Added - **Desktop Extension (.mcpb)** - One-click installation bundle with branded FAF orange icon - Packaged .mcpb format for drag-and-drop installation in Claude Desktop - Orange smiley icon displays in all MCP server views - Available from GitHub releases page - **MCP Protocol Icons** - Added full icon set (48x48, 128x128, 256x256, 512x512) to server.json - Icons hosted on GitHub raw URLs for registry display - Proper MIME types and size specifications ### Changed - **One-Command Installation** - Moved faf-cli from peerDependencies to dependencies - `npm install -g claude-faf-mcp` now auto-installs both packages - Dual download metrics maintained (both packages counted separately) - Eliminated manual two-step installation process - **README Restructure** - Added two installation options - Option 1: npm (one command, no config editing) - Option 2: Desktop Extension (with branded icon) - Clear documentation of path resolution system ### Installation Experience This release perfects the installation flow: users get one-command simplicity while we maintain accurate download metrics for both claude-faf-mcp and faf-cli packages. ## [3.2.0] - 2025-11-10 ### Added - **Podium Edition Scorecard** - Full championship-style scorecard with `faf_score --full` flag - Dynamic status tiers (PODIUM EDITION, RACE READY, QUALIFYING, IN DEVELOPMENT) - Four detailed sections with live progress bars (Core Intelligence, Context Delivery, Performance, Standalone Operation) - Real-time metrics calculated based on project files (project.faf, CLAUDE.md, README.md, package.json) - Smart next steps based on what's missing in your project - Mobile-friendly "project.faf score: podium" format - Includes new Claude quote: "It's so logical if it didn't exist, AI would have built it itself" ### Changed - **README Restructure** - Following Svelte/Vercel pattern for clean landing page - README.md now uses clean landing page content (155 lines → from 564 lines) - Version history moved to CHANGELOG.md (this file) - GitHub Pages (wolfe-jam.github.io/claude-faf-mcp/) is now canonical documentation - Landing page tagline updated to new Claude quote - Title color changed to orange (#FF8C00) for brand consistency ### Project Milestone This release inaugurates the "project.faf scorecard era" - transforming the static documentation scorecard into a dynamic, interactive feature accessible through MCP tools. ## [3.0.5] - 2025-11-07 ### Added - **Discord Release Automation** - Automatic Discord announcements for new releases - **MCP Mission Statement** - Clarified .faf's position as the Context layer for Model Context Protocol ### Changed - **Documentation Polish** - Updated README from beta messaging to stable v3.0.4+ docs - **Code Cleanup** - Post-release refactoring and optimization ### Fixed - **File Utils** - Simplified file handling logic - **FAF File Finder** - Improved project.faf detection with better fallback logic ## [3.0.4] - 2025-11-06 🏎️ **100% Standalone Achievement - Championship Complete** ### Added - **faf_quick** - Lightning-fast project.faf creation (3ms average) - **faf_enhance** - Intelligent enhancement with auto-detection (63ms) ### Changed - **Mk3 Complete** - 14/14 bundled commands (was 12/14) - **100% Standalone** - Zero CLI dependencies across all 50 tools - **16.2x Speedup** - Average performance improvement over CLI versions - **19ms Average** - Execution time across all bundled commands ### Performance - 50/50 MCP tools operational (100% success rate) - Fastest command: 1ms (formats) - Unmeasurable: 0ms (migrate - too fast!) ## [3.0.3] - 2025-11-06 ### Added - **9 NEW Bundled Commands**: Eliminated ALL CLI dependencies! - `faf_sync` - Sync project.faf with project changes - `faf_bi_sync` - Bidirectional sync (project.faf ↔ CLAUDE.md) - `faf_formats` - TURBO-CAT format discovery - `faf_doctor` - Health check diagnostics - `faf_validate` - Schema validation - `faf_audit` - Comprehensive quality audit - `faf_update` - Update project.faf metadata - `faf_migrate` - Migrate legacy .faf to project.faf - `faf_innit` - British init command (innit bruv!) ### Fixed - **CRITICAL**: Users can now write CLAUDE.md without CLI (faf_bi_sync works!) - **CRITICAL**: Format discovery works without CLI (faf_formats works!) - All 50 MCP tools now work standalone - NO CLI DEPENDENCY ### Changed - Mk3 bundled engine now handles 12 commands (was 3): - init, score, auto (v3.0.0) - sync, bi-sync, formats, doctor, validate, audit, update, migrate, innit (v3.0.3) - Average test duration: 102.20ms (50/50 passing) ### Performance - 100% tool success rate - All categories verified working - Zero CLI fallback calls for bundled commands ### Breaking the 40% Barrier Users stuck at 40% AI-readiness (couldn't write CLAUDE.md) are now FREE! - Before: 16/25 working (64%) - blocked by CLI dependency - After: 25/25 working (100%) - fully standalone ## [3.0.2] - 2025-11-06 ### Fixed - **Claude Desktop Usability**: MCP now defaults to ~/Projects instead of constantly asking for directory paths - **Working Directory Logic**: Simplified `findBestWorkingDirectory()` to force the ~/Projects default - **Container Compatibility**: Explicitly avoids `/root/` to work seamlessly in Claude Desktop's container environment ### Changed - Engine adapter now creates ~/Projects directory if it doesn't exist (cross-platform) - Fallback hierarchy: FAF_WORKING_DIR env → MCP_WORKING_DIR env → ~/Projects (force) → home → /tmp - Better user experience: "we LIVE in /Projects" - no more path prompts ### Testing - 50/50 tools passing (100%) with new default - Average duration: 152.58ms - All categories verified working ## [3.0.1] - 2025-11-06 ### Fixed - **Mk3 Engine Adapter**: Fixed flag parsing bug where `--force` was treated as a directory path - **faf_auto Tool**: Now correctly passes `force` flag to bundled engine - **Type Definitions**: Added missing `force` property to `FafAutoArgs` interface ### Testing - Added comprehensive MCP tools test suite (test-mcp-tools.js) - All 5 core tools now passing: faf_init, faf_score, faf_auto, faf_status, faf_about - Verified file creation works correctly through MCP tool handlers ### Performance - Average duration: 20.6ms (5/5 tests passing) - 100% success rate on MCP tool operations ## [3.0.0] - 2025-11-06 🏎️ **Mk3 Championship Edition - Done Properly** ### Breaking Changes - **project.faf ONLY**: No longer supports legacy `.faf` (hidden) files - MCP now throws LOUD error if `.faf` detected with migration instructions - Users MUST run `faf migrate` to upgrade legacy projects ### What's New in v3.0.0 - **Mk3 Bundled Engine**: Core CLI code bundled directly (6-16x faster) - **ONE Standard**: project.faf everywhere (visible, one name, like package.json) - **LOUD Migration Errors**: Clear guidance when legacy `.faf` detected - **Championship Performance**: 24.7ms avg, 104 calls/sec throughput ### Added - project.faf as the ONLY supported filename (no legacy fallback) - Bundled engine for 3 commands: score, init, auto (no CLI dependency) - Loud error messages with migration instructions for legacy files - Simplified file discovery (no complex priority logic) ### Changed - `findFafFile()` now ONLY finds project.faf (throws error for `.faf`) - File discovery simplified (no tier system, no legacy support) - All internal references updated to project.faf standard ### Removed - Legacy `.faf` (hidden) file support - Multi-tier file discovery system - Deprecation warnings (replaced with hard errors) ### Migration Guide If upgrading from v2.x with `.faf` files: 1. Run `faf migrate` in your project directory 2. This renames `.faf` → `project.faf` (takes <1 second) 3. Then upgrade to MCP v3.0.0 ### Performance - Cold start: 154ms - Warmed average: 24.7ms (50% better than 50ms target) - Concurrent: 9.6ms per call - Memory: -1.88MB heap growth (zero leaks) ## [3.0.0-beta.2] - 2025-11-06 ### Documentation - Added comprehensive beta announcement to README with: - Clear explanation of Mk3 Bundled Engine - Compatibility table (no CLI → v2.7.3, with CLI → v3.0 beta) - Installation instructions for both scenarios - What works vs what doesn't (3 bundled, 13 need CLI) - Beta testing feedback request - Performance metrics and WJTTC certification ## [3.0.0-beta.1] - 2025-11-06 🏎️ **Mk3 Bundled Engine - Championship Performance Edition** ### Breaking Changes - MCP server now operates standalone - no longer requires global faf-cli installation - Bundled engine architecture replaces CLI process spawning for core commands ### Added - **Mk3 Bundled Engine**: Core CLI engine code now bundled directly into MCP package - 3 commands now use direct function calls (no CLI dependency): - `score` - FafCompiler scoring engine (24.7ms avg, 104 calls/sec throughput) - `init` - Project initialization (78ms avg) - `auto` - Combined init + score workflow (9-15ms avg) - New `/src/faf-core/` directory with 19 bundled files (624KB compiled): - Core compiler engine (FafCompiler - 922 lines) - Authoring (championship `faf-generator`) - Utilities (file operations, fafignore parsing, chrome detection) - Engines (FAB formats processor, DNA analyzer, context extractor, dependency TSA) - Programmatic APIs for score, init, and auto commands (return structured data, no console output) - Fallback mechanism: non-bundled commands still shell out to CLI if installed - Enhanced working directory detection with safety checks (prevents home/root directory execution) ### Changed - Performance improvements: 6-16x faster than CLI spawning for bundled commands - Cold start: 154ms (beating 200ms target) - Warmed average: 24.7ms (beating 50ms target by 50%) - Concurrent: 9.6ms per call (104 calls/second throughput) - TypeScript strict mode adjustments: disabled `noUnusedLocals` and `noUnusedParameters` for bundled CLI code - Engine adapter now routes to bundled functions before falling back to CLI ### Dependencies - Added `yaml` package (2.4.1) - only new production dependency needed ### Performance - Memory efficient: -1.88MB heap growth over 100 iterations (negative = no leak!) - Sub-10ms response times in concurrent mode - Zero crashes, zero hangs, zero race conditions ### Testing - WJTTC Championship Grade Certified (6/6 tests passed) - 100% test pass rate across stress tests - Backward compatible with existing workflows ### Documentation - BUNDLING_PLAN.md - Complete dependency tree and migration strategy - MK3_TEST_RESULTS.md - Architecture documentation and performance benchmarks - WJTTC-MK3-ENGINE-REPORT.md - championship test report ### Known Limitations - 13 commands still require CLI fallback (quick, sync, bi-sync, enhance, formats, validate, doctor, dna, log, update, recover, auth, audit) - Cold start 154ms (acceptable but could be optimized to <100ms in future) ### Migration Notes - Existing MCP users get automatic performance upgrade - No configuration changes required - Backward compatible with all existing workflows - CLI fallback ensures no functionality loss ### Compatibility Notice - **No CLI installed**: Use v2.7.3 (last fully standalone version) - **With CLI installed**: Use v2.8/2.9 or upgrade to v3.0.0-beta.1 (3 commands get 6-16x performance boost) - **Mk3 beta caveat**: 13 commands still require faf-cli fallback (will be bundled in Mk3 stable) ## [2.9.0] - 2025-11-06 ### Added - faf_install_skill tool for automatic installation of faf-expert skill to Claude Code - DROP | PASTE | CREATE user guidance when bare faf command called without directory - Smart Projects folder detection in faf_quick with projectName parameter (~/projects/ > ~/Projects/ > create ~/Projects/) ### Changed - Updated messaging from "THE JPEG for AI" to "Persistent Project Context" - Enhanced user onboarding experience with clear three-pathway guidance - faf_quick now supports projectName parameter for instant project creation in Projects folder ### Documentation - CLI synced with DROP | PASTE | CREATE messaging and Persistent Project Context terminology ## [2.8.1] - 2025-11-05 ### Fixed - README now includes "DROP or PASTE, Click & Go!" messaging - Removed "chatgpt" from package.json keywords (not supported) - Corrected test count from 79 to 57 throughout documentation ## [2.8.0] - 2025-11-05 ### Added - Tool Visibility System - Intelligent filtering to reduce cognitive load - 21 Core Tools (default) - Essential workflow tools shown by default - 30+ Advanced Tools (opt-in) - Expert-level tools via FAF_MCP_SHOW_ADVANCED env var - Tool categorization system (workflow, quality, intelligence, sync, ai, help, trust, file, utility, display) - Configuration priority system (ENV > config file > default) - Support for ~/.fafrc config file (JSON and key=value formats) - Claude Code skill (faf-expert) bundled with package - Comprehensive visibility test suite (22 new tests) ### Changed - Default tool count reduced from 51 to 21 (59% reduction in cognitive load) - Tool filtering performance <10ms (5x better than 50ms target) - Professional console output (silent operation, no clutter) - README updated with v2.8.0 features and Claude Code skill installation ### Performance - Sub-10ms tool filtering for 56 tools - Zero regressions in existing functionality - 79 total tests passing (57 existing + 22 new) ### Testing - WJTTC Gold Certified - Championship testing standards applied - Complete test report available ## [2.7.3] - 2025-11-02 ### Fixed - Corrected project.faf screenshot CDN URL to use claude-faf-mcp package asset - Image now displays correctly on npmjs.com README ## [2.7.2] - 2025-10-31 ### Changed - Updated package.json description to highlight IANA registration - Enhanced README with IANA registration messaging throughout - Added visual "See It In Action" section showing project.faf placement - Improved CLI vs MCP clarity section with better formatting - Expanded Major Milestones timeline with complete chronological dates - Updated download statistics to current metrics (4,700 total, 598/week) - Changed platform validation messaging to "Quadruple Validation" ### Documentation - Added screenshot showing project.faf between package.json and README.md - Improved milestone presentation with all key dates from Aug 2024 to Oct 2025 - Enhanced IANA registration visibility across README sections ## [2.7.1] - 2025-10-30 ### Fixed - Added missing screenshot asset (project-faf-screenshot.png) to npm package - Screenshot now displays correctly on npmjs.com package page ## [2.7.0] - 2025-10-30 ### Added - project.faf as the new standard for all projects - File discovery utility supporting both project.faf and legacy .faf - NPM badges in README (version, downloads, license) - What's New section showcasing project.faf visibility ### Changed - New projects now create project.faf (instead of hidden .faf) - All MCP tools support both project.faf and legacy .faf files - README updated with simplified v2.7.0 announcement - Updated 18 locations across codebase for new standard ### Fixed - File discovery now handles all .faf filename variations - EISDIR protection for edge cases ### Testing - Championship-grade stress testing completed - WJTTC Gold Certified - Backward compatibility verified with legacy .faf files ### Migration - Existing .faf files continue to work perfectly - Use faf migrate (CLI v3.1.0) to upgrade to project.faf - Coordinated release with faf-cli v3.1.0 ## [2.6.7] - 2025-10-25 ### Fixed - Corrected Homebrew installation command from `Wolfe-Jam/tap` to `wolfe-jam/faf` - Fixed tap name in both installation sections of README ### Added - Created Homebrew formula for claude-faf-mcp in wolfe-jam/faf tap - Homebrew installation now fully functional and verified ## [2.6.6] - 2025-10-25 ### Changed - Redesigned README for professional clarity and credibility - Removed decorative emoji and formatting from meta-content - Emphasized "persistent project context" in the registry listing - Clarified format-driven architecture (format-first, not tools-first) ### Added - "Scoring System Experience" section with product screenshot - Homebrew installation option (brew install Wolfe-Jam/tap/claude-faf-mcp) - Strengthened positioning: "first and only persistent project context server" ### Documentation - Format-driven architecture now leads value proposition - Distinguished .faf from tools.md and CLAUDE.md - Professional, noise-free README structure ## [2.6.3] - 2025-10-20 ### Fixed - Corrected typo in README title: "Persistant" → "Persistent" ## [2.6.2] - 2025-10-20 ### Changed - README version management - DRY principle implementation - Removed duplicate version references from Technical Specs section - Version now appears once in title for simplified maintenance ### Documentation - Version only in title (single source of truth) and historical changelog entries - Streamlined documentation for easier version updates ## [2.6.1] - 2025-10-16 ☑️ **MCP Registry publication** (historical: `io.github.Wolfe-Jam/claude-faf-mcp`, since superseded by `one.faf/claude-faf-mcp`) ### Added - server.json configuration for the MCP Registry listing - A one-line community entry in the modelcontextprotocol/servers README ([PR #2759](https://github.com/modelcontextprotocol/servers/pull/2759), merged 2025-10-17). Historical: that README no longer lists it. ### Changed - mcpName field updated with correct capitalization format (io.github.Wolfe-Jam/claude-faf-mcp) - First .faf format server in the MCP Registry ### Registry Status - ☑️ Published to the MCP Registry (registry.modelcontextprotocol.io) - Correction (6.0.0): this entry used to say the listing was validated by Anthropic's engineering team. It was a community README entry; no Anthropic review or endorsement is claimed. - ☑️ Available for one-click installation in MCP-compatible hosts ## [2.6.0] - 2025-10-14 ✪ **Post-Evaluation Release (94.4/100 Gold Standard)** ### Added - Type-safe tool handlers with proper TypeScript definitions - Community contribution framework (templates, guidelines, funding) - WJTTC Comprehensive Evaluation Report (94.4/100 Gold Standard) ### Changed - Repository cleanup: Removed 17K+ lines of legacy docs - Improved TypeScript strict mode compliance across all handlers ### Developer Experience - Better IDE autocomplete with proper types - Cleaner codebase for contributors - Professional community standards ## [2.5.5] - 2025-10-13 ### Added - GitHub Pages documentation hub at https://wolfe-jam.github.io/claude-faf-mcp/ - GitHub Discussions for community engagement - Issue templates (bug report & feature request) with YAML forms - CONTRIBUTING.md with development guide and TypeScript strict mode requirements - REDDIT_POST.md for r/ClaudeAI announcement - Comprehensive evaluation report (94.4/100 Gold Standard) - Enhanced NPM keywords (59 strategic terms) for better discoverability - Brand keywords: faf-innit, fast-af, wolfejam, ai-commit, context-mirroring, c-mirror - 12 professional badges in README (NPM, downloads, TypeScript, performance, evaluation) ### Changed - Updated .gitignore to allow docs/*.md files while keeping internal docs private - Enhanced README with Championship Score Card and Orange Smiley branding - Improved package.json description for cleaner NPM presence ### Fixed - Official Orange Smiley 🧡 brand icon properly integrated (commit message corrected from history) - Image URLs now use jsdelivr CDN for reliable display across npm, GitHub, and docs ## [2.5.4] - 2025-10-12 ### Fixed - Image display issues on npmjs.com package page using GitHub raw URLs ## [2.5.3] - 2025-10-11 ### Added - Championship branding complete with Orange Smiley visual identity - Score card screenshot showing actual terminal output ## [2.5.2] - 2025-10-10 ### Added - Visual Championship Experience on NPM package page - Orange Smiley branding with complete visual identity - Championship Score Card screenshot in scoring section ### Changed - Professional presentation and polish across all documentation ## [2.5.1] - 2025-10-09 ### Changed - Championship README with Trophy section leading for immediate impact - Optimized package description for cleaner NPM presence - Professional structure with scannable, modern layout ## [2.5.0] - 2025-10-08 ### Added - **Championship Edition** - 7-tier medal system for AI-readiness scoring - Visual progress bars in terminal output - Milestone tracking with next-level guidance - Enhanced scoring algorithm for better project analysis ### Changed - Scoring system now uses podium tiers: - ✪ Trophy (100%) - Perfect AI|HUMAN balance - 🥇 Gold (99%) - Gold standard - 🥈 Silver (95-98%) - Excellence - 🥉 Bronze (85-94%) - Production ready - 🟢 Green (70-84%) - Good foundation - 🟡 Yellow (55-69%) - Getting there - 🔴 Red (0-54%) - Needs attention ## [2.4.0] - 2025-09-30 ### Added - Enhanced MCP tools for better Claude Desktop integration - Improved error handling and validation ## [2.3.0] - 2025-09-25 ### Added - Bi-directional sync between .faf and CLAUDE.md files - Performance optimizations (<11ms target achieved) ## [2.2.0] - 2025-09-20 ### Added - Complete TypeScript strict mode implementation - Comprehensive test suite (730 C.O.R.E tests) - Zero-dependency architecture (MCP SDK only) ## [2.1.0] - 2025-09-15 ### Added - 33+ MCP tools for complete project management - Auto-detection and project analysis - File operations (read, write, search, list) ## [2.0.0] - 2025-09-10 ### Added - Initial MCP server implementation - .faf format support for Claude Desktop - Core tools: faf_init, faf_auto, faf_score, faf_status ### Changed - Migrated from CLI-only to MCP server architecture ## [1.0.0] - 2025-09-01 ### Added - Initial release of .faf format - Project DNA concept for AI context - Basic scoring system --- ## Legend - **Added** - New features - **Changed** - Changes in existing functionality - **Deprecated** - Soon-to-be removed features - **Removed** - Removed features - **Fixed** - Bug fixes - **Security** - Vulnerability fixes --- **Made with 🧡 by wolfejam.dev**