mcp-context-card 0.5.1 → 0.6.0

package/dist/render-card.js

@@ -12,7 +12,7 @@
 import { join } from "node:path";
 import { parseAgentsMd } from "./agents-md.js";
 import { parseFafm } from "./memory.js";
-import { resolveIdentity, trinityMeta, META_NS } from "./identity.js";
+import { resolveIdentity, serverCardMeta, META_NS } from "./identity.js";
 import { NAME, SERVER_CARD_URI } from "./constants.js";
 import { escapeHtml, renderInline, renderMarkdown, slug } from "./md.js";
 /** AAIF brand orange (aaif.io). The default accent. */
@@ -26,15 +26,20 @@ const CSS = (accent) => `
   --accent:${accent};
   --bg:#f4f4f5; --card:#fff; --fg:#0a0a0a; --muted:#6b6b70;
   --line:rgba(0,0,0,.09); --chip:rgba(0,0,0,.05);
+  --card-shadow:0 1px 3px rgba(0,0,0,.06), 0 12px 32px rgba(0,0,0,.10);
 }
 :root[data-theme="dark"]{
   --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
   --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+  --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+    0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
 }
 @media (prefers-color-scheme:dark){
   :root:not([data-theme="light"]){
     --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
     --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+    --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+      0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
   }
 }
 *{box-sizing:border-box}
@@ -42,7 +47,7 @@ body{margin:0;background:var(--bg);color:var(--fg);
   font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
   padding:40px 18px}
 .card{max-width:760px;margin:0 auto;background:var(--card);border:1px solid var(--line);
-  border-radius:14px;overflow:hidden}
+  border-radius:14px;overflow:hidden;box-shadow:var(--card-shadow)}
 .card>*{padding:26px 30px}
 .top{border-top:4px solid var(--accent);border-bottom:1px solid var(--line)}
 h1{margin:0 0 10px;font-size:1.7rem;letter-spacing:-.02em}
@@ -92,7 +97,7 @@ export function renderCard(root, opts = {}) {
     const agents = parseAgentsMd(join(root, "AGENTS.md"));
     const mem = parseFafm(join(root, "project.fafm"));
     const id = resolveIdentity(root);
-    const meta = trinityMeta();
+    const meta = serverCardMeta();
     const name = id?.displayName ?? id?.name ?? NAME;
     const pills = [
         id?.vendor && id.vendor !== id.status && `<span class="pill">${escapeHtml(id.vendor)}</span>`,

package/dist/server.d.ts

@@ -2,10 +2,10 @@
  * mcp-context-card server — makes a project's context, memory, and identity
  * discoverable to any MCP client.
  *
- *   context   — read_agents_md · list_agents_md_sections   (this project's AGENTS.md)
- *   memory    — remember · recall · forget                 (a .fafm file)
- *   identity  — whoami                                     (this server's .fafa)
- *   discovery — list_context_sources                       (what's published, and how)
+ *   context   — read_agents_md · list_agents_md_sections · author_agents_md   (this project's AGENTS.md)
+ *   memory    — remember · recall · forget                                    (a .fafm file)
+ *   identity  — whoami                                                        (this server's .fafa)
+ *   discovery — list_context_sources · render_context_card                    (what's published, and how)
  *
  * ...exposed through the two mechanisms already in the ecosystem:
  *

package/dist/server.js

@@ -2,10 +2,10 @@
  * mcp-context-card server — makes a project's context, memory, and identity
  * discoverable to any MCP client.
  *
- *   context   — read_agents_md · list_agents_md_sections   (this project's AGENTS.md)
- *   memory    — remember · recall · forget                 (a .fafm file)
- *   identity  — whoami                                     (this server's .fafa)
- *   discovery — list_context_sources                       (what's published, and how)
+ *   context   — read_agents_md · list_agents_md_sections · author_agents_md   (this project's AGENTS.md)
+ *   memory    — remember · recall · forget                                    (a .fafm file)
+ *   identity  — whoami                                                        (this server's .fafa)
+ *   discovery — list_context_sources · render_context_card                    (what's published, and how)
  *
  * ...exposed through the two mechanisms already in the ecosystem:
  *
@@ -22,7 +22,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 import { findSection, parseAgentsMd } from "./agents-md.js";
 import { authorAgentsMd } from "./author.js";
 import { forget, parseFafm, recall, remember } from "./memory.js";
-import { identity, trinityMeta, whoami } from "./identity.js";
+import { identity, serverCardMeta, whoami } from "./identity.js";
 import { renderCard, safeAccent } from "./render-card.js";
 export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
 import { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
@@ -36,7 +36,7 @@ export const ROOT = join(here, "..");
  * `/.well-known/mcp/server-card`.
  */
 export function serverCard() {
-    return { name: NAME, version: VERSION, _meta: trinityMeta() };
+    return { name: NAME, version: VERSION, _meta: serverCardMeta() };
 }
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 /**
@@ -88,7 +88,7 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "author_agents_md",
-                description: "Author an AGENTS.md for this project from its repo facts (via agents-md-facts) and return the draft — a managed block, ready to drop in. Detects real build/test commands, entry points, and toolchain conventions; nothing invented. Does not write a file.",
+                description: "Author an AGENTS.md for this project and return the draft — BETTER from repo facts alone (via agents-md-facts: real build/test commands, entry points, toolchain conventions, nothing invented), or BEST when a project.faf exists (facts plus its structured goal/who/why as a second managed block ahead of them). Does not write a file.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
@@ -170,9 +170,10 @@ export function createServer(root = ROOT) {
             }
             case "author_agents_md": {
                 const a = authorAgentsMd(root);
+                const tier = a.tier === "best" ? "BEST (project.faf + facts)" : "BETTER (facts only)";
                 const note = a.exists
-                    ? "AGENTS.md already exists — diff this managed block in, don't overwrite"
-                    : "no AGENTS.md yet — write this, then `npx agents-md-facts --check` keeps it true";
+                    ? `${tier} — AGENTS.md already exists, diff this in, don't overwrite`
+                    : `${tier} — no AGENTS.md yet, write this, then \`npx agents-md-facts --check\` keeps the facts block true`;
                 return text(`<!-- ${note} -->\n\n${a.markdown}`);
             }
             case "remember": {

package/dist/transport/http.js

@@ -11,7 +11,7 @@
  * transports in a map; this one deliberately does not.
  *
  * Alongside the MCP endpoint it serves the discovery documents:
- *   GET /.well-known/mcp/server-card   — the Server Card + _meta trinity
+ *   GET /.well-known/mcp/server-card   — the Server Card + _meta block
  *   GET /.well-known/ai-catalog.json   — the three sibling entries
  *   GET /.well-known/fafa              — the agent identity card
  */

package/docs/MECHANISMS.md

@@ -29,7 +29,7 @@ Both return:
 ```jsonc
 {
   "name": "mcp-context-card",
-  "version": "0.2.0",
+  "version": "0.6.0",
   "_meta": {
     "io.github.wolfe-jam.mcp-context-card/context": {
       "source": "AGENTS.md",
@@ -39,7 +39,7 @@ Both return:
       "source": "project.fafm",
       "mediaType": "application/vnd.fafm+yaml",
       "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml",
-      "note": "no de-facto standard for agent memory yet — one instantiation"
+      "note": "no de-facto standard for agent memory yet — this is one instantiation"
     },
     "io.github.wolfe-jam.mcp-context-card/identity": {
       "source": ".well-known/fafa",
@@ -64,7 +64,7 @@ Both return:
   is for instructions; the block says so rather than implying `.fafm` is a
   standard.
 
-Built by `trinityMeta()` in [`src/identity.ts`](../src/identity.ts).
+Built by `serverCardMeta()` in [`src/identity.ts`](../src/identity.ts).
 
 ---
 
@@ -129,9 +129,26 @@ project.fafm   ─┼─→  Server Card _meta   (context · memory · identity)
   fafa
 ```
 
-`catalog-gen.ts` reads exactly the files `trinityMeta()` names. The CI job
+`catalog-gen.ts` reads exactly the files `serverCardMeta()` names. The CI job
 `npm run catalog:check` regenerates `ai-catalog.json` and fails on any drift —
 change a source, both surfaces move together.
 
 **Describe the artifacts once; expose them through whatever mechanism the
 consumer speaks.**
+
+---
+
+## Server Card, and A2A
+
+**Server Card** is what this server has: `AGENTS.md`, a memory file, an
+identity block — read in-band as an MCP resource, or out-of-band at
+`GET /.well-known/mcp/server-card`.
+
+**A2A's [AgentCard](https://a2a-protocol.org/latest/specification/)** is
+different: a live agent you can hand a task to — an endpoint, `capabilities`,
+`skills`, authentication.
+
+`.fafa` is the identity source behind the Server Card. We're ready for A2A:
+the day a project here is reachable over A2A, the same source publishes a
+real AgentCard alongside it — one more mechanism, same invariant, a real
+endpoint and real skills, not a reshape of `.fafa`.

package/docs/TRANSPORT.md

@@ -41,7 +41,7 @@ the wire, so all logging goes to `stderr`.
 ```
 GET  /                          → index (endpoints)
 POST /mcp                       → MCP (initialize, tools/list, tools/call, …)
-GET  /.well-known/mcp/server-card   → the Server Card + _meta trinity block
+GET  /.well-known/mcp/server-card   → the Server Card + _meta block
 GET  /.well-known/ai-catalog.json   → the three sibling entries
 GET  /.well-known/fafa              → the agent identity card
 ```

package/docs/WIRING.md

@@ -77,7 +77,7 @@ And to discover what a server offers before committing to it:
 
 ```ts
 await client.callTool({ name: "list_context_sources", arguments: {} });
-// → { context: { source: "AGENTS.md", mediaType: "text/markdown", present: true, sections: 9 },
+// → { context: { source: "AGENTS.md", mediaType: "text/markdown", present: true, sections: 10 },
 //     memory:  { … }, identity: { … },
 //     surfaces: { mcp: { serverCard: "resource mcp-context-card://server-card" },
 //                 http: { serverCard: "GET /.well-known/mcp/server-card",
@@ -94,11 +94,11 @@ To serve *your* artifacts:
 1. **Replace the three files** — `AGENTS.md`, `project.fafm`, `.well-known/fafa`
    — with your own, or point `MCP_CONTEXT_CARD_ROOT` at a directory that has them.
    `AGENTS.md` is the one with a real standard; the other two are swappable.
-2. **Rename the namespace.** `trinityMeta()` in `src/identity.ts` uses
+2. **Rename the namespace.** `serverCardMeta()` in `src/identity.ts` uses
    `io.github.wolfe-jam.mcp-context-card/*` keys, and `buildCatalog()` in
    `src/catalog-gen.ts` uses `urn:air:mcp-context-card:*` identifiers. Change both to
    a domain or GitHub identity you control ([MECHANISMS.md](./MECHANISMS.md)).
-3. **Swap the media types** in `trinityMeta()` if your memory / identity
+3. **Swap the media types** in `serverCardMeta()` if your memory / identity
    artifacts aren't `.fafm` / `.fafa`. Drop the `iana` field for any that isn't
    a registered type.
 4. `npm run catalog` to regenerate, `npm run demo` to confirm all three still

package/docs/card-dark.html

@@ -0,0 +1,126 @@
+<!doctype html>
+<html lang="en" data-theme="dark">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>mcp-context-card — context card</title>
+<style>
+:root{
+  --accent:#FF702D;
+  --bg:#f4f4f5; --card:#fff; --fg:#0a0a0a; --muted:#6b6b70;
+  --line:rgba(0,0,0,.09); --chip:rgba(0,0,0,.05);
+  --card-shadow:0 1px 3px rgba(0,0,0,.06), 0 12px 32px rgba(0,0,0,.10);
+}
+:root[data-theme="dark"]{
+  --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+  --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+  --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+    0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
+}
+@media (prefers-color-scheme:dark){
+  :root:not([data-theme="light"]){
+    --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+    --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+    --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+      0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
+  }
+}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);
+  font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  padding:40px 18px}
+.card{max-width:760px;margin:0 auto;background:var(--card);border:1px solid var(--line);
+  border-radius:14px;overflow:hidden;box-shadow:var(--card-shadow)}
+.card>*{padding:26px 30px}
+.top{border-top:4px solid var(--accent);border-bottom:1px solid var(--line)}
+h1{margin:0 0 10px;font-size:1.7rem;letter-spacing:-.02em}
+.pills{display:flex;flex-wrap:wrap;gap:6px}
+.pill{font-size:.74rem;font-weight:600;padding:3px 9px;border-radius:20px;background:var(--chip);color:var(--muted)}
+.pill.accent{background:color-mix(in srgb,var(--accent) 16%,transparent);color:var(--accent)}
+section{border-bottom:1px solid var(--line)}
+section:last-child{border-bottom:0}
+.label{font-size:.7rem;font-weight:700;letter-spacing:.16em;text-transform:uppercase;
+  color:var(--accent);margin:0 0 14px}
+.toc{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0 0 20px;padding:0;list-style:none}
+.toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
+.toc a:hover{color:var(--accent)}
+.md h1,.md h2,.md h3,.md h4{margin:22px 0 8px;font-size:1rem;letter-spacing:-.01em}
+.md h1{font-size:1.15rem}
+.md p{margin:8px 0}
+.md ul,.md ol{margin:8px 0;padding-left:22px}
+.md li{margin:3px 0}
+.md code{background:var(--chip);padding:1px 5px;border-radius:5px;
+  font:.86em ui-monospace,SFMono-Regular,Menlo,monospace}
+.md pre{background:var(--chip);padding:14px 16px;border-radius:9px;overflow:auto}
+.md pre code{background:none;padding:0}
+.md table{border-collapse:collapse;width:100%;margin:12px 0;font-size:.88rem;display:block;overflow:auto}
+.md th,.md td{border:1px solid var(--line);padding:6px 10px;text-align:left}
+.md blockquote{margin:10px 0;padding-left:14px;border-left:3px solid var(--line);color:var(--muted)}
+.md a{color:var(--accent)}
+.fact{padding:12px 0;border-bottom:1px solid var(--line)}
+.fact:last-child{border-bottom:0}
+.fact p{margin:0 0 7px}
+.meta{display:flex;flex-wrap:wrap;gap:6px;align-items:center}
+.tag{font-size:.72rem;padding:2px 8px;border-radius:5px;background:var(--chip);color:var(--muted)}
+.dot{width:7px;height:7px;border-radius:50%;background:var(--accent);display:inline-block}
+.dot.pending{background:var(--muted)}
+.disc{width:100%;border-collapse:collapse;font-size:.84rem}
+.disc th,.disc td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--line)}
+.disc th{color:var(--muted);font-weight:600}
+.disc code{font:.86em ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted)}
+.fetch{margin:14px 0 0;font-size:.82rem;color:var(--muted)}
+.fetch code{background:var(--chip);padding:1px 5px;border-radius:5px}
+.foot{color:var(--muted);font-size:.78rem;text-align:center;border-top:1px solid var(--line)}
+.none{color:var(--muted);font-style:italic}
+</style>
+</head>
+<body>
+<main class="card">
+  <div class="top">
+    <h1>mcp-context-card</h1>
+    <div class="pills"><span class="pill">io.github.wolfe-jam</span><span class="pill">v0.6.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+  </div>
+  <section>
+    <p class="label">Context — AGENTS.md</p>
+    <ul class="toc"><li><a href="#setup">Setup</a></li><li><a href="#build">Build</a></li><li><a href="#test">Test</a></li><li><a href="#layout">Layout</a></li><li><a href="#conventions">Conventions</a></li><li><a href="#the-invariant">The invariant</a></li><li><a href="#safety">Safety</a></li><li><a href="#definition-of-done">Definition of done</a></li><li><a href="#authoring-this-file">Authoring this file</a></li></ul><div class="md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — 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 <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
+<p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p>
+<h2 id="setup">Setup</h2>
+<pre><code class="language-bash">npm ci</code></pre>
+<p>Node 22 or newer. No other system dependencies.</p>
+<h2 id="build">Build</h2>
+<pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/</code></pre>
+<h2 id="test">Test</h2>
+<pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
+npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
+npm run demo          # end to end: all tools over stdio, then over stateless HTTP</code></pre>
+<p>CI runs <code>typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>).</p>
+<h2 id="layout">Layout</h2>
+<table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table>
+<h2 id="conventions">Conventions</h2>
+<ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul>
+<h2 id="the-invariant">The invariant</h2>
+<p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p>
+<h2 id="safety">Safety</h2>
+<ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul>
+<h2 id="definition-of-done">Definition of done</h2>
+<p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>.</p>
+<h2 id="authoring-this-file">Authoring this file</h2>
+<p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div>
+  </section>
+  <section>
+    <p class="label">Memory — 4 facts</p>
+    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER.</p><div class="meta"><span class="tag">agents-md</span><span class="tag">author_agents_md</span><span class="tag">faf</span><span class="dot" title="verified"></span></div></div>
+  </section>
+  <section>
+    <p class="label">Discovery</p>
+    <table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody><tr><td>context</td><td><code>AGENTS.md</code></td><td><code>text/markdown</code></td></tr><tr><td>memory</td><td><code>project.fafm</code></td><td><code>application/vnd.fafm+yaml</code></td></tr><tr><td>identity</td><td><code>.well-known/fafa</code></td><td><code>application/vnd.fafa+yaml</code></td></tr></tbody></table>
+    <p class="fetch">A machine reads this over <b>MCP</b> from the
+      <code>mcp-context-card://server-card</code> resource; over <b>HTTP</b> also
+      from <code>GET /.well-known/mcp/server-card</code> and
+      <code>GET /.well-known/ai-catalog.json</code>.</p>
+  </section>
+  <div class="foot">mcp-context-card · context card</div>
+</main>
+</body>
+</html>

package/docs/card-light.html

@@ -0,0 +1,126 @@
+<!doctype html>
+<html lang="en" data-theme="light">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>mcp-context-card — context card</title>
+<style>
+:root{
+  --accent:#FF702D;
+  --bg:#f4f4f5; --card:#fff; --fg:#0a0a0a; --muted:#6b6b70;
+  --line:rgba(0,0,0,.09); --chip:rgba(0,0,0,.05);
+  --card-shadow:0 1px 3px rgba(0,0,0,.06), 0 12px 32px rgba(0,0,0,.10);
+}
+:root[data-theme="dark"]{
+  --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+  --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+  --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+    0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
+}
+@media (prefers-color-scheme:dark){
+  :root:not([data-theme="light"]){
+    --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+    --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+    --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+      0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
+  }
+}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);
+  font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  padding:40px 18px}
+.card{max-width:760px;margin:0 auto;background:var(--card);border:1px solid var(--line);
+  border-radius:14px;overflow:hidden;box-shadow:var(--card-shadow)}
+.card>*{padding:26px 30px}
+.top{border-top:4px solid var(--accent);border-bottom:1px solid var(--line)}
+h1{margin:0 0 10px;font-size:1.7rem;letter-spacing:-.02em}
+.pills{display:flex;flex-wrap:wrap;gap:6px}
+.pill{font-size:.74rem;font-weight:600;padding:3px 9px;border-radius:20px;background:var(--chip);color:var(--muted)}
+.pill.accent{background:color-mix(in srgb,var(--accent) 16%,transparent);color:var(--accent)}
+section{border-bottom:1px solid var(--line)}
+section:last-child{border-bottom:0}
+.label{font-size:.7rem;font-weight:700;letter-spacing:.16em;text-transform:uppercase;
+  color:var(--accent);margin:0 0 14px}
+.toc{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0 0 20px;padding:0;list-style:none}
+.toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
+.toc a:hover{color:var(--accent)}
+.md h1,.md h2,.md h3,.md h4{margin:22px 0 8px;font-size:1rem;letter-spacing:-.01em}
+.md h1{font-size:1.15rem}
+.md p{margin:8px 0}
+.md ul,.md ol{margin:8px 0;padding-left:22px}
+.md li{margin:3px 0}
+.md code{background:var(--chip);padding:1px 5px;border-radius:5px;
+  font:.86em ui-monospace,SFMono-Regular,Menlo,monospace}
+.md pre{background:var(--chip);padding:14px 16px;border-radius:9px;overflow:auto}
+.md pre code{background:none;padding:0}
+.md table{border-collapse:collapse;width:100%;margin:12px 0;font-size:.88rem;display:block;overflow:auto}
+.md th,.md td{border:1px solid var(--line);padding:6px 10px;text-align:left}
+.md blockquote{margin:10px 0;padding-left:14px;border-left:3px solid var(--line);color:var(--muted)}
+.md a{color:var(--accent)}
+.fact{padding:12px 0;border-bottom:1px solid var(--line)}
+.fact:last-child{border-bottom:0}
+.fact p{margin:0 0 7px}
+.meta{display:flex;flex-wrap:wrap;gap:6px;align-items:center}
+.tag{font-size:.72rem;padding:2px 8px;border-radius:5px;background:var(--chip);color:var(--muted)}
+.dot{width:7px;height:7px;border-radius:50%;background:var(--accent);display:inline-block}
+.dot.pending{background:var(--muted)}
+.disc{width:100%;border-collapse:collapse;font-size:.84rem}
+.disc th,.disc td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--line)}
+.disc th{color:var(--muted);font-weight:600}
+.disc code{font:.86em ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted)}
+.fetch{margin:14px 0 0;font-size:.82rem;color:var(--muted)}
+.fetch code{background:var(--chip);padding:1px 5px;border-radius:5px}
+.foot{color:var(--muted);font-size:.78rem;text-align:center;border-top:1px solid var(--line)}
+.none{color:var(--muted);font-style:italic}
+</style>
+</head>
+<body>
+<main class="card">
+  <div class="top">
+    <h1>mcp-context-card</h1>
+    <div class="pills"><span class="pill">io.github.wolfe-jam</span><span class="pill">v0.6.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+  </div>
+  <section>
+    <p class="label">Context — AGENTS.md</p>
+    <ul class="toc"><li><a href="#setup">Setup</a></li><li><a href="#build">Build</a></li><li><a href="#test">Test</a></li><li><a href="#layout">Layout</a></li><li><a href="#conventions">Conventions</a></li><li><a href="#the-invariant">The invariant</a></li><li><a href="#safety">Safety</a></li><li><a href="#definition-of-done">Definition of done</a></li><li><a href="#authoring-this-file">Authoring this file</a></li></ul><div class="md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — 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 <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
+<p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p>
+<h2 id="setup">Setup</h2>
+<pre><code class="language-bash">npm ci</code></pre>
+<p>Node 22 or newer. No other system dependencies.</p>
+<h2 id="build">Build</h2>
+<pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/</code></pre>
+<h2 id="test">Test</h2>
+<pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
+npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
+npm run demo          # end to end: all tools over stdio, then over stateless HTTP</code></pre>
+<p>CI runs <code>typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>).</p>
+<h2 id="layout">Layout</h2>
+<table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table>
+<h2 id="conventions">Conventions</h2>
+<ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul>
+<h2 id="the-invariant">The invariant</h2>
+<p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p>
+<h2 id="safety">Safety</h2>
+<ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul>
+<h2 id="definition-of-done">Definition of done</h2>
+<p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>.</p>
+<h2 id="authoring-this-file">Authoring this file</h2>
+<p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div>
+  </section>
+  <section>
+    <p class="label">Memory — 4 facts</p>
+    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER.</p><div class="meta"><span class="tag">agents-md</span><span class="tag">author_agents_md</span><span class="tag">faf</span><span class="dot" title="verified"></span></div></div>
+  </section>
+  <section>
+    <p class="label">Discovery</p>
+    <table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody><tr><td>context</td><td><code>AGENTS.md</code></td><td><code>text/markdown</code></td></tr><tr><td>memory</td><td><code>project.fafm</code></td><td><code>application/vnd.fafm+yaml</code></td></tr><tr><td>identity</td><td><code>.well-known/fafa</code></td><td><code>application/vnd.fafa+yaml</code></td></tr></tbody></table>
+    <p class="fetch">A machine reads this over <b>MCP</b> from the
+      <code>mcp-context-card://server-card</code> resource; over <b>HTTP</b> also
+      from <code>GET /.well-known/mcp/server-card</code> and
+      <code>GET /.well-known/ai-catalog.json</code>.</p>
+  </section>
+  <div class="foot">mcp-context-card · context card</div>
+</main>
+</body>
+</html>

package/docs/card.html

@@ -9,15 +9,20 @@
   --accent:#FF702D;
   --bg:#f4f4f5; --card:#fff; --fg:#0a0a0a; --muted:#6b6b70;
   --line:rgba(0,0,0,.09); --chip:rgba(0,0,0,.05);
+  --card-shadow:0 1px 3px rgba(0,0,0,.06), 0 12px 32px rgba(0,0,0,.10);
 }
 :root[data-theme="dark"]{
   --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
   --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+  --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+    0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
 }
 @media (prefers-color-scheme:dark){
   :root:not([data-theme="light"]){
     --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
     --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+    --card-shadow:0 0 0 1px rgba(255,255,255,.16),
+      0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
   }
 }
 *{box-sizing:border-box}
@@ -25,7 +30,7 @@ body{margin:0;background:var(--bg);color:var(--fg);
   font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
   padding:40px 18px}
 .card{max-width:760px;margin:0 auto;background:var(--card);border:1px solid var(--line);
-  border-radius:14px;overflow:hidden}
+  border-radius:14px;overflow:hidden;box-shadow:var(--card-shadow)}
 .card>*{padding:26px 30px}
 .top{border-top:4px solid var(--accent);border-bottom:1px solid var(--line)}
 h1{margin:0 0 10px;font-size:1.7rem;letter-spacing:-.02em}
@@ -73,11 +78,11 @@ section:last-child{border-bottom:0}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.wolfe-jam</span><span class="pill">v0.5.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.wolfe-jam</span><span class="pill">v0.6.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
-    <ul class="toc"><li><a href="#setup">Setup</a></li><li><a href="#build">Build</a></li><li><a href="#test">Test</a></li><li><a href="#layout">Layout</a></li><li><a href="#conventions">Conventions</a></li><li><a href="#the-invariant">The invariant</a></li><li><a href="#safety">Safety</a></li><li><a href="#definition-of-done">Definition of done</a></li><li><a href="#authoring-this-file">Authoring this file</a></li></ul><div class="md"><p><code>mcp-context-card</code> is an MCP server that makes a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> discoverable to any MCP client — through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
+    <ul class="toc"><li><a href="#setup">Setup</a></li><li><a href="#build">Build</a></li><li><a href="#test">Test</a></li><li><a href="#layout">Layout</a></li><li><a href="#conventions">Conventions</a></li><li><a href="#the-invariant">The invariant</a></li><li><a href="#safety">Safety</a></li><li><a href="#definition-of-done">Definition of done</a></li><li><a href="#authoring-this-file">Authoring this file</a></li></ul><div class="md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — 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 <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
 <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p>
 <h2 id="setup">Setup</h2>
 <pre><code class="language-bash">npm ci</code></pre>
@@ -91,7 +96,7 @@ npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80,
 npm run demo          # end to end: all tools over stdio, then over stateless HTTP</code></pre>
 <p>CI runs <code>typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>).</p>
 <h2 id="layout">Layout</h2>
-<table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — wraps <code>agents-md-facts</code> (the AGENTS.md authoring engine)</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table>
+<table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table>
 <h2 id="conventions">Conventions</h2>
 <ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul>
 <h2 id="the-invariant">The invariant</h2>
@@ -101,11 +106,11 @@ npm run demo          # end to end: all tools over stdio, then over stateless HT
 <h2 id="definition-of-done">Definition of done</h2>
 <p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>.</p>
 <h2 id="authoring-this-file">Authoring this file</h2>
-<p><code>AGENTS.md</code> here is maintained by hand. It can also be generated from the repo's <code>project.faf</code> with <code>faf export --agents</code> — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div>
+<p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div>
   </section>
   <section>
-    <p class="label">Memory — 3 facts</p>
-    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div>
+    <p class="label">Memory — 4 facts</p>
+    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER.</p><div class="meta"><span class="tag">agents-md</span><span class="tag">author_agents_md</span><span class="tag">faf</span><span class="dot" title="verified"></span></div></div>
   </section>
   <section>
     <p class="label">Discovery</p>