mcp-context-card 1.4.0 → 1.6.0

package/dist/render-card.js

@@ -14,7 +14,7 @@ import { basename, join, resolve } from "node:path";
 import { parseAgentsMd } from "./agents-md.js";
 import { parseFafm } from "./memory.js";
 import { resolveIdentity, serverCardMeta, META_NS } from "./identity.js";
-import { SERVER_CARD_URI } from "./constants.js";
+import { PUBLISH_MEMORY_ENV, SERVER_CARD_URI } from "./constants.js";
 import { escapeHtml, renderInline, renderMarkdown, slug } from "./md.js";
 /** AAIF brand orange (aaif.io). The default accent. */
 export const AAIF_ACCENT = "#FF702D";
@@ -23,48 +23,137 @@ export function safeAccent(a) {
     return a && ACCENT_OK.test(a) ? a : AAIF_ACCENT;
 }
 const CSS = (accent) => `
+/* The page and the card are themed independently. The page follows the
+   viewer's OS. The card is the owner's choice: body[data-theme] (light | dark;
+   none = follow the OS), and the reader can switch it with the ◐ toggle (#ink). */
 :root{
   --accent:${accent};
-  --bg:#f4f4f5; --card:#fff; --fg:#0a0a0a; --muted:#6b6b70;
-  --line:rgba(0,0,0,.09); --chip:rgba(0,0,0,.05);
-  --card-shadow:0 1px 3px rgba(0,0,0,.06), 0 12px 32px rgba(0,0,0,.10);
+  --page-bg:#f4f4f5;--page-muted:#6b6b70;--page-line:rgba(0,0,0,.09);--page-chip:rgba(0,0,0,.05);
 }
-:root[data-theme="dark"]{
-  --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
-  --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
-  --card-shadow:0 0 0 1px rgba(255,255,255,.16),
-    0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
+@media (prefers-color-scheme:dark){
+  :root{--page-bg:#000;--page-muted:#9a9aa0;--page-line:rgba(255,255,255,.13);--page-chip:rgba(255,255,255,.07)}
 }
+.bcard{--card:#fff;--fg:#0a0a0a;--muted:#6b6b70;--line:rgba(0,0,0,.09);--chip:rgba(0,0,0,.05);--card-shadow:0 1px 3px rgba(0,0,0,.06),0 12px 32px rgba(0,0,0,.10)}
+body[data-theme="dark"] .bcard,
+body[data-theme="light"] #ink:checked~.stage .bcard{--card:#0d0d0d;--fg:#fafafa;--muted:#9a9aa0;--line:rgba(255,255,255,.13);--chip:rgba(255,255,255,.07);--card-shadow:0 0 0 1px rgba(255,255,255,.16),0 8px 40px color-mix(in srgb,var(--accent) 20%,transparent)}
+body[data-theme="dark"] #ink:checked~.stage .bcard{--card:#fff;--fg:#0a0a0a;--muted:#6b6b70;--line:rgba(0,0,0,.09);--chip:rgba(0,0,0,.05);--card-shadow:0 1px 3px rgba(0,0,0,.06),0 12px 32px rgba(0,0,0,.10)}
 @media (prefers-color-scheme:dark){
-  :root:not([data-theme="light"]){
-    --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
-    --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
-    --card-shadow:0 0 0 1px rgba(255,255,255,.16),
-      0 8px 40px color-mix(in srgb, var(--accent) 20%, transparent);
-  }
+  body:not([data-theme]) .bcard{--card:#0d0d0d;--fg:#fafafa;--muted:#9a9aa0;--line:rgba(255,255,255,.13);--chip:rgba(255,255,255,.07);--card-shadow:0 0 0 1px rgba(255,255,255,.16),0 8px 40px color-mix(in srgb,var(--accent) 20%,transparent)}
+  body:not([data-theme]) #ink:checked~.stage .bcard{--card:#fff;--fg:#0a0a0a;--muted:#6b6b70;--line:rgba(0,0,0,.09);--chip:rgba(0,0,0,.05);--card-shadow:0 1px 3px rgba(0,0,0,.06),0 12px 32px rgba(0,0,0,.10)}
+}
+@media (prefers-color-scheme:light){
+  body:not([data-theme]) #ink:checked~.stage .bcard{--card:#0d0d0d;--fg:#fafafa;--muted:#9a9aa0;--line:rgba(255,255,255,.13);--chip:rgba(255,255,255,.07);--card-shadow:0 0 0 1px rgba(255,255,255,.16),0 8px 40px color-mix(in srgb,var(--accent) 20%,transparent)}
 }
+.bcard{color:var(--fg)}
 *{box-sizing:border-box}
-body{margin:0;background:var(--bg);color:var(--fg);
+body{margin:0;background:var(--page-bg);color:var(--page-muted);
   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: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}
+  padding:40px 16px}
+/* ── the business card: two faces, flip, two views ─────────────────── */
+.sr{position:absolute;width:1px;height:1px;margin:-1px;overflow:hidden;clip:rect(0 0 0 0);white-space:nowrap}
+.stage{max-width:760px;margin:0 auto}
+.views{display:flex;justify-content:flex-end;margin:0 0 10px}
+.view,.hint label{cursor:pointer}
+.view{font-size:.78rem;font-weight:600;padding:3px 11px;border-radius:20px;border:1px solid var(--page-line);
+  background:var(--page-chip);color:var(--page-muted);letter-spacing:.2em}
+.views{gap:8px}
+.view:hover,.hint label:hover{color:var(--accent);border-color:var(--accent)}
+.bcard{margin:0 auto;width:100%;aspect-ratio:7/4;perspective:1600px}
+#portrait:checked~.stage{max-width:480px}
+#portrait:checked~.stage .bcard{aspect-ratio:4/7}
+.faces{position:relative;width:100%;height:100%;transform-style:preserve-3d;transition:transform .6s ease}
+#flip:checked~.stage .faces{transform:rotateY(180deg)}
+.face{position:absolute;inset:0;background:var(--card);border:1px solid var(--line);border-radius:16px;
+  box-shadow:var(--card-shadow);backface-visibility:hidden;-webkit-backface-visibility:hidden;overflow:hidden}
+.back{transform:rotateY(180deg) translateZ(1px);display:flex;flex-direction:column}
+/* The face turned away takes no pointer or wheel events, so the visible face
+   scrolls (a hidden backface can still win hit-testing, notably in Chrome/Safari on macOS). */
+#flip:checked~.stage .front,#flip:not(:checked)~.stage .back{pointer-events:none;visibility:hidden;transition:visibility 0s .3s}
+#flip:checked~.stage .back,#flip:not(:checked)~.stage .front{visibility:visible;transition:visibility 0s .3s}
+.panes{overscroll-behavior:contain;-webkit-overflow-scrolling:touch}
+.front{display:flex;flex-direction:column;justify-content:center;padding:34px 44px;
+  border-top:5px solid var(--accent);
+  background:linear-gradient(135deg,color-mix(in srgb,var(--accent) 10%,var(--card)) 0%,var(--card) 55%)}
+.front .id{max-width:34em}
+h1{margin:0;font-size:2.1rem;line-height:1.15;letter-spacing:-.025em}
+.title{margin:8px 0 0;font-size:.82rem;font-weight:700;letter-spacing:.14em;text-transform:uppercase;color:var(--accent)}
+.oneliner{margin:16px 0 0;font-size:1.05rem;color:var(--muted);line-height:1.5}
+.foot-front{position:absolute;left:44px;right:130px;bottom:22px;display:flex;flex-wrap:wrap;align-items:center;gap:6px 12px}
+.domain{font:.8rem ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted)}
+.corner{position:absolute;width:30px;height:30px;border-radius:50%;display:grid;place-items:center;
+  cursor:pointer;font-weight:700;font-size:.9rem;color:var(--muted);background:var(--chip);border:1px solid var(--line);z-index:4}
+.corner:hover{color:var(--accent);border-color:var(--accent)}
+.corner.tr{top:16px;right:16px;font-family:Georgia,serif;font-style:italic}
+.logo{position:absolute;top:34px;left:44px;width:84px;height:84px;border-radius:50%;display:grid;place-items:center;
+  color:#fff;font-weight:800;font-size:2rem;letter-spacing:-.02em;line-height:1;
+  background:radial-gradient(circle at 30% 25%,color-mix(in srgb,var(--accent) 80%,#fff),var(--accent) 45%,color-mix(in srgb,var(--accent) 50%,#000));
+  box-shadow:0 0 0 3px var(--card),0 0 0 4px color-mix(in srgb,var(--accent) 45%,transparent),0 6px 20px color-mix(in srgb,var(--accent) 30%,transparent)}
+.front .id{margin-top:70px}
+.corner.br{bottom:16px;right:16px}
+.flipbtn{position:absolute;right:18px;bottom:16px;z-index:4;cursor:pointer;width:42px;height:42px;border-radius:50%;
+  display:grid;place-items:center;color:var(--fg);background:transparent;box-shadow:inset 0 0 0 2px var(--fg);
+  transition:transform .2s ease}
+.flipbtn span{font-size:1.3rem;line-height:1;font-weight:700}
+
+/* the back's button: same spot and outline as the front's; ↺ instead of ↻. Over
+   scrolling text it takes the card's colour, so the arrow stays readable. */
+.flipbtn.back-btn{background:var(--card)}
+/* fast tooltip: shows at once on hover or keyboard focus (a title tooltip waits ~1 s) */
+.flipbtn[data-tip]::after{content:attr(data-tip);position:absolute;right:0;bottom:calc(100% + 8px);white-space:nowrap;
+  font:600 .74rem/1 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;letter-spacing:0;padding:6px 9px;border-radius:7px;
+  color:var(--card);background:var(--fg);opacity:0;transform:translateY(3px);pointer-events:none;transition:opacity .08s,transform .08s}
+.flipbtn[data-tip]:hover::after,#flip:focus-visible~.stage .flipbtn[data-tip]::after{opacity:1;transform:none}
+.flipbtn:hover{transform:none}.flipbtn:hover span{transform:rotate(-25deg)}.flipbtn span{transition:transform .2s ease}
+.whatis{position:absolute;top:16px;right:16px;z-index:5}
+.whatis>summary{position:static;list-style:none}
+.whatis>summary::-webkit-details-marker{display:none}
+.whatis[open]>summary{color:var(--accent);border-color:var(--accent)}
+.whatis-panel{position:absolute;right:0;top:38px;width:min(320px,70vw);padding:14px 16px;border-radius:12px;
+  background:var(--card);border:1px solid var(--line);box-shadow:var(--card-shadow);font-size:.84rem;line-height:1.5}
+.whatis-panel p{margin:0 0 8px}.whatis-head{font-weight:800;color:var(--accent);letter-spacing:-.01em;font-size:.95rem}
+.whatis-foot{color:var(--muted);margin:0!important}.whatis-panel code{font:.86em ui-monospace,SFMono-Regular,Menlo,monospace}
+.tabbar{display:flex;flex-wrap:wrap;gap:4px;padding:14px 60px 0 18px;border-bottom:1px solid var(--line);border-top:5px solid var(--accent)}
+.tabbar label{cursor:pointer;font-size:.8rem;font-weight:600;color:var(--muted);padding:6px 11px;border-radius:8px 8px 0 0}
+.tabbar label:hover{color:var(--fg)}
+.panes{flex:1;overflow:auto;padding:20px 26px 72px}
+.pane{display:none}
+.lead{margin:0 0 14px;font-size:1rem;line-height:1.6}
+.kv{border-collapse:collapse;font-size:.86rem;width:100%}
+.kv th{text-align:left;font-weight:600;color:var(--muted);padding:6px 14px 6px 0;white-space:nowrap;vertical-align:top}
+.kv td{padding:6px 0;border-bottom:1px solid var(--line)}
+.kv code,.lead code{font:.86em ui-monospace,SFMono-Regular,Menlo,monospace}
+.hint{text-align:center;color:var(--page-muted);font-size:.78rem;margin:14px 0 0}
+.hint label{color:var(--accent)}
+#flip:focus-visible~.stage .flipbtn,#portrait:focus-visible~.stage .view[for=portrait],#ink:focus-visible~.stage .view[for=ink]{outline:2px solid var(--accent);outline-offset:2px}
+@media (max-width:640px){
+  .bcard,#portrait:checked~.stage .bcard{aspect-ratio:auto;height:min(78vh,720px)}
+  .front{padding:28px 26px}.foot-front{left:26px}
+  .logo{top:24px;left:26px;width:64px;height:64px;font-size:1.5rem}.front .id{margin-top:56px}
+  h1{font-size:1.7rem}
+}
+/* flat: expanded render and print — both faces, every tab, no flip */
+.flat .faces,.flat .face{position:static;transform:none!important;height:auto}
+.flat .bcard{aspect-ratio:auto;perspective:none}
+.flat .face{margin:0 0 18px}.flat .front{min-height:260px;position:relative}
+.flat .pane{display:block;margin:0 0 22px}.flat .bcard{color:var(--fg)}.flat .tabbar,.flat .views,.flat .hint,.flat .corner,.flat .flipbtn,.flat .whatis{display:none}
+.flat .panes{overflow:visible}
+@media print{
+  .faces,.face{position:static!important;transform:none!important;height:auto!important}
+  .bcard{aspect-ratio:auto!important}.face{margin:0 0 18px;box-shadow:none}
+  .pane{display:block!important;margin:0 0 22px}.tabbar,.views,.hint,.corner,.flipbtn,.whatis{display:none!important}
+  .panes{overflow:visible}
+}
 .pills{display:flex;flex-wrap:wrap;gap:6px}
 .pill{font-size:.74rem;font-weight:600;padding:3px 9px;border-radius:20px;background:var(--chip);color:var(--muted)}
 .pill.accent{background:color-mix(in srgb,var(--accent) 16%,transparent);color:var(--accent)}
-section{border-bottom:1px solid var(--line)}
-section:last-child{border-bottom:0}
 .label{font-size:.7rem;font-weight:700;letter-spacing:.16em;text-transform:uppercase;
   color:var(--accent);margin:0 0 14px}
 .toc{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0;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);
+.ctx-nav{position:sticky;top:-20px;z-index:3;background:var(--card);
+  margin:0 -26px 16px;padding:11px 26px;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);
@@ -110,29 +199,74 @@ details.ctx-section>.md{padding:0 0 16px}
 .disc code{font:.86em ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted)}
 .fetch{margin:14px 0 0;font-size:.82rem;color:var(--muted)}
 .fetch code{background:var(--chip);padding:1px 5px;border-radius:5px}
-.foot{color:var(--muted);font-size:.78rem;text-align:center;border-top:1px solid var(--line)}
 .none{color:var(--muted);font-style:italic}
 `;
 const htmlAttr = (theme) => theme === "auto" ? "" : ` data-theme="${theme}"`;
