mcp-context-card 1.0.1 → 1.1.1

package/.well-known/fafa

@@ -9,7 +9,7 @@ agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
   vendor: "io.github.Wolfe-Jam"
-  version: "1.0.1"
+  version: "1.1.1"
   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

package/AGENTS.md

@@ -15,7 +15,7 @@ connection.
 npm ci
 ```
 
-Node 22 or newer. No other system dependencies.
+Node 20 or newer. No other system dependencies.
 
 ## Build
 

package/CHANGELOG.md

@@ -2,6 +2,55 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.1.1
+
+Every tool now says what it is and what it does to your project.
+
+Each of the nine tools carries a human-readable `title` and MCP tool
+annotations, so a host can label it properly and decide whether to ask
+before running it:
+
+- **Read-only (7):** `read_agents_md`, `list_agents_md_sections`,
+  `author_agents_md` (returns a draft, writes nothing), `recall`, `whoami`,
+  `list_context_sources`, `render_context_card`.
+- **Writes the memory file (2):** `remember` and `forget` are marked
+  `destructiveHint: true`. `remember` replaces a fact when an id is reused;
+  `forget` removes one.
+- All nine are `idempotentHint: true` (repeating a call changes nothing more)
+  and `openWorldHint: false` (they only touch the local project).
+
+A new test checks every tool's title and hints against what it actually does,
+so a tool added later can't ship without them. 106 tests, all green on
+Linux, macOS, and Windows.
+
+No API change to the nine tools: same names, same inputs, same behaviour.
+
+## 1.1.0
+
+The card scans in one screen — AGENTS.md sections collapse by default.
+
+Every AGENTS.md section is now its own `<details>`, closed on load: the card
+opens as identity → the section list → memory count → discovery, one screen,
+scannable. Click a section to read it; the section index stays sticky at the
+top so it's always one click away, not a scroll back up.
+
+- **Expand all / Collapse all** — a control in the sticky nav, from one
+  ~16-line inline script (no external resources; the card is still one
+  self-contained file). It's a progressive enhancement: the button ships
+  `hidden` and the script reveals it, so with JavaScript off every section
+  still opens and closes on its own.
+- **`--expanded` / `?expand=all` / `expanded: true`** — the full-page render,
+  for a screenshot or a PR. Available on the CLI (`npx mcp-context-card card
+  --expanded`), the HTTP transport (`GET /card?expand=all`), and the
+  `render_context_card` tool. This path renders `<details open>` server-side —
+  no script involved.
+- **A section index link opens its section** — `#section` in the URL, or a
+  click in the nav.
+- **Print / save-as-PDF** opens every section first, then restores.
+
+No API change to the nine tools. `render_context_card` gains an optional
+`expanded` boolean; everything else is unchanged.
+
 ## 1.0.1
 
 `npx mcp-context-card` now runs — it silently no-op'd when launched through

package/README.md

@@ -70,14 +70,21 @@ file access, no shell, no search.
 
 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.
+memory, and how a machine fetches it. The view for people: read it, screenshot
+it, drop it in a PR, put it on a status page.
+
+`AGENTS.md` sections are collapsed by default, so the card scans in one screen;
+a sticky index jumps to any section, **Expand all** opens everything. Sections
+toggle natively — the one small inline script only adds the bulk button and the
+print handler. `--expanded` / `?expand=all` renders it fully open, script-free,
+for a screenshot.
 
 ```
-npx mcp-context-card card       # at a terminal: writes context-card.html and opens it
+npx mcp-context-card card            # at a terminal: writes context-card.html and opens it
+npx mcp-context-card card --expanded # every section open
 npx mcp-context-card card > x.html   # piped/redirected: raw HTML to stdout
-GET /card                       # live, on the HTTP transport
-GET /card?theme=light&accent=%230066cc
+GET /card                            # live, on the HTTP transport
+GET /card?expand=all&theme=light&accent=%230066cc
 ```
 
 Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
@@ -115,7 +122,7 @@ npx mcp-context-card card
 
 At a terminal it writes `context-card.html` and opens it in your browser. Piped
 or redirected (`> card.html`, a script, CI) it writes raw HTML to stdout instead;
