@cfbender/cesium 0.3.5 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## v0.3.6 — 2026-05-11
+
+Adds a periodic-table-themed favicon for the cesium HTTP server.
+
+- **feat:** Element-55 ("Cs") periodic-table tile favicon in the claret-dark
+  palette. Source SVG at `assets/favicon.svg`.
+- **feat:** `writeFaviconSvg` drops `<stateDir>/favicon.svg` next to
+  `theme.css` on every publish/ask (and on `cesium theme apply`). The static
+  HTTP server then serves it at `/favicon.svg`.
+- **feat:** `<link rel="icon" type="image/svg+xml">` is now emitted in
+  artifact pages, project index pages, and the global index page (paths
+  derived from the existing theme.css href so suppression behavior matches).
+- **feat:** Inline favicon emblem rendered next to the "cesium" / "cesium ·
+  project" eyebrow on both index pages.
+- **feat:** `/favicon.ico` shim — server pre-handler serves the SVG bytes
+  with `image/svg+xml` content type so browsers that auto-request the legacy
+  `.ico` path don't see a 404.
+
 ## v0.3.5 — 2026-05-11
 
 Fixes the `Publish to npm` GitHub Action.

package/README.md

@@ -1,4 +1,7 @@
-# Cesium
+<h1>
+  <img src="assets/favicon.svg" alt="" width="48" height="48" align="left" style="margin-right: 12px; vertical-align: middle;">
+  Cesium
+</h1>
 
 Cesium publishes substantive opencode agent responses — plans, code reviews,
 comparisons, explainers, audits, RFCs — as self-contained beautiful HTML artifacts
@@ -6,10 +9,6 @@ on disk, instead of dumping markdown into the terminal. The browser becomes the
 reading surface; the terminal stays the control surface. Each artifact is a single
 `.html` file: portable, archivable, viewable offline, shareable as a URL over SSH.
 
-v0.3.0 adds **interactive Q&A artifacts** — the agent can now publish a question
-form, wait for the user to answer in their browser, and receive the structured
-responses before continuing work.
-
 <video src="assets/cesium.mp4" autoplay loop muted playsinline width="720">
   Demo video — see <a href="assets/cesium.mp4">assets/cesium.mp4</a> if it
   doesn't play inline (some markdown viewers strip <code>&lt;video&gt;</code>).
@@ -51,19 +50,37 @@ unreleased changes).
 
 ### CLI
 
+The CLI puts a `cesium` binary on your `PATH` for browsing, opening, and
+managing artifacts (`cesium ls`, `cesium open`, `cesium serve`, `cesium prune`,
+`cesium theme`).
+
+**Recommended: install with [mise](https://mise.jdx.dev/)** so cesium is pinned
+in your config and tracks with the rest of your toolchain. Add to your
+`~/.config/mise/config.toml` (or a project-local `mise.toml`):
+
+```toml
+[tools]
+"npm:@cfbender/cesium" = "latest"
+```
+
+Then run `mise install` (or `mise use -g npm:@cfbender/cesium@latest` for the
+one-liner equivalent). Pin to a specific release with `"0.3.6"` instead of
+`"latest"`. Upgrade with `mise upgrade npm:@cfbender/cesium`.
+
+**Alternative: install with bun directly:**
+
 ```bash
 bun install -g @cfbender/cesium
 ```
 
-This puts a `cesium` binary on your `PATH` (at `~/.bun/bin/cesium`). If
-`which cesium` returns nothing, add `~/.bun/bin` to your shell rc:
+This puts the binary at `~/.bun/bin/cesium`. If `which cesium` returns nothing,
+add `~/.bun/bin` to your shell rc:
 
 ```bash
 export PATH="$HOME/.bun/bin:$PATH"
 ```
 
-Upgrade later with `bun update -g @cfbender/cesium` (or via your version
-manager — e.g. `mise use -g npm:@cfbender/cesium@latest`). To uninstall:
+Upgrade with `bun update -g @cfbender/cesium`. Uninstall with
 `bun remove -g @cfbender/cesium`.
 
 ### Developing on cesium itself

package/assets/styleguide.html

@@ -329,6 +329,89 @@
         color: var(--muted);
         text-transform: lowercase;
       }