+/** What the front calls this thing, from where it runs: "MCP server", "A2A agent", or both. */
+export function cardKind(id) {
+    const kinds = [];
+    const protocols = new Set((id?.endpoints ?? []).map((e) => e.protocol));
+    if (protocols.has("a2a"))
+        kinds.push("A2A agent");
+    if (protocols.has("mcp") || (id?.packages ?? []).length)
+        kinds.push("MCP server");
+    return kinds;
+}
+/** The front's title line: what it is, then its version. Empty when nothing is known. */
+export function cardTitle(id) {
+    return [cardKind(id).join(" · "), id?.agentVersion ? `v${id.agentVersion}` : ""].filter(Boolean).join(" · ");
+}
+/** The front's logo: the first letters of the name's first two words ("mcp-context-card" → "MC"). */
+export function cardInitials(name) {
+    const words = name.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    return words
+        .slice(0, 2)
+        .map((w) => Array.from(w)[0].toUpperCase())
+        .join("");
+}
+/** The front's one-liner: the first sentence of the description. */
+export function cardOneLiner(id, max = 140) {
+    const d = id?.description;
+    if (!d)
+        return "";
+    const first = clip(d, max);
+    if (!first.endsWith("…"))
+        return first;
+    // A long first sentence: stop at its first natural pause (— ; :) when that
+    // still says something, rather than cutting a phrase in half.
+    const pause = /\s[—–]\s|;\s|:\s/.exec(d);
+    return pause && pause.index >= 40 && pause.index <= max ? d.slice(0, pause.index).trim() : first;
+}
+/** The project's card: read its files, then draw. */
 export function renderCard(root, opts = {}) {
-    const theme = opts.theme ?? "auto";
-    const accent = safeAccent(opts.accent);
+    return renderBusinessCard(readCard(root, opts), opts);
+}
+/** The (i) panel for an agent or server card. */
+const AGENT_ABOUT = `<p class="whatis-head">Business Cards for Agents</p>
+            <p>This is the public card of an AI agent or MCP server: who it is, what it does, where to reach it. Flip it for the detail.</p>
+            <p>People read it here. Machines read the same facts from its MCP Server Card and AI Catalog, before they ever connect.</p>
+            <p class="whatis-foot">Made with <code>mcp-context-card</code></p>`;
+/** Read a project's AGENTS.md, memory and identity into a business card. */
+export function readCard(root, opts = {}) {
+    const flat = !!opts.expanded;
     const agents = parseAgentsMd(join(root, "AGENTS.md"));
     const mem = parseFafm(join(root, "project.fafm"));
     const id = resolveIdentity(root);
     const meta = serverCardMeta();
     const name = id?.displayName ?? id?.name ?? basename(resolve(root));
-    const pills = [
-        id?.vendor && id.vendor !== id.status && `<span class="pill">${escapeHtml(id.vendor)}</span>`,
-        id?.agentVersion && `<span class="pill">v${escapeHtml(id.agentVersion)}</span>`,
-        id?.status && `<span class="pill accent">${escapeHtml(id.status)}</span>`,
-        id?.license && `<span class="pill">${escapeHtml(id.license)}</span>`,
-    ]
-        .filter(Boolean)
-        .join("");
-    // 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 title = cardTitle(id);
+    const oneLiner = cardOneLiner(id);
+    const domain = /^urn:air:([^:]+):/i.exec(id?.id ?? "")?.[1];
+    // The version rides in the title line, so the front's chips skip it.
+    const chips = [
+        id?.vendor && id.vendor !== id.status ? { text: id.vendor } : null,
+        !title && id?.agentVersion ? { text: `v${id.agentVersion}` } : null,
+        id?.status ? { text: id.status, accent: true } : null,
+        id?.license ? { text: id.license } : null,
+    ].filter((c) => !!c);
+    // CONTEXT — one <details> per AGENTS.md section, collapsed by default;
+    // `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
@@ -142,29 +276,53 @@ export function renderCard(root, opts = {}) {
     const preamble = [agents?.preamble, agents?.sections.find((s) => s.level === 1)?.body ?? ""]
         .filter(Boolean)
         .join("\n\n");
-    const openAttr = opts.expanded ? " open" : "";
+    const openAttr = flat ? " 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
         ? `<div class="ctx-nav">${toc}${bodySections.length
-            ? `<button type="button" class="xall" hidden>${opts.expanded ? "Collapse all" : "Expand all"}</button>`
+            ? `<button type="button" class="xall" hidden>${flat ? "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 yet. Ask your agent to draft one: <code>author_agents_md</code> builds it from this repo's real build and test commands, nothing invented.</p>`;
     // MEMORY
-    const memoryBody = mem.facts.length
-        ? mem.facts
-            .map((f) => {
-            const verified = f.verification_status === "verified";
-            const tags = (f.tags ?? [])
-                .map((t) => `<span class="tag">${escapeHtml(t)}</span>`)
-                .join("");
-            return `<div class="fact"><p>${renderInline(f.text)}</p><div class="meta">${tags}<span class="dot${verified ? "" : " pending"}" title="${verified ? "verified" : f.verification_status ?? "unverified"}"></span></div></div>`;
-        })
-            .join("")
-        : `<p class="none">No facts yet. Ask your agent to remember something, and it lands here.</p>`;
+    const memLabel = `${mem.facts.length} fact${mem.facts.length === 1 ? "" : "s"}${opts.memory === "private" && mem.facts.length ? ", kept private" : ""}`;
+    const memoryBody = opts.memory === "private" && mem.facts.length
+        ? `<p class="none">Kept private on this page. To show the facts, set <code>${PUBLISH_MEMORY_ENV}=1</code>.</p>`
+        : mem.facts.length
+            ? mem.facts
+                .map((f) => {
+                const verified = f.verification_status === "verified";
+                const tags = (f.tags ?? [])
+                    .map((t) => `<span class="tag">${escapeHtml(t)}</span>`)
+                    .join("");
+                return `<div class="fact"><p>${renderInline(f.text)}</p><div class="meta">${tags}<span class="dot${verified ? "" : " pending"}" title="${verified ? "verified" : f.verification_status ?? "unverified"}"></span></div></div>`;
+            })
+                .join("")
+            : `<p class="none">No facts yet. Ask your agent to remember something, and it lands here.</p>`;
+    // ABOUT — the identity, in full
+    const aboutRows = [
+        id?.id && ["Agent ID", `<code>${escapeHtml(id.id)}</code>`],
+        id?.vendor && ["Publisher", escapeHtml(id.vendor)],
+        id?.agentVersion && ["Version", `v${escapeHtml(id.agentVersion)}`],
+        id?.status && ["Status", escapeHtml(id.status)],
+        id?.license && ["License", escapeHtml(id.license)],
+        ...(id?.endpoints ?? []).map((e) => [
+            e.protocol === "a2a" ? "A2A endpoint" : e.protocol === "mcp" ? "MCP endpoint" : escapeHtml(e.protocol),
+            e.location ? `<code>${escapeHtml(e.location)}</code>` : "—",
+        ]),
+        ...(id?.packages ?? []).map((pk) => [`Package (${escapeHtml(pk.registryType)})`, `<code>${escapeHtml(pk.identifier)}</code>`]),
+    ].filter(Boolean);
+    const aboutBody = `${id?.description ? `<p class="lead">${escapeHtml(id.description)}</p>` : `<p class="none">No description yet. <code>npx faf-cli card init</code> writes one into the project's <code>.fafa</code>.</p>`}${aboutRows.length
+        ? `<table class="kv"><tbody>${aboutRows.map(([k, v]) => `<tr><th>${k}</th><td>${v}</td></tr>`).join("")}</tbody></table>`
+        : ""}`;
+    // SKILLS — only when the .fafa lists capabilities
+    const skills = id?.skills ?? [];
+    const skillsBody = skills
+        .map((sk) => `<div class="fact"><p><b>${escapeHtml(sk.name)}</b>${sk.description ? ` — ${escapeHtml(sk.description)}` : ""}</p></div>`)
+        .join("");
     // DISCOVERY
     const rows = Object.entries(meta)
         .map(([k, v]) => {
@@ -172,63 +330,129 @@ export function renderCard(root, opts = {}) {
         return `<tr><td>${concern}</td><td><code>${escapeHtml(v.source)}</code></td><td><code>${escapeHtml(v.mediaType)}</code></td></tr>`;
     })
         .join("");
+    const discoveryBody = `<table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody>${rows}</tbody></table>
+    <p class="fetch">A machine reads this over <b>MCP</b> from the
+      <code>${escapeHtml(SERVER_CARD_URI)}</code> resource; over <b>HTTP</b> also
+      from <code>GET /mcp/server-card</code> and
+      <code>GET /.well-known/ai-catalog.json</code>.</p>`;
+    // The back: tabs (CSS radios; every pane shows when flat or printed).
+    // [key, tab label, pane heading, body]
+    const tabs = [
+        ["about", "About", "About", aboutBody],
+        ...(skills.length
+            ? [["skills", "Skills", `Skills — ${skills.length}`, skillsBody]]
+            : []),
+        ["context", "Context", "Context — AGENTS.md", contextBody],
+        ["memory", "Memory", `Memory — ${memLabel}`, memoryBody],
+        ["discovery", "Discovery", "Discovery", discoveryBody],
+    ];
+    return {
+        name,
+        title,
+        oneLiner,
+        domain,
+        chips,
+        tabs: tabs.map(([key, label, heading, html]) => ({ key, label, heading, html })),
+        about: AGENT_ABOUT,
+    };
+}
+/** Draw any business card as one self-contained HTML page. */
+export function renderBusinessCard(card, opts = {}) {
+    const theme = opts.theme ?? "auto";
+    const accent = safeAccent(opts.accent);
+    const portrait = opts.layout === "portrait";
+    const flat = !!opts.expanded;
+    const { name, title, oneLiner, domain } = card;
+    const tabs = card.tabs.map((t) => ({ ...t, key: t.key.replace(/[^a-z0-9-]/gi, "").toLowerCase() || "tab" }));
+    const pills = card.chips
+        .map((c) => `<span class="pill${c.accent ? " accent" : ""}">${escapeHtml(c.text)}</span>`)
+        .join("");
+    const radios = tabs
+        .map((t, i) => `<input type="radio" name="tab" id="t-${t.key}" class="sr"${i === 0 ? " checked" : ""}>`)
+        .join("");
+    const tabbar = tabs.map((t) => `<label for="t-${t.key}">${escapeHtml(t.label)}</label>`).join("");
+    const panes = tabs
+        .map((t) => `<div class="pane p-${t.key}"><p class="label">${escapeHtml(t.heading)}</p>${t.html}</div>`)
+        .join("");
+    // One CSS rule pair per tab: its pane shows, its label lights, when its radio is checked.
+    const tabCss = tabs
+        .map((t) => `#t-${t.key}:checked~.panes .p-${t.key}{display:block}#t-${t.key}:checked~.tabbar label[for=t-${t.key}]{color:var(--accent);background:var(--chip)}`)
+        .join("");
+    // The (i) panel: the same control, in the same spot, on both faces.
+    const WHATIS = `<details class="whatis">
+          <summary class="corner tr" title="About this card" aria-label="About this card">i</summary>
+          <div class="whatis-panel">
+            ${card.about}
+          </div>
+        </details>`;
     return `<!doctype html>
-<html lang="en"${htmlAttr(theme)}>
+<html lang="en">
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width,initial-scale=1">
-<title>${escapeHtml(name)} — context card</title>
-<style>${CSS(accent)}</style>
+<title>${escapeHtml(name)} — business card</title>
+<style>${CSS(accent)}${tabCss}</style>
 </head>
-<body>
-<main class="card">
-  <div class="top">
-    <h1>${escapeHtml(name)}</h1>
-    ${pills ? `<div class="pills">${pills}</div>` : ""}
-  </div>
-  <section>
-    <p class="label">Context — AGENTS.md</p>
-    ${contextBody}
-  </section>
-  <section>
-    <p class="label">Memory — ${mem.facts.length} fact${mem.facts.length === 1 ? "" : "s"}</p>
-    ${memoryBody}
-  </section>
-  <section>
-    <p class="label">Discovery</p>${id?.id ? `\n    <p class="fetch">Agent ID <code>${escapeHtml(id.id)}</code></p>` : ""}
-    <table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody>${rows}</tbody></table>
-    <p class="fetch">A machine reads this over <b>MCP</b> from the
-      <code>${escapeHtml(SERVER_CARD_URI)}</code> resource; over <b>HTTP</b> also
-      from <code>GET /.well-known/mcp/server-card</code> and
-      <code>GET /.well-known/ai-catalog.json</code>.</p>
-  </section>
-  <div class="foot">${escapeHtml(name)} · context card</div>
-</main>
-${bodySections.length ? TOGGLE_SCRIPT : ""}
+<body${flat ? ` class="flat"` : ""}${htmlAttr(theme)}>
+<input type="checkbox" id="flip" class="sr" aria-label="Flip the card">
+<input type="checkbox" id="ink" class="sr" aria-label="Switch the card between light and dark">
+<input type="checkbox" id="portrait" class="sr" aria-label="Portrait view"${portrait ? " checked" : ""}>
+<div class="stage">
+  <div class="views"><label for="ink" class="view" title="Card: light or dark">◐</label><label for="portrait" class="view" title="Landscape or portrait">▭ ▯</label></div>
+  <main class="bcard">
+    <div class="faces">
+      <section class="face front">
+        <div class="logo" aria-hidden="true">${escapeHtml(cardInitials(name))}</div>
+        ${WHATIS}
+        <div class="id">
+          <h1>${escapeHtml(name)}</h1>
+          ${title ? `<p class="title">${escapeHtml(title)}</p>` : ""}
+          ${oneLiner ? `<p class="oneliner">${escapeHtml(oneLiner)}</p>` : ""}
+        </div>
+        <div class="foot-front">${domain ? `<span class="domain">${escapeHtml(domain)}</span>` : ""}${pills ? `<div class="pills">${pills}</div>` : ""}</div>
+        <label for="flip" class="flipbtn" data-tip="Flip the card" aria-label="Flip the card"><span aria-hidden="true">↻</span></label>
+      </section>
+      <section class="face back">
+        ${radios}
+        ${WHATIS}
+        <div class="tabbar">${tabbar}</div>
+        <div class="panes">${panes}</div>
+        <label for="flip" class="flipbtn back-btn" data-tip="Flip back" aria-label="Flip back"><span aria-hidden="true">↺</span></label>
+      </section>
+    </div>
+  </main>
+  <p class="hint">${escapeHtml(name)} · business card · <label for="flip">flip it over</label></p>
+</div>
+${CARD_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.
+ * The card's only script — a progressive enhancement. Flip, tabs and the view
+ * toggle are CSS (checkbox and radio inputs) and work without it. It adds:
+ * Expand all / Collapse all for the context sections, opening the section a
+ * `#hash` names (flipping to the back and its Context tab first), and opening
+ * every section for printing (browsers disagree on printing a closed
+ * `<details>`).
  */
-const TOGGLE_SCRIPT = `<script>
+const CARD_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};
+  var btn=document.querySelector(".xall");
+  var sync=function(){if(btn)btn.textContent=secs.every(function(d){return d.open})?"Collapse all":"Expand all"};
+  if(btn&&secs.length){
+    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(decodeURIComponent(location.hash.slice(1)));
+    if(!d||d.tagName!=="DETAILS")return;
+    var f=document.getElementById("flip"),t=document.getElementById("t-context");
+    if(f)f.checked=true;if(t)t.checked=true;d.open=true;sync();
+    setTimeout(function(){d.scrollIntoView({block:"nearest"})},620);
+  };
   addEventListener("hashchange",openHash);openHash();
   var pre=[];
   addEventListener("beforeprint",function(){pre=secs.map(function(d){return d.open});secs.forEach(function(d){d.open=true})});
@@ -270,7 +494,10 @@ export function renderCardText(root, opts = {}) {
     const meta = serverCardMeta();
     const name = id?.displayName ?? id?.name ?? basename(resolve(root));
     const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
-    const out = [`### ${name} — context card`];
+    const out = [`### ${name} — business card`];
+    const title = cardTitle(id);
+    if (title)
+        out.push(`**${title}**`);
     const pills = [
         id?.vendor && id.vendor !== id.status ? id.vendor : null,
         id?.agentVersion ? `v${id.agentVersion}` : null,

package/dist/server-card.d.ts

@@ -0,0 +1,39 @@
+export interface ServerCardOptions {
+    /** Public origin this server is reached at (e.g. `https://ctx.example.com`).
+     *  When set, the card advertises the streamable-HTTP endpoint at `<origin>/mcp`. */
+    origin?: string;
+}
+export declare function serverCard(opts?: ServerCardOptions): {
+    _meta: {
+        readonly "io.github.Wolfe-Jam.mcp-context-card/context": {
+            readonly source: "AGENTS.md";
+            readonly mediaType: "text/markdown";
+        };
+        readonly "io.github.Wolfe-Jam.mcp-context-card/memory": {
+            readonly source: "project.fafm";
+            readonly mediaType: "application/vnd.fafm+yaml";
+            readonly iana: string;
+            readonly note: "no de-facto standard for agent memory yet — this is one instantiation";
+        };
+        readonly "io.github.Wolfe-Jam.mcp-context-card/identity": {
+            readonly source: ".well-known/fafa";
+            readonly mediaType: "application/vnd.fafa+yaml";
+            readonly iana: string;
+        };
+    };
+    remotes?: {
+        type: "streamable-http";
+        url: string;
+        supportedProtocolVersions: string[];
+    }[] | undefined;
+    $schema: string;
+    name: string;
+    version: string;
+    title: string;
+    description: string;
+    websiteUrl: string;
+    repository: {
+        url: string;
+        source: string;
+    };
+};

package/dist/server-card.js

@@ -0,0 +1,38 @@
+/**
+ * server-card — this server's MCP Server Card (SEP-2127, Final; schema v1).
+ *
+ * Required: `$schema`, `name` (reverse-DNS), `version`, `description`.
+ * Optional fields carried here: `title`, `websiteUrl`, `repository`, `remotes`
+ * (only when the caller knows the public origin, i.e. served over HTTP) and the
+ * namespaced `_meta` context block. No tools, resources or prompts: a card
+ * describes identity and connectivity, and primitives stay runtime-listed.
+ *
+ * `name`, `title` and `version` are the same values the live connection reports
+ * in `serverInfo`, so the card never contradicts runtime.
+ */
+import { SUPPORTED_PROTOCOL_VERSIONS } from "@modelcontextprotocol/sdk/types.js";
+import { DESCRIPTION, MCP_PATH, REGISTRY_NAME, REPOSITORY_URL, SERVER_CARD_SCHEMA, TITLE, VERSION, } from "./constants.js";
+import { serverCardMeta } from "./identity.js";
+export function serverCard(opts = {}) {
+    return {
+        $schema: SERVER_CARD_SCHEMA,
+        name: REGISTRY_NAME,
+        version: VERSION,
+        title: TITLE,
+        description: DESCRIPTION,
+        websiteUrl: REPOSITORY_URL,
+        repository: { url: REPOSITORY_URL, source: "github" },
+        ...(opts.origin
+            ? {
+                remotes: [
+                    {
+                        type: "streamable-http",
+                        url: `${opts.origin}${MCP_PATH}`,
+                        supportedProtocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+                    },
+                ],
+            }
+            : {}),
+        _meta: serverCardMeta(),
+    };
+}