-`--stdout` forces that from a terminal too.
+`--stdout` forces that from a terminal too. `--expanded` opens every section.
 
 ### Wire it into a host
 
@@ -186,6 +193,10 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
 | `list_context_sources` | what this project publishes, in what media types, via which surface |
 | `render_context_card` | the whole card as one self‑contained HTML page (also `GET /card`) |
 
+Seven tools only read. `remember` and `forget` write the memory file, so they're
+marked destructive and a host can ask before running them. Every tool carries a
+title and MCP tool annotations.
+
 ## The demo
 
 `npm run demo` runs every tool over both transports:
@@ -198,10 +209,11 @@ 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`.
 
-104 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
+106 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.
+one; another checks the stdio and HTTP tool surfaces match, and another checks
+every tool's title and behaviour hints against what it actually does.
 
 ## Layout
 

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 1.0.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             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex   --stdout\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` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
+export declare const HELP = "mcp-context-card 1.1.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             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex\n                                      --expanded (all sections open)   --stdout\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` (opens your context in a browser) or `--http`.\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/bin.js

@@ -9,7 +9,8 @@
  *   mcp-context-card card         → this directory's context card. At a terminal:
  *                                   writes context-card.html and opens it. Piped
  *                                   or redirected: HTML to stdout ( > card.html ).
- *                                   --theme light|dark · --accent #hex · --stdout
+ *                                   --theme light|dark · --accent #hex
+ *                                   --expanded (all sections open) · --stdout
  *   mcp-context-card --help       → usage
  *   mcp-context-card --version    → version
  *
@@ -32,7 +33,8 @@ USAGE
   mcp-context-card --stdio          force stdio even when PORT is set
   mcp-context-card card             this dir's context card — opens it in your browser
                                     at a terminal; HTML to stdout when piped ( > f.html )
-                                      --theme light|dark   --accent #hex   --stdout
+                                      --theme light|dark   --accent #hex
+                                      --expanded (all sections open)   --stdout
   mcp-context-card --help           this text
   mcp-context-card --version        print version
 
@@ -109,6 +111,7 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
         const html = renderCard(root, {
             theme: theme === "light" || theme === "dark" ? theme : "auto",
             accent: safeAccent(flagValue(argv, "--accent")),
+            expanded: argv.includes("--expanded"),
         });
         // Piped / redirected (or --stdout) → raw HTML on stdout, unchanged.
         // A bare run at a terminal → the HTML is noise; write a file and open it.

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 = "1.0.1";
+export declare const VERSION = "1.1.1";
 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 = "1.0.1";
+export const VERSION = "1.1.1";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";

package/dist/render-card.d.ts

@@ -3,6 +3,12 @@ export interface CardOptions {
     theme?: Theme;
     /** CSS hex colour for the accent. Validated; invalid falls back to AAIF. */
     accent?: string;
+    /**
+     * Render every AGENTS.md section open. Default: sections collapse to their
+     * headings (`<details>`), click one to read it — the card scans in one screen.
+     * `expanded` is the whole-page render, for a screenshot or a PR.
+     */
+    expanded?: boolean;
 }
 /** AAIF brand orange (aaif.io). The default accent. */
 export declare const AAIF_ACCENT = "#FF702D";

package/dist/render-card.js

@@ -6,8 +6,9 @@
  * or drop into a PR. Same three sources as the Server Card _meta block and
  * ai-catalog; this is the view for people.
  *
- * Self-contained: inline CSS, no JS, no external fonts. Renders anywhere,
- * including as a data: URI.
+ * Self-contained: inline CSS, no external fonts or resources. The only script
+ * is the expand-all / print helper (TOGGLE_SCRIPT) — a progressive enhancement;
+ * every section still opens on its own without it. Renders anywhere.
  */
 import { join } from "node:path";
 import { parseAgentsMd } from "./agents-md.js";
@@ -47,7 +48,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;box-shadow:var(--card-shadow)}
+  border-radius:14px;overflow:clip;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}
@@ -58,9 +59,31 @@ 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{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0;padding:0;list-style:none}
 .toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
 .toc a:hover{color:var(--accent)}
