@chllming/wave-orchestration 0.5.1

package/releases/manifest.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 1,
+  "packageName": "@chllming/wave-orchestration",
+  "releases": [
+    {
+      "version": "0.5.1",
+      "date": "2026-03-22",
+      "summary": "Phase 4 fix release plus npmjs trusted-publishing bootstrap support.",
+      "features": [
+        "Final lane completion now stays blocked on unresolved human feedback and escalation tickets from completed waves, matching the intended Phase 4 barrier behavior.",
+        "Hermetic trace fixtures now rewrite seeded per-agent executor blocks so local replay coverage cannot accidentally launch live Codex, Claude Code, or OpenCode sessions.",
+        "A dedicated npmjs publish workflow now exists alongside the GitHub Packages workflow, with `package.json` publish metadata updated so each workflow can target its own registry cleanly.",
+        "Install and maintainer docs now distinguish the current GitHub Packages path from the future zero-token npmjs path and document trusted-publishing bootstrap."
+      ],
+      "manualSteps": [
+        "Push `main` and tag `v0.5.1` before publishing, so the npm tarball matches the tagged source exactly.",
+        "For the first npmjs release, authenticate locally and run `npm publish --access public --registry=https://registry.npmjs.org` from the `0.5.1` checkout.",
+        "After the first npmjs release exists, configure npm trusted publishing for `chllming / wave-orchestration / publish-npm.yml` so later tagged releases no longer need manual npm auth."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.5.0",
+      "date": "2026-03-22",
+      "summary": "Phase 4 helper assignment routing, cross-lane dependency workflows, and publish-ready package metadata.",
+      "features": [
+        "Capability-targeted requests now become explicit helper assignments with deterministic assignee selection, assignment snapshots, ledger/task coverage, inbox visibility, and closure barriers.",
+        "Typed cross-lane dependency workflows now have `wave dep` operator commands, per-wave inbound/outbound dependency projections, dependency-aware gating, and replay-visible dependency state.",
+        "Phase 3 replay acceptance was tightened around the runtime-orchestration layer with stored outcome snapshots, launcher-generated local trace fixtures, and stronger replay comparison coverage.",
+        "The package now carries explicit `repository`, `homepage`, and `bugs` metadata for cleaner GitHub Packages linking."
+      ],
+      "manualSteps": [
+        "After upgrading, dry-run the target lane with `pnpm exec wave launch --lane main --dry-run --no-dashboard` to inspect helper-assignment and dependency projections before running real executors.",
+        "Use `pnpm exec wave dep show --lane <lane> --wave <n> --json` to inspect inbound and outbound dependency state when a lane appears blocked.",
+        "If you want helper-task routing beyond ownership defaults, add or refine `### Capabilities` blocks in your wave files and `capabilityRouting.preferredAgents` in `wave.config.json`."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.4.0",
+      "date": "2026-03-21",
+      "summary": "Runtime surface upgrade plus hermetic traces for Codex, Claude Code, and OpenCode.",
+      "features": [
+        "Expanded Codex `exec` support for model, profile, inline config, search, images, extra directories, JSON mode, and ephemeral sessions, alongside Claude settings overlay merging and OpenCode merged config overlays plus multi-file attachments.",
+        "Dry-run materialization of prompts, merged runtime overlays, and executor launch previews for all supported real runtimes.",
+        "Dedicated runtime configuration reference docs under `docs/reference/runtime-config/`, installed by `wave init` for config/default/profile/lane/agent authoring.",
+        "Hermetic `traceVersion: 2` trace bundles with copied launched-agent artifacts, cumulative quality metrics, hash validation, and an internal read-only replay validator.",
+        "Retry and coordination hardening for policy-safe fallback blocking, clarification-follow-up matching, and artifact-linked inbox visibility."
+      ],
+      "manualSteps": [
+        "Review any per-agent `### Executor` blocks that want the new runtime fields before cutting real waves on the upgraded package.",
+        "Run `pnpm exec wave launch --lane main --dry-run --no-dashboard` after upgrading to confirm prompts and executor overlays materialize as expected.",
+        "Use the docs under `docs/reference/runtime-config/` as the canonical reference when migrating runtime defaults, profiles, or per-agent executor blocks.",
+        "Treat internal trace replay as a publish gate for `0.4.0`, but keep it internal-only until a later operator-facing replay surface is designed."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.1.0",
+      "date": "2026-03-21",
+      "summary": "Generic wave orchestrator runtime with Context7 and multi-executor support.",
+      "features": [
+        "Generic wave parsing, validation, dashboards, closure sweep, and human feedback queue.",
+        "Context7 bundle resolution, prefetch, and prompt injection.",
+        "Headless executors for Codex, Claude Code, OpenCode, and the local smoke executor."
+      ],
+      "manualSteps": [],
+      "breaking": false
+    },
+    {
+      "version": "0.2.0",
+      "date": "2026-03-21",
+      "summary": "Package-first install and non-destructive upgrade workflow.",
+      "features": [
+        "Workspace-root aware runtime so the orchestrator can run from an installed package against any target repo.",
+        "New `wave init`, `wave upgrade`, `wave changelog`, and `wave doctor` commands.",
+        "Install-state tracking and upgrade-history reports under `.wave/` without overwriting repo-owned plans, waves, or config."
+      ],
+      "manualSteps": [
+        "For fresh repos, install the package and run `pnpm exec wave init`.",
+        "For repos that already have Wave config or plans, run `pnpm exec wave init --adopt-existing` once so upgrades stay non-destructive."
+      ],
+      "breaking": false
+    },
+    {
+      "version": "0.3.0",
+      "date": "2026-03-21",
+      "summary": "Phase 1 and 2 roadmap runtime: typed coordination, integration gating, and runtime planning.",
+      "features": [
+        "Canonical coordination log materialization, generated board projection, compiled shared summary, per-agent inboxes, and a durable wave ledger.",
+        "Planning-time executor profiles, lane runtime policy, hard runtime-mix enforcement, and retry fallback reassignment recorded into ledger, integration, and traces.",
+        "Orchestrator-first clarification triage, explicit integration summaries, and staged closure that runs integration before documentation and evaluator closure."
+      ],
+      "manualSteps": [
+        "Run `pnpm exec wave init --adopt-existing` in older repos if they do not yet have the newer role prompts and docs surfaces.",
+        "Review `wave.config.json` lane runtime policy before relying on automatic fallback behavior or strict runtime-mix limits."
+      ],
+      "breaking": false
+    }
+  ]
+}

package/scripts/context7-api-check.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Minimal Context7 API smoke test (expects CONTEXT7_API_KEY in the environment).
+set -euo pipefail
+
+if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then
+  echo "context7-api-check: CONTEXT7_API_KEY is not set" >&2
+  exit 1
+fi
+
+URL='https://context7.com/api/v2/libs/search?libraryName=temporal&query=go%20workflow'
+echo "GET $URL" >&2
+RESP="$(curl -fsS "$URL" -H "Authorization: Bearer ${CONTEXT7_API_KEY}" -H "Accept: application/json")"
+RESP_JSON="$RESP" node -e "
+const j = JSON.parse(process.env.RESP_JSON || '{}');
+const list = Array.isArray(j) ? j : (j.results ?? j.items ?? []);
+const first = list[0];
+if (!first) { console.error('Unexpected response shape:', Object.keys(j)); process.exit(1); }
+const id = first.id ?? first.libraryId;
+const name = first.title ?? first.name;
+console.log('ok — first library:', id || name || JSON.stringify(first).slice(0, 120));
+"

package/scripts/context7-export-env.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Load CONTEXT7_API_KEY from repo-root .env.local, then export it for child processes.
+#
+# Usage:
+#   source scripts/context7-export-env.sh
+#     — merges .env.local into the current shell (only CONTEXT7_* vars need to be present;
+#       the whole file is sourced with set -a).
+#
+#   bash scripts/context7-export-env.sh run <command> [args...]
+#     — loads .env.local, requires CONTEXT7_API_KEY, exports it, then execs the command.
+#
+# Examples:
+#   pnpm context7:api-check
+#   bash scripts/context7-export-env.sh run env | grep CONTEXT7
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+ENV_FILE="$REPO_ROOT/.env.local"
+
+if [[ -f "$ENV_FILE" ]]; then
+  set -a
+  # shellcheck disable=SC1090
+  source "$ENV_FILE"
+  set +a
+fi
+
+if [[ "${1:-}" == "run" ]]; then
+  set -euo pipefail
+  shift
+  if [[ $# -lt 1 ]]; then
+    echo "context7-export-env: run requires a command (e.g. bash scripts/context7-export-env.sh run curl ...)" >&2
+    exit 1
+  fi
+  if [[ -z "${CONTEXT7_API_KEY:-}" ]]; then
+    echo "context7-export-env: CONTEXT7_API_KEY is not set. Add it to ${ENV_FILE} at repo root." >&2
+    exit 1
+  fi
+  export CONTEXT7_API_KEY
+  exec "$@"
+fi
+
+# Invoked (not "run"): print hint; sourcing skips this when $0 is bash.
+if [[ "${BASH_SOURCE[0]:-}" == "${0:-}" ]]; then
+  echo "Usage: source scripts/context7-export-env.sh" >&2
+  echo "   or: bash scripts/context7-export-env.sh run <command> [args...]" >&2
+  exit 2
+fi
+
+# Sourced: export if set so subprocesses (e.g. codex) inherit it.
+if [[ -n "${CONTEXT7_API_KEY:-}" ]]; then
+  export CONTEXT7_API_KEY
+fi

package/scripts/research/agent-context-archive.mjs

@@ -0,0 +1,472 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+export const TOPIC_DEFINITIONS = [
+  {
+    id: "harnesses-and-practice",
+    title: "Harnesses and Practice",
+    description:
+      "Current guidance and recent papers on agent harness design, reviewer loops, terminal-native execution, and practical coding-agent workflows.",
+  },
+  {
+    id: "long-running-agents-and-compaction",
+    title: "Long-Running Agents and Compaction",
+    description:
+      "Long-horizon execution, resumability, memory systems, compaction, and evolving-task evaluation for agents that span many sessions.",
+  },
+  {
+    id: "blackboard-and-shared-workspaces",
+    title: "Blackboard and Shared Workspaces",
+    description:
+      "Shared-workspace coordination, blackboard-style agent systems, explicit consensus mechanics, and distributed reasoning under coordination constraints.",
+  },
+  {
+    id: "repo-context-and-evaluation",
+    title: "Repo Context and Evaluation",
+    description:
+      "Repository-level context files, harness evaluation methods, and evidence on what improves or harms coding-agent performance.",
+  },
+];
+
+export const PAPER_SECTION_ORDER = [
+  "P0 direct hits",
+  "P1 strong adjacent work",
+  "P2 lineage and older references",
+];
+
+const PAPER_SECTION_OVERRIDES = {
+  "an-open-agent-architecture": "P2 lineage and older references",
+  "evaluating-agents-md-are-repository-level-context-files-helpful-for-coding-agents":
+    "P1 strong adjacent work",
+  "memory-for-autonomous-llm-agents-mechanisms-evaluation-and-emerging-frontiers":
+    "P1 strong adjacent work",
+};
+
+const TOPIC_OVERRIDE_MAP = {
+  "evaluating-agents-md-are-repository-level-context-files-helpful-for-coding-agents":
+    ["repo-context-and-evaluation"],
+};
+
+function escapeInlinePipes(value) {
+  return String(value ?? "").replaceAll("|", "\\|");
+}
+
+function normalizeWhitespace(value) {
+  return String(value ?? "")
+    .replaceAll("\u00a0", " ")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+}
+
+function safeSlugFromPath(relPath) {
+  return path.basename(relPath, ".md");
+}
+
+function stripQuotes(value) {
+  const text = String(value ?? "").trim();
+  if (
+    (text.startsWith("'") && text.endsWith("'")) ||
+    (text.startsWith("\"") && text.endsWith("\""))
+  ) {
+    return text.slice(1, -1);
+  }
+  return text;
+}
+
+function parseFrontmatter(markdown) {
+  const match = markdown.match(/^---\n([\s\S]*?)\n---\n/);
+  return match ? match[1] : "";
+}
+
+function parseFrontmatterScalar(frontmatter, key) {
+  const match = frontmatter.match(new RegExp(`^${key}:\\s*(.+)$`, "m"));
+  return match ? stripQuotes(match[1]) : null;
+}
+
+function parseFrontmatterList(frontmatter, key) {
+  const match = frontmatter.match(new RegExp(`^${key}:\\n((?:  - .*\\n?)*)`, "m"));
+  if (!match) {
+    return [];
+  }
+  return match[1]
+    .split("\n")
+    .map((line) => line.match(/^  - (.+)$/)?.[1] ?? null)
+    .map((entry) => stripQuotes(entry))
+    .map((entry) => normalizeWhitespace(entry))
+    .filter(Boolean);
+}
+
+function extractFirstUrl(value) {
+  const match = String(value ?? "").match(/\((https?:\/\/[^)]+)\)/);
+  return match ? match[1] : null;
+}
+
+function parseMetadataRows(markdown) {
+  const sectionMatch = markdown.match(/## Metadata\s+([\s\S]*?)(?:\n## |\n# |$)/);
+  if (!sectionMatch) {
+    return new Map();
+  }
+
+  const rows = new Map();
+  for (const line of sectionMatch[1].split("\n")) {
+    if (!line.startsWith("|")) {
+      continue;
+    }
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((cell) => cell.trim());
+    if (cells.length < 2 || cells[0] === "Field" || cells[0] === "---") {
+      continue;
+    }
+    rows.set(cells[0].toLowerCase(), cells[1]);
+  }
+  return rows;
+}
+
+function parseYear(value) {
+  if (!value) {
+    return null;
+  }
+  const match = String(value).match(/\b(19|20)\d{2}\b/);
+  return match ? Number(match[0]) : null;
+}
+
+export function parseArchiveEntry(markdown, relPath) {
+  const frontmatter = parseFrontmatter(markdown);
+  const rows = parseMetadataRows(markdown);
+  const kind =
+    parseFrontmatterScalar(frontmatter, "kind") ??
+    (relPath.startsWith("articles/") ? "article" : "paper");
+
+  return {
+    slug: safeSlugFromPath(relPath),
+    path: relPath,
+    kind,
+    title: parseFrontmatterScalar(frontmatter, "title") ?? safeSlugFromPath(relPath),
+    summary: parseFrontmatterScalar(frontmatter, "summary"),
+    topics: parseFrontmatterList(frontmatter, "topics"),
+    year: parseYear(rows.get("year")),
+    venue: normalizeWhitespace(rows.get("venue")),
+    bucket: normalizeWhitespace(rows.get("research bucket")),
+    mapsTo: normalizeWhitespace(rows.get("maps to")),
+    fit: normalizeWhitespace(rows.get("harness fit")),
+    sourcePage: extractFirstUrl(rows.get("source page")),
+    sourcePdf: extractFirstUrl(rows.get("source pdf")),
+    additionalSource: extractFirstUrl(rows.get("additional source")),
+    additionalPdf: extractFirstUrl(rows.get("additional pdf")),
+  };
+}
+
+export function parsePaperSectionMap(indexMarkdown) {
+  const sectionMap = new Map();
+  let currentSection = null;
+
+  for (const line of String(indexMarkdown).split("\n")) {
+    if (line.startsWith("## ")) {
+      currentSection = line.slice(3).trim();
+      continue;
+    }
+    const match = line.match(
+      /\]\((?:(?:\.\/|\.\.\/)(?:papers\/)?|\/(?:[^)]+\/)?agent-context-cache\/(?:papers\/)?)?([a-z0-9-]+)(?:\.md)?\)/i,
+    );
+    if (!match || !currentSection) {
+      continue;
+    }
+    sectionMap.set(match[1], currentSection);
+  }
+
+  return sectionMap;
+}
+
+function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+export function inferTopics(entry, section = null) {
+  const topics = [...(entry.topics ?? [])];
+  const override = TOPIC_OVERRIDE_MAP[entry.slug];
+  if (override) {
+    topics.push(...override);
+  }
+
+  if (topics.length > 0) {
+    return unique(topics);
+  }
+
+  const haystack = `${entry.slug} ${entry.title} ${entry.mapsTo} ${entry.fit}`.toLowerCase();
+
+  if (
+    /agents-md|repository-level|repo context|repository context|evaluation harness|benchmark/.test(
+      haystack,
+    )
+  ) {
+    topics.push("repo-context-and-evaluation");
+  }
+
+  if (
+    /blackboard|shared workspace|shared workspaces|distributed coordination|coordination|consensus|communication-reasoning gap|silo-bench|symphony|dova|open agent architecture/.test(
+      haystack,
+    )
+  ) {
+    topics.push("blackboard-and-shared-workspaces");
+  }
+
+  if (
+    /long-running|long horizon|long-horizon|compaction|context engineering|memory|continuous software evolution|resumability|initializer|trace|versioned snapshots|reviewer loop/.test(
+      haystack,
+    )
+  ) {
+    topics.push("long-running-agents-and-compaction");
+  }
+
+  if (
+    entry.kind === "article" || /harness|codex|terminal|engineering|reviewer|agent-first/.test(haystack)
+  ) {
+    topics.push("harnesses-and-practice");
+  }
+
+  if (topics.length === 0) {
+    topics.push(entry.kind === "article" ? "harnesses-and-practice" : "long-running-agents-and-compaction");
+  }
+
+  return unique(topics);
+}
+
+export async function loadArchiveEntries(archiveRoot) {
+  const entries = [];
+
+  for (const folder of ["papers", "articles"]) {
+    const dirPath = path.join(archiveRoot, folder);
+    let fileNames = [];
+    try {
+      fileNames = await fs.readdir(dirPath);
+    } catch {
+      continue;
+    }
+
+    for (const fileName of fileNames.sort()) {
+      if (!fileName.endsWith(".md") || fileName === "index.md") {
+        continue;
+      }
+      const relPath = path.posix.join(folder, fileName);
+      const markdown = await fs.readFile(path.join(archiveRoot, relPath), "utf8");
+      entries.push(parseArchiveEntry(markdown, relPath));
+    }
+  }
+
+  return entries.sort((left, right) => left.title.localeCompare(right.title));
+}
+
+function relativeLink(fromDir, toPath) {
+  return path.relative(fromDir, toPath).split(path.sep).join("/");
+}
+
+function formatLocalLink(fromDir, targetPath, label) {
+  const relPath = relativeLink(fromDir, targetPath);
+  return `[${escapeInlinePipes(label)}](${relPath})`;
+}
+
+function formatSourceLink(entry) {
+  const url = entry.sourcePage ?? entry.additionalSource ?? entry.sourcePdf ?? entry.additionalPdf;
+  return url ? `[Source](${url})` : "—";
+}
+
+function formatCell(value, fallback = "—") {
+  const normalized = normalizeWhitespace(value);
+  return normalized ? escapeInlinePipes(normalized) : fallback;
+}
+
+function renderTable(headers, rows) {
+  const headerLine = `| ${headers.join(" | ")} |`;
+  const dividerLine = `| ${headers.map(() => "---").join(" | ")} |`;
+  return [headerLine, dividerLine, ...rows].join("\n");
+}
+
+export function buildPaperSectionAssignments(entries, existingSectionMap) {
+  const assignments = new Map();
+  for (const entry of entries.filter((item) => item.kind === "paper")) {
+    const requestedBucket = PAPER_SECTION_ORDER.includes(entry.bucket) ? entry.bucket : null;
+    assignments.set(
+      entry.slug,
+      existingSectionMap.get(entry.slug) ??
+        requestedBucket ??
+        PAPER_SECTION_OVERRIDES[entry.slug] ??
+        "P2 lineage and older references",
+    );
+  }
+  return assignments;
+}
+
+export function renderPaperIndex(entries, sectionAssignments) {
+  const paperEntries = entries.filter((entry) => entry.kind === "paper");
+  const grouped = new Map(PAPER_SECTION_ORDER.map((section) => [section, []]));
+  for (const entry of paperEntries) {
+    const section = sectionAssignments.get(entry.slug) ?? "P2 lineage and older references";
+    if (!grouped.has(section)) {
+      grouped.set(section, []);
+    }
+    grouped.get(section).push(entry);
+  }
+
+  const sections = PAPER_SECTION_ORDER.filter((section) => (grouped.get(section) ?? []).length > 0).map(
+    (section) => {
+      const rows = grouped
+        .get(section)
+        .slice()
+        .sort((left, right) => left.title.localeCompare(right.title))
+        .map((entry) => {
+          const fileLabel = formatLocalLink("papers", path.posix.join("papers", `${entry.slug}.md`), entry.title);
+          return `| ${fileLabel} | ${entry.year ?? "Unknown"} | ${formatCell(entry.venue)} | ${formatCell(entry.mapsTo)} | ${formatCell(entry.fit)} | ${formatSourceLink(entry)} |`;
+        });
+      return `## ${section}\n\n${renderTable(
+        ["Paper", "Year", "Venue", "Maps to", "Fit", "Source"],
+        rows,
+      )}`;
+    },
+  );
+
+  return `---
+summary: "Index of local-only agent-context papers and reports converted to Markdown with source links"
+read_when:
+  - Browsing the local harness and blackboard paper archive
+  - Looking for the paper copy of a source in the local cache
+title: "Paper Archive"
+---
+
+# Paper Archive
+
+<Note>
+This local-only archive contains ${paperEntries.length} papers and reports. Source
+documents were fetched transiently, converted to Markdown, and removed from
+disk after extraction. This directory is gitignored and is not shipped as part
+of the repository docs.
+</Note>
+
+## Coverage
+
+- Harnesses and practice
+- Long-running agents and compaction
+- Blackboard and shared workspaces
+- Repo context and evaluation
+
+${sections.join("\n\n")}
+`;
+}
+
+export function renderArticleIndex(entries) {
+  const articleEntries = entries.filter((entry) => entry.kind === "article");
+  const rows = articleEntries
+    .slice()
+    .sort((left, right) => left.title.localeCompare(right.title))
+    .map((entry) => {
+      const localLink = formatLocalLink(
+        "articles",
+        path.posix.join("articles", `${entry.slug}.md`),
+        entry.title,
+      );
+      return `| ${localLink} | ${entry.year ?? "Unknown"} | ${formatCell(entry.venue)} | ${formatCell(entry.mapsTo)} | ${formatSourceLink(entry)} |`;
+    });
+
+  return `---
+summary: "Index of local-only practice articles cached alongside the agent-context paper archive"
+read_when:
+  - Browsing current practice articles in the local harness archive
+  - Jumping from topic indexes into cached OpenAI and Anthropic guidance
+title: "Practice Articles"
+---
+
+# Practice Articles
+
+<Note>
+These cached articles are local-only working copies of vendor guidance that was
+useful for the harness archive. The source URLs remain the canonical
+references.
+</Note>
+
+${renderTable(["Article", "Year", "Venue", "Maps to", "Source"], rows)}
+`;
+}
+
+export function buildTopicGroups(entries, sectionAssignments) {
+  const groups = new Map(TOPIC_DEFINITIONS.map((topic) => [topic.id, []]));
+  for (const entry of entries) {
+    const section = entry.kind === "paper" ? sectionAssignments.get(entry.slug) : null;
+    for (const topic of inferTopics(entry, section)) {
+      if (!groups.has(topic)) {
+        groups.set(topic, []);
+      }
+      groups.get(topic).push(entry);
+    }
+  }
+  return groups;
+}
+
+function renderTopicList(fromDir, entries) {
+  return entries
+    .slice()
+    .sort((left, right) => left.title.localeCompare(right.title))
+    .map((entry) => {
+      const targetPath = path.posix.join(entry.kind === "article" ? "articles" : "papers", `${entry.slug}.md`);
+      const localLink = formatLocalLink(fromDir, targetPath, entry.title);
+      const label = entry.kind === "article" ? "Article" : "Paper";
+      return `- ${localLink} (${label}; ${entry.year ?? "Unknown"}; ${formatCell(entry.venue)})`;
+    })
+    .join("\n");
+}
+
+export function renderTopicsIndex(topicGroups) {
+  const lines = TOPIC_DEFINITIONS.map((topic) => {
+    const count = (topicGroups.get(topic.id) ?? []).length;
+    return `- [${topic.title}](./${topic.id}.md) (${count})\n  ${topic.description}`;
+  }).join("\n");
+
+  return `---
+summary: "Topic-based guides into the local-only agent-context archive"
+read_when:
+  - You want to browse the local archive by theme instead of by source type
+  - You are building a future reading list around a specific agent-system topic
+title: "Topic Indexes"
+---
+
+# Topic Indexes
+
+<Note>
+These indexes group the whole local archive by theme while leaving the cached
+Markdown files flat in their original \`papers/\` and \`articles/\` directories.
+</Note>
+
+${lines}
+`;
+}
+
+export function renderTopicPage(topic, entries) {
+  const articleEntries = entries.filter((entry) => entry.kind === "article");
+  const paperEntries = entries.filter((entry) => entry.kind === "paper");
+  const sections = [];
+
+  if (articleEntries.length > 0) {
+    sections.push(`## Articles\n\n${renderTopicList("topics", articleEntries)}`);
+  }
+  if (paperEntries.length > 0) {
+    sections.push(`## Papers and reports\n\n${renderTopicList("topics", paperEntries)}`);
+  }
+
+  return `---
+summary: '${topic.description.replaceAll("'", "''")}'
+read_when:
+  - You want a curated reading slice of the local agent-context archive
+  - You need related practice articles and papers in one place
+title: '${topic.title.replaceAll("'", "''")}'
+---
+
+# ${topic.title}
+
+<Note>
+${topic.description} This page is a local-only grouping aid for the cache under
+\`docs/research/agent-context-cache/\`.
+</Note>
+
+${sections.join("\n\n")}
+`;
+}