+      .pill.accent {
+        background: color-mix(in srgb, var(--accent) 18%, var(--surface));
+        color: var(--accent);
+        font-weight: 600;
+      }
+
+      /* ranked list */
+      .ranked-list {
+        display: flex;
+        flex-direction: column;
+        gap: 1em;
+        margin: 0 0 1.5em;
+        padding: 0;
+        list-style: none;
+      }
+      .ranked-item {
+        background: var(--surface);
+        border: 1.5px solid var(--rule);
+        border-radius: 12px;
+        padding: 22px 26px;
+        display: grid;
+        grid-template-columns: 64px 1fr;
+        gap: 6px 24px;
+        align-items: start;
+      }
+      .ranked-item .rank-num {
+        font-family: var(--serif);
+        font-size: 2.4rem;
+        font-weight: 500;
+        color: var(--oat);
+        line-height: 1;
+        letter-spacing: -0.02em;
+        padding-top: 2px;
+      }
+      .ranked-item .rank-title {
+        font-family: var(--serif);
+        font-size: 1.2rem;
+        font-weight: 600;
+        color: var(--ink);
+        margin: 0 0 6px;
+        line-height: 1.3;
+      }
+      .ranked-item .rank-meta {
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        flex-wrap: wrap;
+        margin-bottom: 14px;
+      }
+      .ranked-item .rank-body > p {
+        color: var(--ink-soft);
+        font-size: 0.95rem;
+        line-height: 1.65;
+        margin: 0 0 0.85em;
+      }
+      .ranked-item .rank-body > p:last-child {
+        margin-bottom: 0;
+      }
+      .ranked-item .rank-body > ul,
+      .ranked-item .rank-body > ol {
+        color: var(--ink-soft);
+        font-size: 0.95rem;
+        line-height: 1.65;
+        margin: 0 0 0.85em;
+        padding-left: 1.2em;
+      }
+      .ranked-item .rank-aside {
+        color: var(--muted);
+        font-size: 0.9rem;
+        line-height: 1.6;
+        padding-left: 14px;
+        border-left: 2px solid var(--rule);
+        margin: 0;
+      }
+      .ranked-item .rank-aside-label {
+        font-family: var(--mono);
+        font-size: 0.7rem;
+        font-weight: 600;
+        letter-spacing: 0.1em;
+        text-transform: uppercase;
+        color: var(--accent);
+        margin-right: 6px;
+      }
 
       /* byline */
       .byline {
@@ -845,6 +928,72 @@
         </div>
       </section>
 
+      <!-- ============================================================
+       Section 13 · Ranked list
+       ============================================================ -->
+      <section>
+        <p class="eyebrow">13 · ranked-list</p>
+        <h2 class="h-section"><span class="section-num">13</span>Ranked list</h2>
+        <p>
+          Use <code>.ranked-list</code> + <code>.ranked-item</code> for ordered recommendations,
+          findings, or rankings — anything that would otherwise be a heavy numbered
+          <code>&lt;h3&gt;</code> sequence. Each item gets a soft serif numeral on the left and a
+          calm title + meta + body on the right. Pair <code>.pill.accent</code> +
+          <code>.tag</code> in the meta row for impact and savings; use <code>.rank-aside</code> for
+          a quieter "bonus" addendum.
+        </p>
+
+        <ol class="ranked-list">
+          <li class="ranked-item">
+            <div class="rank-num">01</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Replace the styleguide payload with a compact catalog</h3>
+              <div class="rank-meta">
+                <span class="pill accent">High impact</span>
+                <span class="tag">~6–8k tokens / call</span>
+              </div>
+              <p>
+                Return a structured Markdown reference of <em>class → purpose → minimal example</em>
+                instead of the full HTML framework. Realistic target: 3–5 KB / ~1k tokens, down from
+                ~7–9k.
+              </p>
+              <p class="rank-aside">
+                <span class="rank-aside-label">Bonus</span>
+                Derive the catalog from a single source so it can't drift from the framework.
+              </p>
+            </div>
+          </li>
+          <li class="ranked-item">
+            <div class="rank-num">02</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Trim the system prompt fragment</h3>
+              <div class="rank-meta">
+                <span class="pill">Low impact</span>
+                <span class="tag">~400 tokens / session</span>
+              </div>
+              <p>
+                Remove redundancy with in-tool <code>description</code> strings. Nice but not
+                transformative.
+              </p>
+            </div>
+          </li>
+          <li class="ranked-item">
+            <div class="rank-num">03</div>
+            <div class="rank-body">
+              <h3 class="rank-title">Stop double-emitting CSS in <code>wrapDocument()</code></h3>
+              <div class="rank-meta">
+                <span class="pill">Disk only</span>
+                <span class="tag">~17 KB / artifact</span>
+              </div>
+              <p>
+                Inline the framework only when the linked stylesheet is unavailable; emit tokens
+                inline always.
+              </p>
+            </div>
+          </li>
+        </ol>
+      </section>
+
       <!-- ============================================================
        Footer / byline
        ============================================================ -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfbender/cesium",
-  "version": "0.3.5",
+  "version": "0.4.0",
   "description": "Beautiful self-contained HTML artifacts from your opencode agent.",
   "license": "MIT",
   "author": "Cody Bender",

package/src/cli/commands/theme.ts

@@ -10,6 +10,7 @@ import {
   type ThemePalette,
 } from "../../render/theme.ts";
 import { writeThemeCss, themeCssPath } from "../../storage/theme-write.ts";
+import { writeFaviconSvg } from "../../storage/favicon-write.ts";
 import { themeTokensCss } from "../../render/theme.ts";
 import { atomicWrite } from "../../storage/write.ts";
 import { readdir } from "node:fs/promises";
@@ -307,6 +308,7 @@ async function themeApplyCommand(argv: string[], ctx: ThemeContext): Promise<num
   const cfg = (ctx.loadConfig ?? loadConfig)();
   const { theme, presetLabel } = resolveTheme(cfg);
   const cssPath = await writeThemeCss(cfg.stateDir, theme);
+  await writeFaviconSvg(cfg.stateDir);
 
   if (values["rewrite-artifacts"]) {
     const { artifacts, indexes } = await retrofitAll(cfg.stateDir, ctx.stdout);

package/src/render/critique.ts

@@ -39,7 +39,7 @@ export interface CritiqueResult {
 const HTTP_RE = /^https?:\/\//i;
 
 /** The only cesium-* class the framework ships with. All others are unknown. */
-const KNOWN_CESIUM_CLASSES = new Set(["cesium-back"]);
+const KNOWN_CESIUM_CLASSES = new Set(["cesium-back", "cesium-eyebrow"]);
 
 /** Callout severity modifiers — a callout needs at least one of these. */
 const CALLOUT_MODIFIERS = new Set(["note", "warn", "risk"]);

package/src/render/favicon.ts

@@ -0,0 +1,56 @@
+// Cesium favicon — periodic-table tile, element 55 ("Cs"), claret-dark palette.
+//
+// The SVG is theme-independent (always claret-dark wine + rose) so it stays
+// recognizable as the cesium emblem regardless of the user's chosen theme.
+//
+// Two consumers:
+//   1. `writeFaviconSvg` writes this string to <stateDir>/favicon.svg, which
+//      is then referenced by <link rel="icon"> in artifact + index pages and
+//      auto-served by the cesium HTTP server.
+//   2. `faviconEmblemSvg` returns inline SVG markup suitable for placing next
+//      to the "cesium" eyebrow on index pages (no <?xml?> declaration, no
+//      role/aria — those are decorative chrome).
+
+/** The full standalone favicon SVG written to <stateDir>/favicon.svg. */
+export const FAVICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="Cesium — element 55">
+  <!-- Periodic table tile, claret-dark palette -->
+  <rect x="2" y="2" width="60" height="60" rx="10" ry="10" fill="#180810"/>
+  <rect x="2.75" y="2.75" width="58.5" height="58.5" rx="9.25" ry="9.25"
+        fill="none" stroke="#C75B7A" stroke-width="1.5"/>
+
+  <!-- Atomic number, top-left -->
+  <text x="8" y="18" fill="#C75B7A"
+        font-family="ui-monospace, 'SF Mono', Menlo, Monaco, monospace"
+        font-size="13" font-weight="700" letter-spacing="0.5">55</text>
+
+  <!-- Element symbol, centered -->
+  <text x="32" y="48" fill="#DDD3C7" text-anchor="middle"
+        font-family="Georgia, 'Times New Roman', serif"
+        font-size="36" font-weight="700" letter-spacing="-1">Cs</text>
+</svg>
+`;
+
+/** Inline SVG emblem for placing next to the "cesium" eyebrow text.
+ *  Decorative — uses aria-hidden so screen readers skip it (the text label
+ *  next to it already says "cesium").
+ *
+ *  @param size — pixel size for both width and height. Defaults to 18.
+ */
+export function faviconEmblemSvg(size = 18): string {
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="${size}" height="${size}" aria-hidden="true" focusable="false" style="display:inline-block;vertical-align:-3px;flex-shrink:0;">
+  <rect x="2" y="2" width="60" height="60" rx="10" ry="10" fill="#180810"/>
+  <rect x="2.75" y="2.75" width="58.5" height="58.5" rx="9.25" ry="9.25" fill="none" stroke="#C75B7A" stroke-width="1.5"/>
+  <text x="8" y="18" fill="#C75B7A" font-family="ui-monospace, 'SF Mono', Menlo, Monaco, monospace" font-size="13" font-weight="700" letter-spacing="0.5">55</text>
+  <text x="32" y="48" fill="#DDD3C7" text-anchor="middle" font-family="Georgia, 'Times New Roman', serif" font-size="36" font-weight="700" letter-spacing="-1">Cs</text>
+</svg>`;
+}
+
+/** Returns the <link rel="icon"> tag for an HTML head, given a relative href.
+ *
+ *  - Artifact pages (3 levels deep): href = "../../../favicon.svg"
+ *  - Project index (2 levels deep):  href = "../../favicon.svg"
+ *  - Global index (root):            href = "favicon.svg"
+ */
+export function faviconLinkTag(href: string): string {
+  return `<link rel="icon" type="image/svg+xml" href="${href}">`;
+}

package/src/render/theme.ts

@@ -456,6 +456,87 @@ h1, h2, h3, h4, h5, h6 {
   color: var(--muted);
   text-transform: lowercase;
 }
+.pill.accent {
+  background: color-mix(in srgb, var(--accent) 18%, var(--surface));
+  color: var(--accent);
+  font-weight: 600;
+}
+
+/* ranked list — numbered cards for ordered recommendations / findings */
+.ranked-list {
+  display: flex;
+  flex-direction: column;
+  gap: 1em;
+  margin: 0 0 1.5em;
+  padding: 0;
+  list-style: none;
+}
+.ranked-item {
+  background: var(--surface);
+  border: 1.5px solid var(--rule);
+  border-radius: 12px;
+  padding: 22px 26px;
+  display: grid;
+  grid-template-columns: 64px 1fr;
+  gap: 6px 24px;
+  align-items: start;
+}
+.ranked-item .rank-num {
+  font-family: var(--serif);
+  font-size: 2.4rem;
+  font-weight: 500;
+  color: var(--oat);
+  line-height: 1;
+  letter-spacing: -0.02em;
+  padding-top: 2px;
+}
+.ranked-item .rank-title {
+  font-family: var(--serif);
+  font-size: 1.2rem;
+  font-weight: 600;
+  color: var(--ink);
+  margin: 0 0 6px;
+  line-height: 1.3;
+}
+.ranked-item .rank-meta {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+  margin-bottom: 14px;
+}
+.ranked-item .rank-body > p {
+  color: var(--ink-soft);
+  font-size: 0.95rem;
+  line-height: 1.65;
+  margin: 0 0 0.85em;
+}
+.ranked-item .rank-body > p:last-child { margin-bottom: 0; }
+.ranked-item .rank-body > ul,
+.ranked-item .rank-body > ol {
+  color: var(--ink-soft);
+  font-size: 0.95rem;
+  line-height: 1.65;
+  margin: 0 0 0.85em;
+  padding-left: 1.2em;
+}
+.ranked-item .rank-aside {
+  color: var(--muted);
+  font-size: 0.9rem;
+  line-height: 1.6;
+  padding-left: 14px;
+  border-left: 2px solid var(--rule);
+  margin: 0;
+}
+.ranked-item .rank-aside-label {
+  font-family: var(--mono);
+  font-size: 0.7rem;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--accent);
+  margin-right: 6px;
+}
 
 /* byline */
 .byline {

package/src/render/wrap.ts

@@ -3,6 +3,7 @@
 import { frameworkRulesCss, themeTokensCss, type ThemeTokens } from "./theme.ts";
 import { renderControl, renderAnswered } from "./controls.ts";
 import { getClientJs } from "./client-js.ts";
+import { faviconLinkTag } from "./favicon.ts";
 import type { InteractiveData, Question } from "./validate.ts";
 
 export interface ArtifactMeta {
@@ -47,6 +48,20 @@ function escapeHtml(str: string): string {
     .replace(/"/g, """);
 }
 
+/** Derives the favicon href from the theme.css href.
+ *
+ *  Both files live in the stateDir root, so the relative depth is identical:
+ *  swap the trailing "theme.css" segment for "favicon.svg". For atypical
+ *  themeCssHref values (absolute URLs, paths without "theme.css" suffix), fall
+ *  back to the artifact-context default.
+ */
+function deriveFaviconHref(themeCssHref: string): string {
+  if (themeCssHref.endsWith("theme.css")) {
+    return themeCssHref.slice(0, -"theme.css".length) + "favicon.svg";
+  }
+  return "../../../favicon.svg";
+}
+
 function safeJsonForScript(obj: unknown): string {
   return JSON.stringify(obj, null, 2).replace(/<\/script>/gi, "<\\/script>");
 }
@@ -145,6 +160,10 @@ export function wrapDocument(opts: WrapOptions): string {
       : "";
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
+  // Favicon path mirrors the theme.css path: artifacts live three levels deep
+  // in <stateDir>/projects/<slug>/artifacts/, so favicon.svg is "../../../".
+  // When suppressed (standalone/test mode), we suppress favicon too.
+  const faviconTag = suppressLink ? "" : `\n  ${faviconLinkTag(deriveFaviconHref(href ?? ""))}`;
 
   return `<!doctype html>
 <html lang="en">
@@ -154,7 +173,7 @@ export function wrapDocument(opts: WrapOptions): string {
   <title>${titleEsc} · cesium</title>
   <style>${rules}
 /* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}</style>${linkTag}
+${tokens}</style>${linkTag}${faviconTag}
   <script type="application/json" id="cesium-meta">${metaJson}</script>
 </head>
 <body>

package/src/server/favicon.ts

@@ -0,0 +1,28 @@
+// Favicon shim handler — serves the cesium favicon at /favicon.ico (the legacy
+// path browsers request automatically) by returning the in-memory SVG bytes
+// with image/svg+xml content type. All evergreen browsers accept SVG favicons
+// regardless of the URL extension.
+//
+// The static server already serves /favicon.svg from <stateDir>/favicon.svg
+// (written by writeFaviconSvg on every publish). This shim covers the .ico
+// fallback so users don't see a 404 in DevTools.
+
+import { FAVICON_SVG } from "../render/favicon.ts";
+
+const SVG_RESPONSE_HEADERS: Record<string, string> = {
+  "Content-Type": "image/svg+xml; charset=utf-8",
+  "Cache-Control": "public, max-age=86400",
+};
+
+export function createFaviconHandler(): (req: Request) => Promise<Response | undefined> {
+  return async (req: Request): Promise<Response | undefined> => {
+    const url = new URL(req.url);
+    if (url.pathname !== "/favicon.ico") {
+      return undefined;
+    }
+    if (req.method !== "GET" && req.method !== "HEAD") {
+      return undefined;
+    }
+    return new Response(FAVICON_SVG, { status: 200, headers: SVG_RESPONSE_HEADERS });
+  };
+}

package/src/server/lifecycle.ts

@@ -6,6 +6,7 @@ import { unlink, writeFile } from "node:fs/promises";
 import { startServer, type ServerHandle } from "./http.ts";
 import { acquireLock } from "../storage/lock.ts";
 import { createApiHandler } from "./api.ts";
+import { createFaviconHandler } from "./favicon.ts";
 
 export interface LifecycleConfig {
   stateDir: string;
@@ -260,6 +261,9 @@ export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo>
 
     // Wire API handler before static file fallback
     handle.addHandler(createApiHandler({ stateDir }));
+    // /favicon.ico shim — browsers auto-request this even when the page
+    // declares an SVG favicon. Serve the SVG bytes inline so we don't 404.
+    handle.addHandler(createFaviconHandler());
 
     const startedAt = new Date().toISOString();
 

package/src/storage/favicon-write.ts

@@ -0,0 +1,23 @@
+// Writes favicon.svg to the state directory.
+//
+// Mirrors theme-write.ts: produces a single static asset alongside theme.css
+// that artifact pages and index pages reference via relative <link rel="icon">.
+// The cesium HTTP server serves it automatically because the state dir is the
+// server's static root.
+
+import { join } from "node:path";
+import { FAVICON_SVG } from "../render/favicon.ts";
+import { atomicWrite } from "./write.ts";
+
+/** Returns the absolute path to favicon.svg in the given stateDir. */
+export function faviconSvgPath(stateDir: string): string {
+  return join(stateDir, "favicon.svg");
+}
+
+/** Writes <stateDir>/favicon.svg. Atomic. Returns the absolute path.
+ *  Idempotent — content is theme-independent so writing twice is a no-op. */
+export async function writeFaviconSvg(stateDir: string): Promise<string> {
+  const path = faviconSvgPath(stateDir);
+  await atomicWrite(path, FAVICON_SVG);
+  return path;
+}

package/src/storage/index-gen.ts

@@ -3,6 +3,7 @@
 import type { IndexEntry } from "./index-cache.ts";
 import type { ThemeTokens } from "../render/theme.ts";
 import { frameworkRulesCss, themeTokensCss } from "../render/theme.ts";
+import { faviconLinkTag, faviconEmblemSvg } from "../render/favicon.ts";
 
 export interface RenderProjectIndexArgs {
   projectSlug: string;
@@ -88,6 +89,11 @@ function formatDate(iso: string): string {
 function indexCss(): string {
   return `
 /* index-page chrome */
+.cesium-eyebrow {
+  display: inline-flex; align-items: center; gap: 8px;
+  /* the eyebrow text is uppercased + tracked; the emblem sits flush left */
+}
+.cesium-eyebrow svg { display: block; }
 .filter-row { display: flex; flex-wrap: wrap; gap: 8px; margin-bottom: 24px; align-items: center; }
 .filter-chip {
   display: inline-block; font-family: var(--sans); font-size: 0.8em; font-weight: 500;
@@ -274,6 +280,12 @@ export function renderProjectIndex(args: RenderProjectIndexArgs): string {
   const iJs = indexJs();
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
+  // Favicon sits next to theme.css in the stateDir root, so swap the suffix.
+  const faviconHref =
+    href !== null && href.endsWith("theme.css")
+      ? href.slice(0, -"theme.css".length) + "favicon.svg"
+      : "../../favicon.svg";
+  const faviconTag = suppressLink ? "" : `\n  ${faviconLinkTag(faviconHref)}`;
 
   // Sort entries newest-first
   const sorted = [...entries].toSorted(
@@ -348,11 +360,11 @@ ${cardsHtml}
   <title>${esc(projectName)} · cesium</title>
   <style>${rules}
 /* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}
+${tokens}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">
-  <p class="eyebrow">cesium · project</p>
+  <p class="eyebrow cesium-eyebrow">${faviconEmblemSvg(18)}<span>cesium · project</span></p>
   <h1 class="h-display">${esc(projectName)}</h1>
   ${subhead}
   ${filterRow}
@@ -383,6 +395,12 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
   const iCss = indexCss();
 
   const linkTag = suppressLink ? "" : `\n  <link rel="stylesheet" href="${href}">`;
+  // Favicon sits next to theme.css; default href is "theme.css" → "favicon.svg".
+  const faviconHref =
+    href !== null && href.endsWith("theme.css")
+      ? href.slice(0, -"theme.css".length) + "favicon.svg"
+      : "favicon.svg";
+  const faviconTag = suppressLink ? "" : `\n  ${faviconLinkTag(faviconHref)}`;
 
   const sorted = [...projects].toSorted(
     (a, b) => new Date(b.latestCreatedAt).getTime() - new Date(a.latestCreatedAt).getTime(),
@@ -432,11 +450,11 @@ export function renderGlobalIndex(args: RenderGlobalIndexArgs): string {
   <title>All projects · cesium</title>
   <style>${rules}
 /* fallback theme tokens — used when theme.css is missing or unreachable */
-${tokens}${iCss}</style>${linkTag}
+${tokens}${iCss}</style>${linkTag}${faviconTag}
 </head>
 <body>
 <div class="page">
-  <p class="eyebrow">cesium</p>
+  <p class="eyebrow cesium-eyebrow">${faviconEmblemSvg(18)}<span>cesium</span></p>
   <h1 class="h-display">All projects</h1>
   ${subhead}
   ${bodyContent}

package/src/tools/ask.ts

@@ -14,6 +14,7 @@ import type { InteractiveData } from "../render/validate.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
 import { atomicWrite } from "../storage/write.ts";
 import { writeThemeCss } from "../storage/theme-write.ts";
+import { writeFaviconSvg } from "../storage/favicon-write.ts";
 import { loadIndex, writeIndex, appendEntry, type IndexEntry } from "../storage/index-cache.ts";
 import { withLock } from "../storage/lock.ts";
 import { renderProjectIndex, renderGlobalIndex } from "../storage/index-gen.ts";
@@ -227,8 +228,9 @@ export function createAskTool(
       // 14. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 14a. Write theme.css (idempotent, outside index lock — separate file)
+      // 14a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
       await writeThemeCss(config.stateDir, theme);
+      await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
         body: scrubbed.html,

package/src/tools/publish.ts

@@ -14,6 +14,7 @@ import { wrapDocument, type ArtifactMeta } from "../render/wrap.ts";
 import { deriveProjectIdentity, artifactFilename, pathsFor } from "../storage/paths.ts";
 import { atomicWrite, patchEmbeddedMetadata } from "../storage/write.ts";
 import { writeThemeCss } from "../storage/theme-write.ts";
+import { writeFaviconSvg } from "../storage/favicon-write.ts";
 import {
   loadIndex,
   writeIndex,
@@ -224,8 +225,9 @@ export function createPublishTool(
       // 12. Build theme + wrap document
       const theme = mergeTheme(themeFromPreset(config.themePreset), config.theme);
 
-      // 12a. Write theme.css (idempotent, outside index lock — separate file)
+      // 12a. Write theme.css + favicon.svg (idempotent, outside index lock — separate files)
       await writeThemeCss(config.stateDir, theme);
+      await writeFaviconSvg(config.stateDir);
 
       const fullHtml = wrapDocument({
         body: scrubbed.html,