+/* ── collapsible context ─────────────────────────────────────────── */
+.ctx-nav{position:sticky;top:0;z-index:3;background:var(--card);
+  margin:0 -30px 16px;padding:11px 30px;border-bottom:1px solid var(--line);
+  display:flex;flex-wrap:wrap;align-items:flex-start;gap:8px 16px}
+.xall{margin-left:auto;flex:none;font:inherit;font-size:.76rem;font-weight:600;
+  white-space:nowrap;padding:3px 11px;border-radius:20px;border:1px solid var(--line);
+  background:var(--chip);color:var(--muted);cursor:pointer}
+.xall:hover{color:var(--accent);border-color:var(--accent)}
+.ctx-preamble{padding-bottom:4px}
+details.ctx-section{border-top:1px solid var(--line)}
+details.ctx-section>summary{cursor:pointer;list-style:none;padding:11px 0;
+  font-weight:600;font-size:1rem;letter-spacing:-.01em;display:flex;gap:9px}
+details.ctx-section>summary::-webkit-details-marker{display:none}
+details.ctx-section>summary::before{content:"›";color:var(--accent);font-weight:700;
+  transition:transform .15s ease}
+details.ctx-section[open]>summary::before{transform:rotate(90deg)}
+details.ctx-section>.md{padding:0 0 16px}
+@media print{
+  .ctx-nav{display:none}
+  details.ctx-section:not([open])>.md{display:block!important}
+  details.ctx-section>summary::before{content:""}
+}
 .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}
@@ -107,21 +130,28 @@ export function renderCard(root, opts = {}) {
     ]
         .filter(Boolean)
         .join("");
-    // CONTEXT — drop the redundant top-level "# AGENTS.md" heading, keep its intro
+    // CONTEXT — one <details> per AGENTS.md section, collapsed by default (the card
+    // scans in one screen); `expanded` renders them all open. The "# AGENTS.md"
+    // top-level heading is dropped; its intro rides above the sections.
     const bodySections = agents?.sections.filter((s) => s.level > 1) ?? [];
     const toc = bodySections.length
         ? `<ul class="toc">${bodySections
             .map((s) => `<li><a href="#${slug(s.heading)}">${escapeHtml(s.heading)}</a></li>`)
             .join("")}</ul>`
         : "";
+    const preamble = [agents?.preamble, agents?.sections.find((s) => s.level === 1)?.body ?? ""]
+        .filter(Boolean)
+        .join("\n\n");
+    const openAttr = opts.expanded ? " open" : "";
+    const sections = bodySections
+        .map((s) => `<details class="ctx-section"${openAttr} id="${slug(s.heading)}"><summary>${escapeHtml(s.heading)}</summary><div class="md">${renderMarkdown(s.body)}</div></details>`)
+        .join("");
     const contextBody = agents
-        ? `${toc}<div class="md">${renderMarkdown([
-            agents.preamble,
-            agents.sections.find((s) => s.level === 1)?.body ?? "",
-            ...bodySections.map((s) => `${"#".repeat(s.level)} ${s.heading}\n\n${s.body}`),
-        ]
-            .filter(Boolean)
-            .join("\n\n"))}</div>`
+        ? `<div class="ctx-nav">${toc}${bodySections.length
+            ? `<button type="button" class="xall" hidden>${opts.expanded ? "Collapse all" : "Expand all"}</button>`
+            : ""}</div>
+    ${preamble ? `<div class="ctx-preamble md">${renderMarkdown(preamble)}</div>` : ""}
+    <div class="ctx-body">${sections}</div>`
         : `<p class="none">No AGENTS.md in this project.</p>`;
     // MEMORY
     const memoryBody = mem.facts.length
