v8.2.0 — The Ladder Edition

One ladder for every card: agent.fafa builds the plain cards, and project.faf adds FAF's context. 2160 tests.

Changed

• Cards follow one ladder: BETTER is .fafa, BEST is project.faf (#149). The .fafa is the source of every card: an agent.fafa alone gives the plain cards its endpoints allow — the A2A card (an A2A endpoint), the MCP Server Card (a remote MCP URL), the registry server.json identity (a remote or a package), the AI Catalog and ARD — with no FAF context and nothing pointing at a project.faf. Add project.faf and the same cards carry FAF's context (the A2A extension, the Server Card's and server.json's _meta). A card's identity comes from the .fafa at both rungs. faf card init, faf cards and --help name the steps BETTER and BEST (8.1.0 called them Good and Better).
• The pack projector (projectPack, buildPack) writes the same cards as faf cards. A new faf option adds FAF's context (BEST); the .fafa is listed in the AI Catalog and ARD by default (listFafa: false leaves it out); an A2A row only when the .fafa names an A2A door. faf cards lists the Server Card in the catalog when it writes one.
• An MCP repo with project.faf and no MCP endpoint in its .fafa gets its Server Card and registry identity from project.faf, as faf server-card writes them.
• faf cards in a folder with neither file names faf card init, where cards start (it said only faf init).
• An existing server.json keeps the name it was published under. The registry identity now comes from the .fafa; when that gives a different name than server.json carries, faf cards refuses to rename it (exit 1, the file left as it is), because a rename moves the next registry publish to another namespace. --force renames it.
• With an MCP endpoint in the .fafa, the Server Card is built from the .fafa (8.1 built it from project.faf). faf owns the Server Card it wrote, so the first faf cards after upgrading rewrites it from the .fafa.
• Library: ProjectedCards.block, the registry entry's _meta and ServerJsonIdentity.meta are optional (absent at BETTER, with no project.faf). faf cards --check prints no block key at BETTER.

Fixed

• A package identifier is never read as an option. An npm name can no longer start with - (--yes, -rf were accepted); a PyPI name must follow PyPI's name rule; any other registry's identifier must start with a letter or digit and have no spaces.
• With no project.faf, a second faf cards rewrote the AI Catalog and ARD with a new updatedAt. It now keeps the stamp, so a run that changes nothing writes nothing.
• faf card init with an npm package never offers the registry step without a server.json to patch.
• faf card init and buildPack refuse what a card must not carry: a "where it runs" that is not an http(s) URL (javascript:, ftp:, file: used to become an npm package), an npm package that is not an npm package name (rm -rf / used to become the MCP server's stdio command), and a protocol other than a2a or mcp from flags.

Install

npm install -g faf-cli@8.2.0
# or: npx faf-cli · brew install wolfe-jam/faf/faf-cli

Commits since v8.1.1

• release: 8.2.0 — The Ladder Edition (#157) (0b3722f)
• ci(windows): a hung test run retries once; test git calls time out (#156) (dd48f30)
• fix: 8.2.0 review — keep a published server.json name; no option-like package ids (#155) (727dc5b)
• ci(windows): time out a hung test run (15 min job, 10 min test step) (#154) (54cb46c)
• docs(readme): live FAF downloads badge, not a hard-coded count (#153) (0b05834)
• ci: run the full test suite on Windows (#152) (ee51dff)
• feat(cards): one ladder — BETTER is .fafa, BEST is project.faf (8.2.0) (#149) (c9fe442)
• ci: a real pre-ship Windows gate (#150) (bea34fc)

FAF defines. AGENTS.md instructs. AI codes.