mcp-context-card 0.6.1 → 1.0.0

package/.well-known/fafa

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

@@ -30,10 +30,16 @@ npm run typecheck   # tsc --noEmit over src/ + test/
 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
 ```
 
-CI runs `typecheck → build → test:coverage → demo` on Linux, macOS, and
-Windows for every push and PR to `main` (`.github/workflows/ci.yml`).
+CI runs `version:check → faf:check → typecheck → build → test:coverage → demo`
+on Linux, macOS, and Windows for every push and PR to `main`
+(`.github/workflows/ci.yml`), plus `catalog:check` / `card:check`,
+`faf-cli check project.faf --strict` (the repo dogfoods a `project.faf` —
+this keeps it Trophy), and `faf:nudge` (PR-only, non-blocking — warns if the
+code's shape moved without `project.faf`) on Linux.
 
 ## Layout
 
@@ -77,7 +83,12 @@ fails on any diff.
 
 `npm run typecheck && npm run build && npm test && npm run demo` all green,
 plus `npm run catalog:check` and `npm run card:check` clean if you touched
-`AGENTS.md`, `project.fafm`, or `.well-known/fafa`.
+`AGENTS.md`, `project.fafm`, or `.well-known/fafa`, and `npm run faf:check`
+green if you changed the layout, a dependency, or the identity. On a version
+bump, `npm run version:check` green (it lists every spot that must move
+together) and `project.faf` still Trophy (`faf-cli check project.faf --strict`).
+If CI's `faf:nudge` warns on your PR, reconcile `project.faf` (and re-check
+`project.fafm` facts if `AGENTS.md` moved) or say why it's fine.
 
 ## Authoring this file
 

package/CHANGELOG.md

@@ -2,6 +2,78 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.0.0
+
+Stable surface. No functional change from 0.6.2 — this release declares
+the API settled and is the reference point everything downstream pins to.
+
+The shape that's now stable: **nine tools** (`read_agents_md`,
+`list_agents_md_sections`, `author_agents_md`, `remember`, `recall`,
+`forget`, `whoami`, `list_context_sources`, `render_context_card`),
+**three concerns** (context / memory / identity), **two discovery
+mechanisms** (the Server Card `_meta` block, a self-published
+`ai-catalog.json`), **two transports** (stdio, stateless Streamable HTTP).
+
+Verified against three independent clients before the cut:
+
+- **Cursor** (3.18.25 / Grok 4.6) — the full behavioural matrix, 10/10.
+- **The MCP SDK `Client`** driving the server over stdio — the same
+  client stack a host uses, 10/10, `resources/templates/list` issued
+  directly on the wire.
+- **`@modelcontextprotocol/inspector`** (2.5.0, the canonical
+  conformance tool) — every method answers correctly; `tools/list
+  --strict` reports zero schema-portability problems across all nine.
+
+- `docs/WIRING.md` gains one host-gotcha note: `@modelcontextprotocol/inspector`
+  2.x reports `prompts/list` as `{ "prompts": [] }` — the server declares
+  only `tools` + `resources` and returns `-32601` for `prompts/list` on
+  the wire; the current Inspector CLI masks that as an empty list.
+
+## 0.6.2
+
+Tool-description quality and anti-drift. Nothing here changes what the
+server does — it makes the tool surface read better to a fresh client
+(and to Glama's automated scorer), silences a spurious `-32601`, and
+adds CI gates so the release-hygiene mistakes of 0.5.x/0.6.x can't recur.
+
+- **Every tool parameter now carries a real description.** Glama's
+  automated tool scoring flagged `remember` at 2/5 on parameters —
+  `id` and `text` were bare `{ type: "string" }`, and the non-obvious
+  bit (reusing an `id` replaces that fact in place, it doesn't add a
+  second) was left entirely to inference. `remember` / `recall` /
+  `forget` params now spell out the id semantics, the exact-match
+  lookup, and the update-vs-append behavior. A new test asserts every
+  tool and every tool parameter carries a description over a minimum
+  length — a bare param can't regress back in.
+- **`resources/templates/list` now answers with an empty list instead of
+  `-32601`.** The server declares the `resources` capability, which
+  covers that method; a client calling it (Glama's MCP Inspector does,
+  on connect) was getting method-not-found. There are no templated
+  resources — the Server Card URI is fixed — so it answers `[]`.
+  Regression-tested.
+- **Quality gates added to CI** — all on content already in the repo, no
+  dependency added:
+  - `version:check` (`scripts/check-versions.mjs`) fails on drift between
+    the ~10 version-bearing spots; rides in `prepublishOnly` too.
+  - `faf-cli check project.faf --strict` (pinned) keeps the dogfooded
+    `project.faf` at Trophy — the repo shipped one and never verified it.
+  - `faf:check` (`scripts/check-faf-consistency.mjs`) verifies the
+    mechanically checkable parts of "do the FAF files still describe
+    reality": every `project.faf` `key_files` path exists, every
+    `project.fafm` fact `source:` exists, every `package.json` dependency
+    is named in `tech_stack`, and `.well-known/fafa`'s name/vendor/license
+    agree with `package.json` + `server.json`. Already caught one drift —
+    `@hono/node-server` was a dependency missing from `tech_stack`.
+  - `faf:nudge` (`scripts/faf-drift-nudge.mjs`, PR-only, **non-blocking**)
+    warns when a change moves the code's shape (a `src/` file added,
+    removed, or renamed; a dependency changed) without touching
+    `project.faf` — a prompt to the author, in the PR, while the context
+    is fresh.
+- `project.fafm`'s header no longer claims to be continuously dogfooded —
+  it's a curated snapshot, reviewed at releases. The file is still one of
+  the three real sources the server reads and writes; the comment just
+  stopped overstating how often it's re-etched.
+
 ## 0.6.1
 
 Two real bugs, both caught by the actual `/pubaaif` publish run against

package/README.md

@@ -191,7 +191,7 @@ 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`.
 