@@ -174,7 +204,35 @@ export function renderCard(root, opts = {}) {
   </section>
   <div class="foot">${escapeHtml(name)} · context card</div>
 </main>
+${bodySections.length ? TOGGLE_SCRIPT : ""}
 </body>
 </html>
 `;
 }
+/**
+ * Expand-all / Collapse-all. The only script in the card — a progressive
+ * enhancement: with it off, every section still opens and closes on its own
+ * (native `<details>`), just without the bulk button. It also opens every
+ * section for printing, since browsers don't agree on whether a closed
+ * `<details>` prints its content.
+ */
+const TOGGLE_SCRIPT = `<script>
+(function(){
+  var btn=document.querySelector(".xall");
+  var secs=[].slice.call(document.querySelectorAll("details.ctx-section"));
+  if(!btn||!secs.length)return;
+  var sync=function(){btn.textContent=secs.every(function(d){return d.open})?"Collapse all":"Expand all"};
+  btn.hidden=false;
+  btn.addEventListener("click",function(){
+    var open=!secs.every(function(d){return d.open});
+    secs.forEach(function(d){d.open=open});sync();
+  });
+  secs.forEach(function(d){d.addEventListener("toggle",sync)});
+  var openHash=function(){var d=document.getElementById(location.hash.slice(1));if(d&&d.tagName==="DETAILS")d.open=true};
+  addEventListener("hashchange",openHash);openHash();
+  var pre=[];
+  addEventListener("beforeprint",function(){pre=secs.map(function(d){return d.open});secs.forEach(function(d){d.open=true})});
+  addEventListener("afterprint",function(){secs.forEach(function(d,i){d.open=pre[i]});sync()});
+  sync();
+})();
+</script>`;

package/dist/server.js

@@ -82,6 +82,8 @@ export function createServer(root = ROOT) {
         tools: [
             {
                 name: "read_agents_md",
+                title: "Read AGENTS.md",
+                annotations: { title: "Read AGENTS.md", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Return this project's AGENTS.md — the whole file, or one section by heading. The instructions a client would otherwise have to know to look for and read wholesale.",
                 inputSchema: {
                     type: "object",
@@ -95,16 +97,22 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "author_agents_md",
+                title: "Draft an AGENTS.md",
+                annotations: { title: "Draft an AGENTS.md", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 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: {} },
             },
             {
                 name: "list_agents_md_sections",
+                title: "List AGENTS.md Sections",
+                annotations: { title: "List AGENTS.md Sections", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "List the headings in this project's AGENTS.md, so a client can pull one section instead of spending context on the whole file.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
                 name: "remember",
+                title: "Remember a Fact",
+                annotations: { title: "Remember a Fact", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Persist a fact past the session boundary — written to a .fafm file, not held in memory. Reusing an existing id replaces that fact's text in place (no duplicate); a new id appends. Facts are written verification_status: unverified.",
                 inputSchema: {
                     type: "object",
@@ -123,6 +131,8 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "recall",
+                title: "Recall a Fact",
+                annotations: { title: "Recall a Fact", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Retrieve a fact stored in a previous session by id. Exact lookup — not fuzzy or substring.",
                 inputSchema: {
                     type: "object",
@@ -137,6 +147,8 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "forget",
+                title: "Forget a Fact",
+                annotations: { title: "Forget a Fact", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Remove a fact by id — to correct or drop something stale. A missing id is reported, not an error.",
                 inputSchema: {
                     type: "object",
@@ -151,22 +163,29 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "whoami",
+                title: "Who Am I",
+                annotations: { title: "Who Am I", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "This server's own identity — name, vendor, version, status, license — from its .fafa card.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
                 name: "list_context_sources",
+                title: "List Context Sources",
+                annotations: { title: "List Context Sources", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "What context does this project publish (AGENTS.md, memory, identity), in what media types, and through which discovery surface. For a client connecting cold.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
                 name: "render_context_card",
-                description: "Render the whole card — identity, AGENTS.md, memory, discovery — as one self-contained HTML page a person can read or screenshot. Also served at GET /card over the HTTP transport.",
+                title: "Render Context Card",
+                annotations: { title: "Render Context Card", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+                description: "Render the whole card — identity, AGENTS.md, memory, discovery — as one self-contained HTML page a person can read or screenshot. AGENTS.md sections collapse by default; pass expanded:true for the full render. Also served at GET /card (?expand=all) over the HTTP transport.",
                 inputSchema: {
                     type: "object",
                     properties: {
                         theme: { type: "string", enum: ["light", "dark", "auto"], description: "default: auto" },
                         accent: { type: "string", description: "CSS hex colour, e.g. #FF702D (default: the AAIF palette)" },
+                        expanded: { type: "boolean", description: "render every AGENTS.md section open (default: collapsed)" },
                     },
                 },
             },
@@ -215,7 +234,8 @@ export function createServer(root = ROOT) {
             }
             case "whoami":
                 return text(whoami(root));
-            case "render_context_card":
+            case "render_context_card": {
+                const rawExpanded = args.expanded;
                 return {
                     content: [
                         {
@@ -223,10 +243,12 @@ export function createServer(root = ROOT) {
                             text: renderCard(root, {
                                 theme: (["light", "dark", "auto"].includes(args.theme) ? args.theme : "auto"),
                                 accent: safeAccent(args.accent),
+                                expanded: rawExpanded === true || rawExpanded === "true",
                             }),
                         },
                     ],
                 };
+            }
             case "list_context_sources": {
                 const doc = parseAgentsMd(AGENTS);
                 const mem = parseFafm(FAFM);

package/dist/transport/http.js

@@ -56,7 +56,7 @@ export function httpApp(root = ROOT) {
         const q = c.req.query();
         const theme = (["light", "dark", "auto"].includes(q.theme ?? "") ? q.theme : "auto");
         c.header("content-type", "text/html; charset=utf-8");
-        return c.body(renderCard(root, { theme, accent: safeAccent(q.accent) }));
+        return c.body(renderCard(root, { theme, accent: safeAccent(q.accent), expanded: q.expand === "all" }));
     });
     // ── Index ───────────────────────────────────────────────────────────
     app.get("/", (c) => c.json({

package/docs/MECHANISMS.md

@@ -29,7 +29,7 @@ Both return:
 ```jsonc
 {
   "name": "mcp-context-card",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "_meta": {
     "io.github.Wolfe-Jam.mcp-context-card/context": {
       "source": "AGENTS.md",

package/docs/card-dark.html

@@ -30,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;box-shadow:var(--card-shadow)}
+  border-radius:14px;overflow:clip;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}
@@ -41,9 +41,31 @@ 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{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0;padding:0;list-style:none}
 .toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
 .toc a:hover{color:var(--accent)}
+/* ── collapsible context ─────────────────────────────────────────── */
+.ctx-nav{position:sticky;top:0;z-index:3;background:var(--card);
+  margin:0 -30px 16px;padding:11px 30px;border-bottom:1px solid var(--line);
+  display:flex;flex-wrap:wrap;align-items:flex-start;gap:8px 16px}
+.xall{margin-left:auto;flex:none;font:inherit;font-size:.76rem;font-weight:600;
+  white-space:nowrap;padding:3px 11px;border-radius:20px;border:1px solid var(--line);
+  background:var(--chip);color:var(--muted);cursor:pointer}
+.xall:hover{color:var(--accent);border-color:var(--accent)}
+.ctx-preamble{padding-bottom:4px}
+details.ctx-section{border-top:1px solid var(--line)}
+details.ctx-section>summary{cursor:pointer;list-style:none;padding:11px 0;
+  font-weight:600;font-size:1rem;letter-spacing:-.01em;display:flex;gap:9px}
+details.ctx-section>summary::-webkit-details-marker{display:none}
+details.ctx-section>summary::before{content:"›";color:var(--accent);font-weight:700;
+  transition:transform .15s ease}
+details.ctx-section[open]>summary::before{transform:rotate(90deg)}
+details.ctx-section>.md{padding:0 0 16px}
+@media print{
+  .ctx-nav{display:none}
+  details.ctx-section:not([open])>.md{display:block!important}
+  details.ctx-section>summary::before{content:""}
+}
 .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}
@@ -78,37 +100,21 @@ 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">v1.0.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">v1.1.1</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
+    <div class="ctx-nav"><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><button type="button" class="xall" hidden>Expand all</button></div>
+    <div class="ctx-preamble 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></div>
+    <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><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
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</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>
+<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><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></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><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></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><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></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><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></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><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></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>
@@ -124,5 +130,25 @@ npm run faf:check     # project.faf / project.fafm / .well-known/fafa still desc
   </section>
   <div class="foot">mcp-context-card · context card</div>
 </main>
+<script>
+(function(){
+  var btn=document.querySelector(".xall");
+  var secs=[].slice.call(document.querySelectorAll("details.ctx-section"));
+  if(!btn||!secs.length)return;
+  var sync=function(){btn.textContent=secs.every(function(d){return d.open})?"Collapse all":"Expand all"};
+  btn.hidden=false;
+  btn.addEventListener("click",function(){
+    var open=!secs.every(function(d){return d.open});
+    secs.forEach(function(d){d.open=open});sync();
+  });
+  secs.forEach(function(d){d.addEventListener("toggle",sync)});
+  var openHash=function(){var d=document.getElementById(location.hash.slice(1));if(d&&d.tagName==="DETAILS")d.open=true};
+  addEventListener("hashchange",openHash);openHash();
+  var pre=[];
+  addEventListener("beforeprint",function(){pre=secs.map(function(d){return d.open});secs.forEach(function(d){d.open=true})});
+  addEventListener("afterprint",function(){secs.forEach(function(d,i){d.open=pre[i]});sync()});
+  sync();
+})();
+</script>
 </body>
 </html>

package/docs/card-light.html

@@ -30,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;box-shadow:var(--card-shadow)}
+  border-radius:14px;overflow:clip;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}
@@ -41,9 +41,31 @@ 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{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0;padding:0;list-style:none}
 .toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
 .toc a:hover{color:var(--accent)}
