mcp-context-card 0.5.1 → 0.6.0

package/.well-known/ai-catalog.json

@@ -18,7 +18,7 @@
       "displayName": "mcp-context-card — persistent memory (.fafm)",
       "type": "application/vnd.fafm+yaml",
       "mediaType": "application/vnd.fafm+yaml",
-      "description": "Cross-session memory — 3 fact(s), profile \"knowledge\". Recall survives a process restart. No de-facto standard for this concern yet.",
+      "description": "Cross-session memory — 4 fact(s), profile \"knowledge\". Recall survives a process restart. No de-facto standard for this concern yet.",
       "url": "./project.fafm",
       "_meta": {
         "io.github.wolfe-jam.mcp-context-card/iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml"
@@ -29,7 +29,7 @@
       "displayName": "mcp-context-card — agent identity (.fafa)",
       "type": "application/vnd.fafa+yaml",
       "mediaType": "application/vnd.fafa+yaml",
-      "description": "An MCP server that makes a project's context (AGENTS.md), cross-session memory, and identity discoverable to any MCP client, through the Server Card _meta block and a self-published ai-catalog.json.",
+      "description": "The essential MCP components for a project's context (AGENTS.md), cross-session memory, and identity — a base MCP on its own, or a drop-in extension for any existing MCP server, discoverable through the Server Card _meta block and a self-published ai-catalog.json.",
       "url": "./.well-known/fafa",
       "_meta": {
         "io.github.wolfe-jam.mcp-context-card/iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml"

package/.well-known/fafa

@@ -9,10 +9,11 @@ agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
   vendor: "io.github.wolfe-jam"
-  version: "0.5.1"
+  version: "0.6.0"
   description: >-
-    An MCP server that makes a project's context (AGENTS.md), cross-session
-    memory, and identity discoverable to any MCP client, through the Server
-    Card _meta block and a self-published ai-catalog.json.
+    The essential MCP components for a project's context (AGENTS.md),
+    cross-session memory, and identity — a base MCP on its own, or a
+    drop-in extension for any existing MCP server, discoverable through the
+    Server Card _meta block and a self-published ai-catalog.json.
   status: "published"
   license: "MIT"

package/AGENTS.md

@@ -1,9 +1,10 @@
 # AGENTS.md
 
-`mcp-context-card` is an MCP server that makes a project's **context**
-(this file), **memory**, and **identity** discoverable to any MCP client —
-through the two surfaces already in the ecosystem: the Server Card `_meta`
-block and `ai-catalog.json` sibling entries.
+`mcp-context-card` is the essential MCP server for a project's **context**
+(this file), **memory**, and **identity** — usable as your base MCP, or
+dropped into any existing MCP server as an extension. Discoverable to any
+MCP client through the two surfaces already in the ecosystem: the Server
+Card `_meta` block and `ai-catalog.json` sibling entries.
 
 `read_agents_md` serves this file, section by section, over the same MCP
 connection.
@@ -40,14 +41,14 @@ Windows for every push and PR to `main` (`.github/workflows/ci.yml`).
 |---|---|
 | `src/server.ts` | the MCP server — the nine tools + the Server Card resource |
 | `src/agents-md.ts` | reads and section-splits this file |
-| `src/author.ts` | `author_agents_md` — wraps `agents-md-facts` (the AGENTS.md authoring engine) |
+| `src/author.ts` | `author_agents_md` — BETTER via `agents-md-facts`, BEST when `project.faf` exists |
 | `src/md.ts` | a minimal dependency-free Markdown → HTML renderer |
 | `src/render-card.ts` | the card — identity + this file + memory + discovery, as one HTML page |
 | `src/memory.ts` → `src/faf/parse-fafm.ts` | file-backed `remember` / `recall` / `forget` |
 | `src/identity.ts` | `whoami` (`.fafa` → `package.json` fallback) + the `_meta` context block |
 | `src/catalog-gen.ts` | writes `.well-known/ai-catalog.json` from the same three sources |
 | `src/transport/http.ts` | the stateless Streamable HTTP app (Hono) |
-| `src/bin.ts` | the entry point (`resolveLaunch`) — `stdio` · `--http` · `card` |
+| `src/bin.ts` | the entry point (`resolveLaunch`) — `stdio` · `--http` · `card` · `--help` · `--version` |
 | `src/faf/parse-fafm.ts` · `parse-fafa.ts` | the `.fafm` / `.fafa` parsers |
 
 ## Conventions
@@ -80,6 +81,7 @@ plus `npm run catalog:check` and `npm run card:check` clean if you touched
 
 ## Authoring this file
 
-`AGENTS.md` here is maintained by hand. It can also be generated from the
-repo's `project.faf` with `faf export --agents` — the server doesn't care how
-the file was authored, only that it's valid Markdown.
+`AGENTS.md` here is maintained by hand. The `author_agents_md` tool (or
+`faf export --agents`) would draft a BEST version straight from this repo's
+own `project.faf` plus its detected facts — the server doesn't care how the
+file was authored, only that it's valid Markdown.

package/CHANGELOG.md

@@ -2,6 +2,92 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 0.6.0
+
+The README as a hero, not just a description. Everything visual this repo
+claims is now backed by a real screenshot from the actual rendered card —
+nothing hand-drawn, nothing mocked up.
+
+- **The card leads the README** — a side-by-side "Light | Dark" table right
+  at the top, instead of one fixed screenshot. Shows the real range to
+  every viewer regardless of their own GitHub theme.
+- **Each of the three concerns gets its own proof** — context, memory, and
+  identity are each followed by a real crop from the card: the `AGENTS.md`
+  section + the `read_agents_md` line, an actual tagged and verified
+  memory fact, and the title + pills.
+- **"Pick one"** — a table right after the hero: add an `AGENTS.md`,
+  improve one to BEST, get a new MCP server base, or extend an MCP you
+  already run. Replaces the old "Who it's for" table.
+- The dark card no longer blends into GitHub's own dark mode — added a
+  visible ring plus a soft accent-tinted glow so it reads as a distinct
+  card regardless of backdrop.
+- **GitHub Pages, live** — `wolfe-jam.github.io/mcp-context-card/` serves
+  the card in auto/light/dark. The GitHub repo's own "Website" field links
+  there. `package.json`'s `homepage` is a different field and stays on the
+  repo itself — that's where install steps and the tools table live, not a
+  bare rendered card.
+- "Vendor-free," not "Not tied to FAF" — dropped a defensive clause nobody
+  needed, and reworded the vendor-boundary line to state the property
+  without naming a vendor to disclaim against.
+- An external README review caught four real gaps, fixed before publish:
+  the identity line said "agent card" — reworded to **Server Card**, the
+  term this repo already documents and owns (SEP‑2127), so it can't be read
+  as A2A's own, distinctly-specified AgentCard; the "Wire it into a host"
+  example now states the Node ≥22 requirement and cross-references the
+  documented `npx` `ENOENT` fix (Cursor) instead of leaving it undiscoverable
+  until WIRING; `docs/WIRING.md`'s `list_agents_md_sections` example showed
+  `sections: 9` — the real, parser-verified count is 10 (it includes the
+  `AGENTS.md` H1, not just its nine `##` headings).
+- `docs/MECHANISMS.md` states the A2A position: Server Card is what this
+  server has. A2A's AgentCard is a different thing — a live agent, an
+  endpoint, skills, auth. We're ready for A2A: the same `.fafa` source
+  publishes a real AgentCard alongside it the day a project here is
+  reachable over one, not a reshape of `.fafa` itself.
+- Bumped straight to 0.6.0 — 0.5.3 was committed but never published;
+  no reason to leave a changelog entry for a version nobody received.
+
+No functional change — README, docs, and card assets only. 102 tests,
+typecheck/build/demo clean, `card:check` + `catalog:check` green.
+
+## 0.5.2
+
+The soak, closed out. Two Cursor host checks — a real bug found and fixed, a
+real gap found and fixed, both confirmed against a real independent MCP host
+on the current build.
+
+- **`author_agents_md` now authors BEST, not just BETTER, when it can.**
+  BETTER is the facts-only draft from `agents-md-facts` (build/test
+  commands, entry points, conventions — nothing invented). **BEST** is that
+  plus a `## Project` section ahead of it — goal, who it's for, why, and a
+  "start here" file list — read straight from `project.faf` when one
+  exists. This is the point of the app: give the best AGENTS.md the
+  project has the material for, not a fixed floor. The tool's response
+  names the tier it produced.
+- **Fix:** `remember` on a project that had never had a `project.fafm`
+  threw `ENOENT` instead of starting one — the single most common
+  first-use case. `remember` now creates a fresh `.fafm` on first write;
+  `forget` / `parseFafm` were already safe and are unchanged. A real
+  child-process e2e test (a cold root, two separate OS processes) makes
+  this a permanent regression guard, not just a fix.
+- `docs/WIRING.md`: a note on hosts whose spawn `PATH` lacks `npx`
+  (`spawn npx ENOENT`, observed in Cursor) — point `command` at `node` +
+  the installed `dist/bin.js` instead.
+- **The README / AGENTS.md / `project.faf` / manifest reframe** — dropped
+  "Small, MIT…" / "a piece, not the toolbox" for the real positioning:
+  essential context, memory, and identity components, usable as a base MCP
+  on their own, or a drop-in extension for any existing MCP server.
+- An accuracy pass across every shipped surface, caught by re-reading
+  rather than by any check: stale test/tool counts (README, CHANGELOG,
+  and `project.faf`'s own `human_context.what` — it undercounted its own
+  tools), 3-release-old version strings sitting in two hand-shown examples
+  (`examples/README.md`, `docs/MECHANISMS.md`), a pre-rename
+  docker-compose service name (`trinity` → `context-card`), an internal
+  function that still carried the pre-rename product name (`trinityMeta` →
+  `serverCardMeta` — not a public export). `project.faf` itself rechecked
+  against the current architecture (`tech_stack`, `key_files`, `cicd`).
+- 102 tests, coverage gate held, `card:check` / `catalog:check` green,
+  `faf-cli check`: ✪ Trophy 100%, 15/15 slots.
+
 ## 0.5.1
 
 First-hour ergonomics and wording, from the 0.5.0 soak.
@@ -19,14 +105,6 @@ First-hour ergonomics and wording, from the 0.5.0 soak.
   to the LICENSE holder.
 - `.well-known/fafa` — `vendor: io.github.wolfe-jam`, `status: published`
   (were both `reference`). Shows in `whoami` and as the card's pills.
-- **Fix:** `remember` on a project that has never had a `project.fafm` threw
-  `ENOENT` instead of starting one — the single most common first-use case.
-  Found by a real host check (Cursor, 2026-09-04). `remember` now creates a
-  fresh `.fafm` on first write; `forget` and `parseFafm` were already safe on
-  a missing file and are unchanged in behaviour.
-- `docs/WIRING.md`: a note on hosts whose spawn `PATH` lacks `npx`
-  (`spawn npx ENOENT`, observed in Cursor) — point `command` at `node` +
-  the installed `dist/bin.js` instead.
 
 ## 0.5.0
 
@@ -73,7 +151,7 @@ tested server.
 
 ### Engineering
 
-- 88 tests across Linux / macOS / Windows, coverage-gated
+- 90 tests across Linux / macOS / Windows, coverage-gated
   (lines 90 / funcs 85 / branches 80, `src/` only). A real `child_process`
   spawn proves memory across a genuine process boundary; stdio/HTTP
   tool-surface parity is asserted.

package/README.md

@@ -3,44 +3,73 @@
 [![CI](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-An MCP server that makes a project's context, memory, and identity discoverable
-to any MCP client — and renders them as one card you can read.
+**Get one. Or add it to yours.** The essential MCP server for a project's
+context, memory, and identity — discoverable to any MCP client, and
+rendered as one card you can read.
 
-- **context** — the project's `AGENTS.md`, served whole or one section at a time
-- **memory** — facts that persist across sessions, in a file
-- **identity** — what this server is, from its own agent card
+| Light | Dark |
+|---|---|
+| ![the context card, light theme](./docs/img/card-light.png) | ![the context card, dark theme](./docs/img/card-dark.png) |
+
+**context** — the project's `AGENTS.md`, served whole or one section at a time.
+
+![the card's context section — AGENTS.md, section nav, read_agents_md](./docs/img/card-context.png)
+
+**memory** — facts that persist across sessions, in a file.
+
+![the card's memory section — a real, tagged, verified fact](./docs/img/card-memory.png)
+
+**identity** — what this server is, from its own Server Card.
+
+![the card's identity — name and pills](./docs/img/card-identity.png)
 
 Discovery goes through two surfaces already in the ecosystem: the Server Card
 `_meta` block and `ai-catalog.json` sibling entries.
 
-## What it is / what it is not
+## Pick one
+
+| You want to… | |
+|---|---|
+| **Add an `AGENTS.md`** — you don't have one | `author_agents_md` drafts one from your repo's real facts |
+| **Improve an `AGENTS.md`** — you have one, make it the best it can be | the same tool, automatically — drop in a `project.faf` and it upgrades to BEST: goal, who it's for, why |
+| **Get a new MCP server base** — context, memory, identity, wired | stand this up as-is; a host has all three before you write a tool of your own |
+| **Improve your MCP with context, memory, ID** — you already run one | run it alongside your existing server; nothing to migrate, it composes |
+
+## A base MCP — or an extension for any other
 
-**It is** — an MCP server for a project's `AGENTS.md`, memory, and identity: nine
-tools, two discovery surfaces (Server Card `_meta`, `ai-catalog.json`), and a
-rendered [card](#the-card). Small, MIT — read it, `npx` it, or fork it.
+Context, memory, and identity are essential — every MCP host needs an agent
+that knows a project's instructions, remembers facts across sessions, and can
+say what it is. `mcp-context-card` is those three, done once:
 
-**It is not**
+- **Stand it up as your base MCP.** Point a host at it and an agent already
+  has `AGENTS.md` served section‑by‑section, `remember` / `recall` / `forget`
+  memory that survives a restart, and a `whoami` identity — before a single
+  tool of your own is written.
+- **Or extend any existing MCP with it.** Run it alongside a server you
+  already have — filesystem, git, a database, your own — and that agent
+  gains context, memory, and identity discovery it didn't have. Nothing to
+  migrate; it composes.
 
-- a framework or a platform — three concerns, nothing more
-- a file, shell, or search tool — it never touches your files or runs commands
-- tied to FAF — context is plain Markdown (`AGENTS.md`); the memory and identity
-  formats are swappable examples
+Nine tools, two discovery surfaces already in the ecosystem (Server Card
+`_meta`, `ai-catalog.json`), and a rendered [card](#the-card). MIT, on npm.
 
 It composes:
 
 - **serve · discover · render** — this server
-- **author · keep true** — [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) (the `author_agents_md` tool wraps it)
+- **author BETTER, keep true** — [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) (`author_agents_md` wraps it for the facts layer; adds a BEST layer of its own from `project.faf` when one exists)
 - **files · shell · git** — [`server-filesystem`](https://github.com/modelcontextprotocol/servers), [`server-git`](https://github.com/modelcontextprotocol/servers) / github‑mcp‑server, your test runner's MCP
 
-A piece, not the toolbox.
+Vendor-free — context is plain Markdown (`AGENTS.md`); the memory and
+identity formats are swappable examples. It reads and writes only its own
+three files (`AGENTS.md`, `project.fafm`, `.well-known/fafa`) — no general
+file access, no shell, no search.
 
 ## The card
 
-![the context card](./docs/img/card.png)
-
-The same three sources render as one self‑contained HTML page — identity,
-`AGENTS.md`, memory, and how a machine fetches it. The view for people:
-screenshot it, drop it in a PR, put it on a status page.
+The screenshot at the top of this page is exactly this — the same three
+sources rendered as one self‑contained HTML page: identity, `AGENTS.md`,
+memory, and how a machine fetches it. The view for people: screenshot it,
+drop it in a PR, put it on a status page.
 
 ```
 GET /card                      # live, on the HTTP transport
@@ -49,36 +78,30 @@ npx mcp-context-card card       # or:  npm run card  →  docs/card.html
 ```
 
 Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
-[docs/card.html](./docs/card.html) is this repo's, rendered.
-
-## Who it's for
-
-| You want… | Reach for |
-|---|---|
-| an `AGENTS.md` and you don't have one | `author_agents_md` — or [`npx agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) |
-| your agent to pull *one* `AGENTS.md` section on demand, not the whole file | `read_agents_md` · `list_agents_md_sections` |
-| a persistent notepad for your agent — survives restarts, no setup | `remember` · `recall` · `forget` |
-| a shareable view of what your MCP server exposes to agents | `GET /card` · `npx mcp-context-card card` |
-| the two‑surface discovery pattern to copy into your own server | read `src/` |
+This repo's own card, live: [auto](https://wolfe-jam.github.io/mcp-context-card/) ·
+[light](https://wolfe-jam.github.io/mcp-context-card/card-light.html) ·
+[dark](https://wolfe-jam.github.io/mcp-context-card/card-dark.html)
+(all in the AAIF accent shown here — pass any hex to change it).
 
 ## Add it to your setup
 
 ### No `AGENTS.md` yet?
 
-The `author_agents_md` tool authors one from your repo's facts — real
-build/test commands, entry points, toolchain conventions — and hands the agent
-the draft. It's a thin wrapper over
-[`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts); to author or
-keep one true outside a session:
+The `author_agents_md` tool authors one — **BETTER** from your repo's real
+facts (build/test commands, entry points, toolchain conventions, via
+[`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts)), or
+**BEST** when a `project.faf` exists: the same facts, plus its structured
+goal, who it's for, and why, as a section ahead of them. Nothing to
+configure — the tier follows what's actually there.
+([The ladder this follows.](https://github.com/Wolfe-Jam/agents-md-facts/blob/main/docs/BETTER-BEST.md))
+
+To author or keep the facts layer true outside a session:
 
 ```bash
 npx agents-md-facts          # author / refresh AGENTS.md
 npx agents-md-facts --check  # fail if missing or stale (CI, pre-commit)
 ```
 
-A `project.faf` is the next rung — a structured source that refreshes the file.
-Short model: [`agents-md-facts/docs/BETTER-BEST.md`](https://github.com/Wolfe-Jam/agents-md-facts/blob/main/docs/BETTER-BEST.md).
-
 ### See the card
 
 One command, no host, no config:
@@ -105,9 +128,18 @@ Claude Desktop, Cursor, or any stdio host:
 
 `MCP_CONTEXT_CARD_ROOT` points at the directory with your `AGENTS.md`. The
 memory tools work with or without it; identity is optional. Over HTTP instead:
-`PORT=8080 npx mcp-context-card`. Full wiring is in
-[docs/WIRING.md](./docs/WIRING.md); transport choice in
-[docs/TRANSPORT.md](./docs/TRANSPORT.md).
+`PORT=8080 npx mcp-context-card`. Requires Node ≥22.
+
+If `command: "npx"` fails to spawn (`spawn npx ENOENT` — seen on Cursor, whose
+host process doesn't inherit a shell `PATH`), point `command` at `node` and
+the installed `dist/bin.js` instead — see
+[docs/WIRING.md](./docs/WIRING.md#1-running-it-in-a-host). Transport choice is
+in [docs/TRANSPORT.md](./docs/TRANSPORT.md).
+
+Extending an MCP you already run: most hosts accept more than one
+`mcpServers` entry — add `context-card` alongside `server-filesystem`,
+`server-git`, or your own, and every agent in that host gains context,
+memory, and identity discovery without anything else changing.
 
 ## Why
 
@@ -137,7 +169,7 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
 
 | Tool | What it's for |
 |---|---|
-| `author_agents_md` | draft an `AGENTS.md` from the repo's facts (via `agents-md-facts`) — a managed block, ready to drop in |
+| `author_agents_md` | draft an `AGENTS.md` — BETTER from the repo's facts (via `agents-md-facts`), BEST when a `project.faf` exists — ready to drop in |
 | `read_agents_md` | return the project's `AGENTS.md` — whole, or one section by heading |
 | `list_agents_md_sections` | the headings, so a client pulls one section instead of the whole file |
 | `remember` | write a fact that will still be there next session |
@@ -159,9 +191,10 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-88 tests on Linux, macOS, and Windows, coverage‑gated in CI. One spawns a real
-child process and checks a remembered fact survives the restart; another checks
-the stdio and HTTP tool surfaces match.
+102 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
+child process and check a remembered fact survives the restart — one against
+an existing `project.fafm`, one starting from a project that has never had
+one; another checks the stdio and HTTP tool surfaces match.
 
 ## Layout
 
@@ -169,14 +202,14 @@ the stdio and HTTP tool surfaces match.
 |---|---|
 | `src/server.ts` | the nine tools + the Server Card resource |
 | `src/agents-md.ts` | reads and section‑splits `AGENTS.md` |
-| `src/author.ts` | `author_agents_md` — wraps [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) |
+| `src/author.ts` | `author_agents_md` — BETTER via [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts), BEST when `project.faf` exists |
 | `src/md.ts` | a minimal dependency‑free Markdown → HTML renderer |
 | `src/render-card.ts` | the card — identity + `AGENTS.md` + memory + discovery, as one HTML page |
 | `src/memory.ts` | file‑backed `remember` / `recall` / `forget` |
 | `src/identity.ts` | `whoami` (`.fafa` → `package.json` fallback) + the `_meta` block |
 | `src/catalog-gen.ts` | writes `ai-catalog.json` from the same three sources |
 | `src/transport/http.ts` | the stateless Streamable HTTP app (Hono) |
-| `src/bin.ts` | the entry point — `stdio` · `--http` · `card` |
+| `src/bin.ts` | the entry point — `stdio` · `--http` · `card` · `--help` · `--version` |
 
 ## Related
 

package/dist/author.d.ts

@@ -1,11 +1,20 @@
 /** The markers `agents-md-facts` uses to bound its managed block. */
 export declare const BLOCK_START = "<!-- agents:from-facts:start -->";
 export declare const BLOCK_END = "<!-- agents:from-facts:end -->";
+/** The markers this file uses to bound the project.faf-sourced intent block. */
+export declare const FAF_BLOCK_START = "<!-- context:from-faf:start -->";
+export declare const FAF_BLOCK_END = "<!-- context:from-faf:end -->";
 export interface Authored {
-    /** the AGENTS.md text — a managed block, ready to drop in */
+    /** the AGENTS.md text — one or two managed blocks, ready to drop in */
     markdown: string;
     /** whether an AGENTS.md already exists at the target */
     exists: boolean;
+    /** which tier was authored — BEST only when a readable project.faf was found */
+    tier: "better" | "best";
 }
-/** Author a managed AGENTS.md block for `root`, from its repo facts. */
+/**
+ * Author AGENTS.md for `root`. BETTER from repo facts alone; BEST — facts
+ * plus the project.faf intent block, ahead of it — when a project.faf with
+ * real content exists.
+ */
 export declare function authorAgentsMd(root: string): Authored;

package/dist/author.js

@@ -1,27 +1,86 @@
 /**
- * author — author an AGENTS.md for a project from its repo facts.
+ * author — author an AGENTS.md for a project, at the tier the project earns.
  *
- * The engine is `agents-md-facts` (a published, standalone tool, AGENTS.md
- * BETTER tier): it detects real build/test commands, entry points, toolchain
- * conventions and nothing invented. This wraps it in the managed-block
- * markers so `agents-md-facts --check` (or its Action / pre-commit hook) can
- * keep the result true afterwards.
+ * BETTER: the engine is `agents-md-facts` (a published, standalone tool) —
+ * it detects real build/test commands, entry points, toolchain conventions
+ * and nothing invented. Every project gets at least this.
  *
- * A `project.faf` is the BEST tier — the same discipline plus a structured
- * source of truth that refreshes the file. This wrapper stays at BETTER; the
- * README points at the BEST path.
+ * BEST: when `project.faf` exists, its structured intent — goal, who it's
+ * for, why it exists, the files that matter most — is real, human-authored
+ * truth that no amount of repo-scanning can detect. A project with a
+ * `project.faf` gets BOTH: the facts block, unchanged, plus this intent as
+ * its own managed block ahead of it. This is the whole point of the app:
+ * give the BEST AGENTS.md when the structured source to build it from is
+ * sitting right there.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { parse } from "yaml";
 import { authorAgentsMd as authorBlock, buildRepoContext } from "agents-md-facts";
 /** The markers `agents-md-facts` uses to bound its managed block. */
 export const BLOCK_START = "<!-- agents:from-facts:start -->";
 export const BLOCK_END = "<!-- agents:from-facts:end -->";
-/** Author a managed AGENTS.md block for `root`, from its repo facts. */
+/** The markers this file uses to bound the project.faf-sourced intent block. */
+export const FAF_BLOCK_START = "<!-- context:from-faf:start -->";
+export const FAF_BLOCK_END = "<!-- context:from-faf:end -->";
+/** Read the structured intent out of `root`'s project.faf, or null if there isn't one to read. */
+function readFafIntent(root) {
+    const path = join(root, "project.faf");
+    if (!existsSync(path))
+        return null;
+    try {
+        const doc = (parse(readFileSync(path, "utf8")) ?? {});
+        const project = doc.project ?? {};
+        const humanContext = doc.human_context ?? {};
+        const intent = {
+            name: str(project.name),
+            goal: str(project.goal),
+            who: str(humanContext.who),
+            why: str(humanContext.why),
+            keyFiles: Array.isArray(doc.key_files) ? doc.key_files.map(String).filter(Boolean) : undefined,
+        };
+        // A .faf with nothing usable in it isn't a real intent source.
+        return intent.goal || intent.who || intent.why ? intent : null;
+    }
+    catch {
+        return null;
+    }
+}
+function str(v) {
+    const s = typeof v === "string" ? v.trim() : "";
+    return s || undefined;
+}
+/** Render the project.faf-sourced intent as its own managed block. */
+function fafIntentBlock(intent) {
+    const lines = ["## Project", ""];
+    if (intent.goal)
+        lines.push(intent.goal, "");
+    if (intent.who)
+        lines.push(`**Who it's for:** ${intent.who}`, "");
+    if (intent.why)
+        lines.push(`**Why:** ${intent.why}`, "");
+    if (intent.keyFiles?.length) {
+        lines.push("**Start here:**", "");
+        for (const f of intent.keyFiles)
+            lines.push(`- \`${f}\``);
+        lines.push("");
+    }
+    return `${FAF_BLOCK_START}\n${lines.join("\n").trimEnd()}\n${FAF_BLOCK_END}\n`;
+}
+/**
+ * Author AGENTS.md for `root`. BETTER from repo facts alone; BEST — facts
+ * plus the project.faf intent block, ahead of it — when a project.faf with
+ * real content exists.
+ */
 export function authorAgentsMd(root) {
-    const block = authorBlock(buildRepoContext(root)).trim();
+    const factsBlock = `${BLOCK_START}\n${authorBlock(buildRepoContext(root)).trim()}\n${BLOCK_END}\n`;
+    const exists = existsSync(join(root, "AGENTS.md"));
+    const intent = readFafIntent(root);
+    if (!intent)
+        return { markdown: factsBlock, exists, tier: "better" };
     return {
-        markdown: `${BLOCK_START}\n${block}\n${BLOCK_END}\n`,
-        exists: existsSync(join(root, "AGENTS.md")),
+        markdown: `${fafIntentBlock(intent)}\n${factsBlock}`,
+        exists,
+        tier: "best",
     };
 }

package/dist/bin.d.ts

@@ -8,7 +8,7 @@ export interface Launch {
     root: string;
 }
 /** what a bare `--help` / `help` prints. */
-export declare const HELP = "mcp-context-card 0.5.1\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card [> f.html]  render this directory's context card to stdout\n                                      --theme light|dark    --accent #hex\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` or `--http` to see output directly.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
+export declare const HELP = "mcp-context-card 0.6.0\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card [> f.html]  render this directory's context card to stdout\n                                      --theme light|dark    --accent #hex\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` or `--http` to see output directly.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
 /**
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
  * tested without spawning a process.

package/dist/card-gen.js

@@ -2,6 +2,15 @@
  * card-gen - write docs/card.html from the three sources, so the card is
  * browsable on GitHub and screenshot-able for the README. Same renderer as
  * GET /card and the render_context_card tool.
+ *
+ * Also writes two theme-pinned siblings (docs/card-light.html,
+ * docs/card-dark.html) — docs/card.html stays "auto" (follows the viewer's
+ * OS preference); the two siblings are for linking a forced theme from the
+ * README, since a static host can't answer a `?theme=` query param.
+ *
+ * GitHub Pages serves this repo from main /docs (wolfe-jam.github.io/
+ * mcp-context-card/) — docs/index.html (a copy of the auto card) is what
+ * answers the bare root, so it isn't a 404.
  */
 import { writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -9,6 +18,10 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { renderCard } from "./render-card.js";
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     const root = join(dirname(fileURLToPath(import.meta.url)), "..");
-    writeFileSync(join(root, "docs/card.html"), renderCard(root));
-    console.log("wrote docs/card.html — the context card, rendered from AGENTS.md / project.fafm / .well-known/fafa");
+    const auto = renderCard(root);
+    writeFileSync(join(root, "docs/card.html"), auto);
+    writeFileSync(join(root, "docs/index.html"), auto);
+    writeFileSync(join(root, "docs/card-light.html"), renderCard(root, { theme: "light" }));
+    writeFileSync(join(root, "docs/card-dark.html"), renderCard(root, { theme: "dark" }));
+    console.log("wrote docs/card.html + docs/index.html (auto) + card-light.html + card-dark.html — the context card, rendered from AGENTS.md / project.fafm / .well-known/fafa");
 }

package/dist/constants.d.ts

@@ -1,5 +1,5 @@
 /** Server identity constants, in their own module so any file can import
  *  them without pulling in the whole server. */
 export declare const NAME = "mcp-context-card";
-export declare const VERSION = "0.5.1";
+export declare const VERSION = "0.6.0";
 export declare const SERVER_CARD_URI = "mcp-context-card://server-card";

package/dist/constants.js

@@ -1,5 +1,5 @@
 /** Server identity constants, in their own module so any file can import
  *  them without pulling in the whole server. */
 export const NAME = "mcp-context-card";
-export const VERSION = "0.5.1";
+export const VERSION = "0.6.0";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";

package/dist/identity.d.ts

@@ -16,7 +16,7 @@ export declare function whoami(root: string): string;
  * other two point at their worked-example artifacts; `memory` carries a note
  * because there is no de-facto standard for it yet.
  */
-export declare function trinityMeta(): {
+export declare function serverCardMeta(): {
     readonly "io.github.wolfe-jam.mcp-context-card/context": {
         readonly source: "AGENTS.md";
         readonly mediaType: "text/markdown";

package/dist/identity.js

@@ -61,7 +61,7 @@ export function whoami(root) {
  * other two point at their worked-example artifacts; `memory` carries a note
  * because there is no de-facto standard for it yet.
  */
-export function trinityMeta() {
+export function serverCardMeta() {
     return {
         [`${META_NS}/context`]: {
             source: "AGENTS.md",