-102 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
+104 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.

package/dist/bin.d.ts

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

package/dist/constants.d.ts

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

package/dist/constants.js

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

package/dist/server.js

@@ -16,7 +16,7 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { findSection, parseAgentsMd } from "./agents-md.js";
@@ -70,6 +70,13 @@ export function createServer(root = ROOT) {
             ],
         };
     });
+    // The `resources` capability implies resources/templates/list. There are no
+    // templated resources here (the Server Card URI is fixed), but answer with an
+    // empty list rather than -32601 — a client shouldn't get method-not-found for
+    // something the declared capability covers.
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, async () => ({
+        resourceTemplates: [],
+    }));
     // ── Tools ───────────────────────────────────────────────────────────
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [
@@ -98,28 +105,47 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "remember",
-                description: "Persist a fact past the session boundary — written to a .fafm file, not held in memory.",
+                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",
-                    properties: { id: { type: "string" }, text: { type: "string" } },
+                    properties: {
+                        id: {
+                            type: "string",
+                            description: "A stable key you choose for this fact — pass the same id later to recall or forget it. Exact match, case-sensitive, any string; keep it short and meaningful (e.g. \"deploy-target\", \"db-url\"). Reusing an id updates that fact rather than adding a second one.",
+                        },
+                        text: {
+                            type: "string",
+                            description: "The fact itself, as plain prose. Stored verbatim and returned as-is by recall.",
+                        },
+                    },
                     required: ["id", "text"],
                 },
             },
             {
                 name: "recall",
-                description: "Retrieve a fact stored in a previous session by id.",
+                description: "Retrieve a fact stored in a previous session by id. Exact lookup — not fuzzy or substring.",
                 inputSchema: {
                     type: "object",
-                    properties: { id: { type: "string" } },
+                    properties: {
+                        id: {
+                            type: "string",
+                            description: "The exact id a previous remember call used. Returns the stored text, or a \"no memory for <id>\" message if nothing matches.",
+                        },
+                    },
                     required: ["id"],
                 },
             },
             {
                 name: "forget",
-                description: "Remove a fact by id — to correct or drop something stale.",
+                description: "Remove a fact by id — to correct or drop something stale. A missing id is reported, not an error.",
                 inputSchema: {
                     type: "object",
-                    properties: { id: { type: "string" } },
+                    properties: {
+                        id: {
+                            type: "string",
+                            description: "The exact id of the fact to remove. Reports whether a fact was actually removed.",
+                        },
+                    },
                     required: ["id"],
                 },
             },

package/docs/MECHANISMS.md

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

package/docs/WIRING.md

@@ -33,6 +33,10 @@
   the arg — e.g. `command: "node"`, `args: ["/path/to/node_modules/mcp-context-card/dist/bin.js"]`
   (or wherever `npm install -g` / your package manager put it; find it with
   `npm root -g` or `which mcp-context-card` after a global install).
+- **`@modelcontextprotocol/inspector` 2.x reports `prompts/list` as `{ "prompts": [] }`** —
+  this server declares only `tools` + `resources`, so `prompts/list` returns
+  `-32601` on the wire; the current Inspector CLI masks that as an empty list
+  (raw JSON-RPC, or Inspector 0.21.x, shows the real `-32601`).
 
 ### Streamable HTTP (remote)
 

package/docs/card-dark.html

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v0.6.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.0.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -93,8 +93,10 @@ npm run typecheck   # tsc --noEmit over src/ + test/</code></pre>
 <h2 id="test">Test</h2>
 <pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
-npm run demo          # end to end: all tools over stdio, then over stateless HTTP</code></pre>
-<p>CI runs <code>typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>).</p>
+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>
@@ -104,7 +106,7 @@ npm run demo          # end to end: all tools over stdio, then over stateless HT
 <h2 id="safety">Safety</h2>
 <ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul>
 <h2 id="definition-of-done">Definition of done</h2>