+/* ── collapsible context ─────────────────────────────────────────── */
+.ctx-nav{position:sticky;top:0;z-index:3;background:var(--card);
+  margin:0 -30px 16px;padding:11px 30px;border-bottom:1px solid var(--line);
+  display:flex;flex-wrap:wrap;align-items:flex-start;gap:8px 16px}
+.xall{margin-left:auto;flex:none;font:inherit;font-size:.76rem;font-weight:600;
+  white-space:nowrap;padding:3px 11px;border-radius:20px;border:1px solid var(--line);
+  background:var(--chip);color:var(--muted);cursor:pointer}
+.xall:hover{color:var(--accent);border-color:var(--accent)}
+.ctx-preamble{padding-bottom:4px}
+details.ctx-section{border-top:1px solid var(--line)}
+details.ctx-section>summary{cursor:pointer;list-style:none;padding:11px 0;
+  font-weight:600;font-size:1rem;letter-spacing:-.01em;display:flex;gap:9px}
+details.ctx-section>summary::-webkit-details-marker{display:none}
+details.ctx-section>summary::before{content:"›";color:var(--accent);font-weight:700;
+  transition:transform .15s ease}
+details.ctx-section[open]>summary::before{transform:rotate(90deg)}
+details.ctx-section>.md{padding:0 0 16px}
+@media print{
+  .ctx-nav{display:none}
+  details.ctx-section:not([open])>.md{display:block!important}
+  details.ctx-section>summary::before{content:""}
+}
 .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}
@@ -78,37 +100,21 @@ 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">v1.0.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">v1.1.1</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
+    <div class="ctx-nav"><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><button type="button" class="xall" hidden>Expand all</button></div>
+    <div class="ctx-preamble 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></div>
+    <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><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
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</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>
+<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><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></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><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></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><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></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><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></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><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></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>
@@ -124,5 +130,25 @@ npm run faf:check     # project.faf / project.fafm / .well-known/fafa still desc
   </section>
   <div class="foot">mcp-context-card · context card</div>
 </main>
+<script>
+(function(){
+  var btn=document.querySelector(".xall");
+  var secs=[].slice.call(document.querySelectorAll("details.ctx-section"));
+  if(!btn||!secs.length)return;
+  var sync=function(){btn.textContent=secs.every(function(d){return d.open})?"Collapse all":"Expand all"};
+  btn.hidden=false;
+  btn.addEventListener("click",function(){
+    var open=!secs.every(function(d){return d.open});
+    secs.forEach(function(d){d.open=open});sync();
+  });
+  secs.forEach(function(d){d.addEventListener("toggle",sync)});
+  var openHash=function(){var d=document.getElementById(location.hash.slice(1));if(d&&d.tagName==="DETAILS")d.open=true};
+  addEventListener("hashchange",openHash);openHash();
+  var pre=[];
+  addEventListener("beforeprint",function(){pre=secs.map(function(d){return d.open});secs.forEach(function(d){d.open=true})});
+  addEventListener("afterprint",function(){secs.forEach(function(d,i){d.open=pre[i]});sync()});
+  sync();
+})();
+</script>
 </body>
 </html>