-<p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>.</p>
+<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>
   </section>

package/docs/card-light.html

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v0.6.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.0.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -93,8 +93,10 @@ npm run typecheck   # tsc --noEmit over src/ + test/</code></pre>
 <h2 id="test">Test</h2>
 <pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
-npm run demo          # end to end: all tools over stdio, then over stateless HTTP</code></pre>
-<p>CI runs <code>typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>).</p>
+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>
@@ -104,7 +106,7 @@ npm run demo          # end to end: all tools over stdio, then over stateless HT
 <h2 id="safety">Safety</h2>
 <ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul>
 <h2 id="definition-of-done">Definition of done</h2>
-<p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>.</p>
+<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>
   </section>

package/docs/card.html

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v0.6.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.0.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -93,8 +93,10 @@ npm run typecheck   # tsc --noEmit over src/ + test/</code></pre>
 <h2 id="test">Test</h2>
 <pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
-npm run demo          # end to end: all tools over stdio, then over stateless HTTP</code></pre>
-<p>CI runs <code>typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>).</p>
+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>
@@ -104,7 +106,7 @@ npm run demo          # end to end: all tools over stdio, then over stateless HT
 <h2 id="safety">Safety</h2>
 <ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul>
 <h2 id="definition-of-done">Definition of done</h2>
-<p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>.</p>
+<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>
   </section>

package/docs/index.html

@@ -78,7 +78,7 @@ section:last-child{border-bottom:0}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v0.6.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.0.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -93,8 +93,10 @@ npm run typecheck   # tsc --noEmit over src/ + test/</code></pre>
 <h2 id="test">Test</h2>
 <pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
-npm run demo          # end to end: all tools over stdio, then over stateless HTTP</code></pre>
-<p>CI runs <code>typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>).</p>
+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>
@@ -104,7 +106,7 @@ npm run demo          # end to end: all tools over stdio, then over stateless HT
 <h2 id="safety">Safety</h2>
 <ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul>
 <h2 id="definition-of-done">Definition of done</h2>
-<p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>.</p>
+<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>
   </section>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-card",
-  "version": "0.6.1",
+  "version": "1.0.0",
   "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": [
@@ -45,7 +45,10 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "prepublishOnly": "npm run clean && npm run build && npm run typecheck && npm test",
+    "version:check": "node scripts/check-versions.mjs",
+    "faf:check": "node scripts/check-faf-consistency.mjs",
+    "faf:nudge": "node scripts/faf-drift-nudge.mjs",
+    "prepublishOnly": "npm run clean && npm run version:check && npm run faf:check && npm run build && npm run typecheck && npm test",
     "start": "node dist/bin.js",
     "start:http": "node dist/bin.js --http",
     "dev": "tsx src/bin.ts",

package/project.faf

@@ -17,7 +17,7 @@ stack:
   connection: slotignored  # no database
   hosting: Docker / any Node host — stdio for local, stateless Streamable HTTP for remote
   cicd: GitHub Actions — typecheck + build + test:coverage + demo on 3 OSes; catalog:check + card:check on Linux
-tech_stack: [TypeScript, "@modelcontextprotocol/sdk", "agents-md-facts", hono, yaml]
+tech_stack: [TypeScript, "@modelcontextprotocol/sdk", "agents-md-facts", hono, "@hono/node-server", yaml]
 human_context:
   who: MCP host and server implementers who want a project's AGENTS.md, memory, and identity available over MCP without inventing an ad-hoc shape for each.
   what: The essential context, memory, and identity components for MCP — usable as a base MCP on its own, or dropped into any existing MCP server as an extension. Nine tools — read_agents_md / list_agents_md_sections / author_agents_md (context), remember / recall / forget (memory), whoami (identity), list_context_sources / render_context_card (discovery) — exposed through the Server Card _meta block and a self-published ai-catalog.json. Dual transport (stdio + stateless Streamable HTTP).

package/project.fafm

@@ -1,8 +1,9 @@
 # application/vnd.fafm+yaml — mcp-context-card project memory
-# Real, dogfooded memory about this repo's own build — not a static example.
-# This file itself is one of the three sources the server exposes:
-# `remember` / `recall` read and write it, and the demo proves a fact
-# survives a full server-process restart (then restores this file exactly).
+# A curated snapshot of what this repo knows about itself: real facts with
+# real sources, reviewed at releases rather than continuously re-etched.
+# This exact file is one of the three sources the server exposes — `remember`
+# / `recall` read and write it, and the demo proves a fact survives a full
+# server-process restart (then restores this file exactly).
 version: "1.1"
 profile: "knowledge"
 namepoint: "@mcp-context-card:public"

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": "0.6.1",
+  "version": "1.0.0",
   "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": "0.6.1",
+      "version": "1.0.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"