package/docs/card.html

@@ -30,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;box-shadow:var(--card-shadow)}
+  border-radius:14px;overflow:clip;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}
@@ -41,9 +41,31 @@ 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{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0;padding:0;list-style:none}
 .toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
 .toc a:hover{color:var(--accent)}
+/* ── collapsible context ─────────────────────────────────────────── */
+.ctx-nav{position:sticky;top:0;z-index:3;background:var(--card);
+  margin:0 -30px 16px;padding:11px 30px;border-bottom:1px solid var(--line);
+  display:flex;flex-wrap:wrap;align-items:flex-start;gap:8px 16px}
+.xall{margin-left:auto;flex:none;font:inherit;font-size:.76rem;font-weight:600;
+  white-space:nowrap;padding:3px 11px;border-radius:20px;border:1px solid var(--line);
+  background:var(--chip);color:var(--muted);cursor:pointer}
+.xall:hover{color:var(--accent);border-color:var(--accent)}
+.ctx-preamble{padding-bottom:4px}
+details.ctx-section{border-top:1px solid var(--line)}
+details.ctx-section>summary{cursor:pointer;list-style:none;padding:11px 0;
+  font-weight:600;font-size:1rem;letter-spacing:-.01em;display:flex;gap:9px}
+details.ctx-section>summary::-webkit-details-marker{display:none}
+details.ctx-section>summary::before{content:"›";color:var(--accent);font-weight:700;
+  transition:transform .15s ease}
+details.ctx-section[open]>summary::before{transform:rotate(90deg)}
+details.ctx-section>.md{padding:0 0 16px}
+@media print{
+  .ctx-nav{display:none}
+  details.ctx-section:not([open])>.md{display:block!important}
+  details.ctx-section>summary::before{content:""}
+}
 .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}
@@ -78,37 +100,21 @@ 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">v1.0.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">v1.1.1</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
+    <div class="ctx-nav"><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><button type="button" class="xall" hidden>Expand all</button></div>
+    <div class="ctx-preamble 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></div>
+    <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><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
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</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>
+<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><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></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><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></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><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></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><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></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><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></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>
@@ -124,5 +130,25 @@ npm run faf:check     # project.faf / project.fafm / .well-known/fafa still desc
   </section>
   <div class="foot">mcp-context-card · context card</div>
 </main>
+<script>
+(function(){
+  var btn=document.querySelector(".xall");
+  var secs=[].slice.call(document.querySelectorAll("details.ctx-section"));
+  if(!btn||!secs.length)return;
+  var sync=function(){btn.textContent=secs.every(function(d){return d.open})?"Collapse all":"Expand all"};
+  btn.hidden=false;
+  btn.addEventListener("click",function(){
+    var open=!secs.every(function(d){return d.open});
+    secs.forEach(function(d){d.open=open});sync();
+  });
+  secs.forEach(function(d){d.addEventListener("toggle",sync)});
+  var openHash=function(){var d=document.getElementById(location.hash.slice(1));if(d&&d.tagName==="DETAILS")d.open=true};
+  addEventListener("hashchange",openHash);openHash();
+  var pre=[];
+  addEventListener("beforeprint",function(){pre=secs.map(function(d){return d.open});secs.forEach(function(d){d.open=true})});
+  addEventListener("afterprint",function(){secs.forEach(function(d,i){d.open=pre[i]});sync()});
+  sync();
+})();
+</script>
 </body>
 </html>

package/docs/index.html

@@ -30,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;box-shadow:var(--card-shadow)}
+  border-radius:14px;overflow:clip;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}
@@ -41,9 +41,31 @@ 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{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0;padding:0;list-style:none}
 .toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
 .toc a:hover{color:var(--accent)}
+/* ── collapsible context ─────────────────────────────────────────── */
+.ctx-nav{position:sticky;top:0;z-index:3;background:var(--card);
+  margin:0 -30px 16px;padding:11px 30px;border-bottom:1px solid var(--line);
+  display:flex;flex-wrap:wrap;align-items:flex-start;gap:8px 16px}
+.xall{margin-left:auto;flex:none;font:inherit;font-size:.76rem;font-weight:600;
+  white-space:nowrap;padding:3px 11px;border-radius:20px;border:1px solid var(--line);
+  background:var(--chip);color:var(--muted);cursor:pointer}
+.xall:hover{color:var(--accent);border-color:var(--accent)}
+.ctx-preamble{padding-bottom:4px}
+details.ctx-section{border-top:1px solid var(--line)}
+details.ctx-section>summary{cursor:pointer;list-style:none;padding:11px 0;
+  font-weight:600;font-size:1rem;letter-spacing:-.01em;display:flex;gap:9px}
+details.ctx-section>summary::-webkit-details-marker{display:none}
+details.ctx-section>summary::before{content:"›";color:var(--accent);font-weight:700;
+  transition:transform .15s ease}
+details.ctx-section[open]>summary::before{transform:rotate(90deg)}
+details.ctx-section>.md{padding:0 0 16px}
+@media print{
+  .ctx-nav{display:none}
+  details.ctx-section:not([open])>.md{display:block!important}
+  details.ctx-section>summary::before{content:""}
+}
 .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}
@@ -78,37 +100,21 @@ 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">v1.0.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">v1.1.1</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
+    <div class="ctx-nav"><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><button type="button" class="xall" hidden>Expand all</button></div>
+    <div class="ctx-preamble 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></div>
+    <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><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
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</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>
+<p>CI runs <code>version:check → faf:check → 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>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><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></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><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></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><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></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><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></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><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>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><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></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>
@@ -124,5 +130,25 @@ npm run faf:check     # project.faf / project.fafm / .well-known/fafa still desc
   </section>
   <div class="foot">mcp-context-card · context card</div>
 </main>
+<script>
+(function(){
+  var btn=document.querySelector(".xall");
+  var secs=[].slice.call(document.querySelectorAll("details.ctx-section"));
+  if(!btn||!secs.length)return;
+  var sync=function(){btn.textContent=secs.every(function(d){return d.open})?"Collapse all":"Expand all"};
+  btn.hidden=false;
+  btn.addEventListener("click",function(){
+    var open=!secs.every(function(d){return d.open});
+    secs.forEach(function(d){d.open=open});sync();
+  });
+  secs.forEach(function(d){d.addEventListener("toggle",sync)});
+  var openHash=function(){var d=document.getElementById(location.hash.slice(1));if(d&&d.tagName==="DETAILS")d.open=true};
+  addEventListener("hashchange",openHash);openHash();
+  var pre=[];
+  addEventListener("beforeprint",function(){pre=secs.map(function(d){return d.open});secs.forEach(function(d){d.open=true})});
+  addEventListener("afterprint",function(){secs.forEach(function(d,i){d.open=pre[i]});sync()});
+  sync();
+})();
+</script>
 </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-card",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "mcpName": "io.github.Wolfe-Jam/mcp-context-card",
   "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 ai-catalog.json sibling entries.",
   "keywords": [

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.Wolfe-Jam/mcp-context-card",
   "title": "mcp-context-card",
   "description": "MCP server for a project's context (AGENTS.md), memory, and identity — base or drop-in extension.",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "repository": {
     "url": "https://github.com/Wolfe-Jam/mcp-context-card",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "mcp-context-card",
-      "version": "1.0.1",
+      "version": "1.1.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"