@jenga-ai/agent 3.1.1 → 3.4.0

package/bin/jenga.js

@@ -21,6 +21,11 @@ Usage:
   jenga status    Show router status and active session
   jenga doctor    Scan .agents/ and .claude/ for orphaned package files and clean up
                   interactively (alias: jenga clean). Add --dry-run to preview only.
+  jenga dashboard start [--port <n>] [--serve-app]
+                  Start the project dashboard API server (and optionally serve the
+                  built UI). Port defaults to 3001, or JENGA_API_PORT if set.
+  jenga dashboard open [--port <n>]
+                  Health-check the dashboard and open it in your browser.
 
 Options:
   --version, -v   Print version
@@ -67,6 +72,11 @@ async function main() {
       await runDoctor(args);
       break;
     }
+    case "dashboard": {
+      const { runDashboard } = await import("../lib/commands/dashboard.js");
+      await runDashboard(args);
+      break;
+    }
     default:
       console.error(`Unknown command: ${cmd}\n`);
       console.log(USAGE);

package/lib/commands/dashboard.js

@@ -0,0 +1,92 @@
+/**
+ * lib/commands/dashboard.js — `jenga dashboard start` / `jenga dashboard open` (E47_S03_T01)
+ *
+ * Reuse decision (documented per this task's `needs_docs: true`)
+ * ────────────────────────────────────────────────────────────────
+ * `project/app/ui/scripts/dashboard-start.cjs` and `dashboard-open.cjs` are standalone CommonJS
+ * scripts that parse `process.argv.slice(2)` directly at the top level and act on it immediately
+ * (start listening / run a health check then `process.exit`). They are not written as importable,
+ * args-parameterized functions.
+ *
+ * Two reuse strategies were considered:
+ *   1. Refactor their bodies into an exported function both the `.cjs` entry points and this
+ *      module call.
+ *   2. Spawn the existing scripts as a child process, forwarding args and exit code.
+ *
+ * Chosen: (2), spawning as a child process. Refactoring (1) would require restructuring two
+ * scripts that are independently relied on elsewhere (root `package.json`'s `dashboard:start`/
+ * `dashboard:open` npm scripts, `skills/j-dashboard`'s launcher, and
+ * `scripts/verify-consumer-install.sh`'s Scenario E regression check) for a task whose job is CLI
+ * wiring, not a dashboard-scripts refactor. Spawning with `stdio: 'inherit'` reuses the scripts
+ * completely verbatim — zero duplicated port-parsing / `--serve-app` / health-check logic — and
+ * guarantees byte-identical output and exit-code behavior to running the `.cjs` scripts directly
+ * (this is what AC1/AC2's "same behavior" requirement asks for literally). It also avoids the
+ * process-global side effects a same-process dynamic `import()` would risk: both scripts call
+ * `process.exit()` directly at top level, which would kill the parent `bin/jenga.js` process
+ * immediately and unrecoverably if loaded in-process.
+ */
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const projectRoot = join(__dirname, "..", "..");
+
+const SUBCOMMANDS = {
+  start: "dashboard-start.cjs",
+  open: "dashboard-open.cjs",
+};
+
+const DASHBOARD_USAGE = `
+Usage:
+  jenga dashboard start [--port <n>] [--serve-app]   Start the dashboard API server
+                                                      (and optionally serve the built UI)
+  jenga dashboard open [--port <n>]                  Health-check the dashboard and open it
+                                                      in your browser
+`.trim();
+
+export async function runDashboard(args, root = projectRoot) {
+  const [sub, ...rest] = args;
+
+  if (!sub || !(sub in SUBCOMMANDS)) {
+    if (sub) {
+      console.error(`Unknown dashboard subcommand: ${sub}\n`);
+    } else {
+      console.error("Missing dashboard subcommand.\n");
+    }
+    console.log(DASHBOARD_USAGE);
+    process.exit(1);
+    return;
+  }
+
+  const scriptPath = join(root, "project", "app", "ui", "scripts", SUBCOMMANDS[sub]);
+  if (!existsSync(scriptPath)) {
+    console.error(`Error: dashboard script not found at ${scriptPath}`);
+    process.exit(1);
+    return;
+  }
+
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [scriptPath, ...rest], {
+      stdio: "inherit",
+      env: process.env,
+    });
+
+    child.on("exit", (code, signal) => {
+      if (signal) {
+        // Re-raise the same signal on ourselves so a Ctrl-C style termination propagates
+        // cleanly to any caller inspecting our own exit status, rather than reporting a
+        // fabricated exit code for a signal-based termination.
+        process.kill(process.pid, signal);
+        return;
+      }
+      process.exit(code === null ? 1 : code);
+    });
+
+    child.on("error", (err) => {
+      console.error(`Error: failed to launch dashboard ${sub}: ${err.message}`);
+      process.exit(1);
+    });
+  });
+}

package/lib/skill-allow-list.json

@@ -1,13 +1,16 @@
 {
-  "generated_at": "2026-09-08T21:53:54.204Z",
-  "skill_count": 36,
+  "generated_at": "2026-09-14T18:42:41.263Z",
+  "skill_count": 41,
   "skills": [
     "brainstorm",
     "btw",
     "clearify",
     "close-story",
+    "cloud-connect",
     "commit",
     "continue",
+    "dashboard",
+    "dashboard-share",
     "deep-dive",
     "dev-done",
     "distribute",
@@ -27,6 +30,8 @@
     "jenga-permission-level",
     "lgtm",
     "pi-plan",
+    "playbook",
+    "playbook-new",
     "proceed",
     "publish",
     "reconcile",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "3.1.1",
+  "version": "3.4.0",
   "description": "An agentic development workflow for Claude Code, Copilot, and Codex — with a persistent Epic/Story/Task board, an isolated git worktree per task, and a separate tester agent that runs your test suite before anything is marked done.",
   "type": "module",
   "publishConfig": {
@@ -14,7 +14,9 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
+    "prepack": "npm run ui:build --prefix project/app --",
     "generate:legacy-paths": "node scripts/generate-legacy-shipped-paths.js",
+    "graph:populate": "node scripts/populate-knowledge-graph.js",
     "test": "bats tests/*.bats",
     "validate:npm-metadata": "bash scripts/validate_npm_metadata.sh",
     "ui:dev": "npm run ui:dev --prefix project/app --",
@@ -44,7 +46,19 @@
     "mcp/training_runner/package.json",
     "mcp/training_runner/package-lock.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "project/app/api/**/*.js",
+    "project/app/api/routes/**",
+    "project/app/api/lib/**",
+    "project/app/api/parsers/**",
+    "project/app/api/package.json",
+    "project/app/ui/scripts/**",
+    "project/app/ui/dist/**",
+    "project/app/package.json",
+    "project/app/ui/package.json",
+    "!project/app/api/**/*.test.js",
+    "!project/app/api/node_modules/**",
+    "!project/app/ui/node_modules/**"
   ],
   "repository": {
     "type": "git",
@@ -82,6 +96,11 @@
     "url": "https://knappkod.se/jenga-ai"
   },
   "license": "MIT",
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "gray-matter": "^4.0.3"
+  },
   "devDependencies": {
     "bats": "^1.13.0"
   }

package/project/app/api/lib/resolve-project-root.js

@@ -0,0 +1,120 @@
+/**
+ * @file project/app/api/lib/resolve-project-root.js
+ *
+ * Resolves the invoking (consumer) project's root directory for the dashboard API, so that
+ * `project/app/api/parsers/*.js` never has to compute its data root via a fixed
+ * `path.resolve(__dirname, '../../../...')` climb — the same defect pattern `E46_S01` already fixed
+ * for `/init` (see `skills/init/scripts/init.sh`'s `PKG_ROOT` idiom and
+ * `lib/generate-agent-context.js`'s `realpathSync` symlink-safe comparison). A `__dirname` climb only
+ * ever resolves correctly when this module runs from this monorepo's own checkout; once mirrored into
+ * a real consumer's `node_modules/@jenga-ai/agent/`, climbing a fixed number of levels lands inside or
+ * above `node_modules`, never at the consuming project's own root.
+ *
+ * Resolution order:
+ *   1. Explicit override — the `JENGA_PROJECT_ROOT` env var. This is the primary mechanism for the
+ *      real npm-consumer case: the dashboard's own launch path (`dashboard-start.cjs` /
+ *      `dashboard-open.cjs` / `server.js`) already knows the invoking `cwd` and can set this before
+ *      the parsers ever load.
+ *   2. Walk up from `cwd` (default `process.cwd()`) looking for a `project/board` directory — the
+ *      marker every Jenga-initialized project has (see `/init`'s scaffold) — bounded to a generous
+ *      but finite number of parent levels.
+ *   3. Fail loudly. Never silently fall back to `__dirname`, `cwd` itself, or `null` — an unresolved
+ *      project root is always a thrown `Error` with a descriptive message naming both the override
+ *      var and the path that was walked.
+ *
+ * Both the override path and every step of the walk-up are resolved through `fs.realpathSync`, so a
+ * symlinked invocation path (macOS `/tmp`/`$TMPDIR`, `npm link`, a symlinked home directory — the same
+ * bug class `E46_S01` fixed) does not break resolution.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const OVERRIDE_ENV_VAR = 'JENGA_PROJECT_ROOT';
+const PROJECT_MARKER = path.join('project', 'board');
+const MAX_WALK_LEVELS = 20;
+
+/**
+ * @param {string} dir absolute, already-realpath'd directory
+ * @returns {boolean} true if `dir/project/board` exists and is a directory
+ */
+function hasProjectMarker(dir) {
+  try {
+    return fs.statSync(path.join(dir, PROJECT_MARKER)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Resolve an absolute, symlink-free directory path, throwing a descriptive error (not a raw ENOENT)
+ * if it doesn't exist.
+ * @param {string} label human-readable label used in the error message
+ * @param {string} rawPath the path as provided (env var value or cwd)
+ * @returns {string}
+ */
+function realpathOrThrow(label, rawPath) {
+  const resolved = path.resolve(rawPath);
+  try {
+    return fs.realpathSync(resolved);
+  } catch (err) {
+    throw new Error(
+      `[resolve-project-root] ${label} "${rawPath}" (resolved to "${resolved}") does not exist: ${err.message}`
+    );
+  }
+}
+
+/**
+ * Determine the invoking consumer project's root directory.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.cwd] working directory to resolve/walk from (defaults to `process.cwd()`)
+ * @param {NodeJS.ProcessEnv} [options.env] environment to read the override from (defaults to `process.env`)
+ * @returns {string} absolute, symlink-resolved path to the project root
+ * @throws {Error} if no project root can be determined (fail loudly — never returns a wrong/empty path)
+ */
+function resolveProjectRoot({ cwd = process.cwd(), env = process.env } = {}) {
+  // 1. Explicit override.
+  const override = env && env[OVERRIDE_ENV_VAR];
+  if (override) {
+    const resolvedOverride = realpathOrThrow(`${OVERRIDE_ENV_VAR}`, override);
+    if (!fs.statSync(resolvedOverride).isDirectory()) {
+      throw new Error(
+        `[resolve-project-root] ${OVERRIDE_ENV_VAR} "${override}" (resolved to "${resolvedOverride}") is not a directory.`
+      );
+    }
+    return resolvedOverride;
+  }
+
+  // 2. Walk up from cwd looking for a project/board marker. realpath the starting point once so
+  // every subsequent path.dirname() step stays symlink-free.
+  let startDir;
+  try {
+    startDir = fs.realpathSync(path.resolve(cwd));
+  } catch (err) {
+    throw new Error(
+      `[resolve-project-root] cwd "${cwd}" does not exist: ${err.message}. ` +
+        `Set ${OVERRIDE_ENV_VAR} to your project's root directory instead.`
+    );
+  }
+
+  let dir = startDir;
+  for (let i = 0; i < MAX_WALK_LEVELS; i++) {
+    if (hasProjectMarker(dir)) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+
+  // 3. Fail loudly.
+  throw new Error(
+    `[resolve-project-root] Could not locate a project root (looked for a "${PROJECT_MARKER}" ` +
+      `directory) walking up from "${startDir}" (${MAX_WALK_LEVELS} levels). ` +
+      `Set the ${OVERRIDE_ENV_VAR} environment variable to your project's root directory, or run ` +
+      `the dashboard from inside a Jenga-initialized project.`
+  );
+}
+
+module.exports = { resolveProjectRoot, OVERRIDE_ENV_VAR, PROJECT_MARKER, MAX_WALK_LEVELS };

package/project/app/api/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "jenga-dashboard-api",
+  "version": "1.0.0",
+  "description": "Jenga AI dashboard API server",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "test": "node parsers/knowledge-graph.test.js && node lib/resolve-project-root.test.js && node parsers/lib/markdown-dir-reader.test.js && node parsers/todo.test.js && node parsers/documentation.test.js && node parsers/rapports.test.js"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "express": "^4.18.2",
+    "gray-matter": "^4.0.3"
+  }
+}

package/project/app/api/parsers/architecture.js

@@ -0,0 +1,72 @@
+/**
+ * @file project/app/api/parsers/architecture.js
+ * Reads package.json and project.config.json to return tech stack + dependency info.
+ * The SAD map itself is sourced from project/knowledge-graph/graph.json via ./knowledge-graph.js
+ * (E08_S05_T01) rather than parsed live from board epics/stories.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { readSADMap } = require('./knowledge-graph');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — see project/app/api/lib/resolve-project-root.js.
+const ROOT = resolveProjectRoot();
+
+/**
+ * Safely read and parse a JSON file.
+ * @param {string} filePath
+ * @returns {Object|null}
+ */
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Parse project config files into architecture metadata.
+ * @returns {Promise<Object>}
+ */
+async function parseArchitecture() {
+  const pkg    = readJson(path.join(ROOT, 'package.json'));
+  const config = readJson(path.join(ROOT, 'project.config.json'));
+
+  // Build tech stack from project.config.json fields + package metadata
+  const tech_stack = [];
+  if (config) {
+    if (config.workflow)         tech_stack.push({ name: config.workflow, description: `Workflow engine (v${(pkg && pkg.version) || 'unknown'})` }); // E26_S01_T03: version from package.json, not deprecated workflow_version
+    if (config.description)      tech_stack.push({ name: 'Jenga AI', description: config.description });
+  }
+  if (pkg) {
+    tech_stack.push({ name: 'Node.js', description: 'JavaScript runtime' });
+    const express = pkg.dependencies && pkg.dependencies['express'];
+    if (express) tech_stack.push({ name: 'Express', description: `HTTP server framework (${express})` });
+  }
+
+  // Build dependency list
+  const dependencies = [];
+  if (pkg) {
+    for (const [name, version] of Object.entries(pkg.dependencies || {})) {
+      dependencies.push({ name, version, type: 'runtime' });
+    }
+    for (const [name, version] of Object.entries(pkg.devDependencies || {})) {
+      dependencies.push({ name, version, type: 'devDependency' });
+    }
+  }
+
+  return {
+    tech_stack,
+    dependencies,
+    sad_map: readSADMap(),
+    _sources: {
+      package_json: pkg ? { name: pkg.name, version: pkg.version } : null,
+      project_config: config || null,
+    },
+  };
+}
+
+module.exports = { parseArchitecture };

package/project/app/api/parsers/board.js

@@ -0,0 +1,141 @@
+/**
+ * @file project/app/api/parsers/board.js
+ * Parses markdown files from project/board/ into a nested epic→story→task tree.
+ *
+ * E06_S05_T04 — each item whose id is named by an active entry in the project's `project/todo.md`
+ * additionally carries `_queued: true`. This is purely *informational* provenance ("the user has
+ * queued this for execution"); the decision of what to do with it belongs to the consumer. The
+ * Active Sprint tab's column logic (`project/app/ui/src/components/board/kanbanColumns.js`) uses it
+ * to promote `Pending`/`Backlog` items into the In Progress column; the Backlog tab ignores it
+ * entirely. Items that aren't referenced get **no new field at all**, so a project with no
+ * `todo.md` produces a byte-identical payload to the pre-T04 parser.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+const { readTodoRefs } = require('./todo');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — the old `path.resolve(__dirname, '../../../board')` only ever landed correctly when this
+// module ran from this monorepo's own checkout.
+const BOARD_ROOT = path.join(resolveProjectRoot(), 'project', 'board');
+
+/**
+ * Read all .md files from a directory (non-recursive).
+ * @param {string} dir
+ * @returns {{ file: string, data: Object, content: string }[]}
+ */
+function readMarkdownDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => {
+      const filePath = path.join(dir, f);
+      try {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        const parsed = matter(raw);
+        return { file: f, data: parsed.data, content: parsed.content.trim() };
+      } catch (err) {
+        console.warn(`[board] Skipping malformed file: ${filePath} — ${err.message}`);
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Board ids referenced by active entries in the project's `project/todo.md`, as an upper-cased Set
+ * for case-insensitive lookup (E06_S05_T04).
+ *
+ * Failure-tolerant by design: `readTodoRefs()` already reports a missing/unreadable file as
+ * `exists: false` rather than throwing, and this extra guard covers anything unexpected beyond that
+ * (e.g. an unresolvable project root). A broken or absent `todo.md` degrades to "nothing is queued"
+ * — i.e. exactly the pre-T04 behavior — and never turns a working board read into a 500.
+ *
+ * @returns {Set<string>}
+ */
+function loadQueuedIds() {
+  try {
+    const { refs } = readTodoRefs();
+    return new Set(refs.map((r) => String(r).toUpperCase()));
+  } catch (err) {
+    console.warn(`[board] Could not read todo.md refs — ${err.message}. No items will be marked queued.`);
+    return new Set();
+  }
+}
+
+/**
+ * `{ _queued: true }` if `id` is queued, otherwise an empty object — spread into an item so
+ * unreferenced items keep their exact pre-T04 shape (no `_queued: false` noise).
+ * @param {Set<string>} queuedIds
+ * @param {string|undefined} id
+ * @returns {{ _queued?: boolean }}
+ */
+function queuedFlagFor(queuedIds, id) {
+  return typeof id === 'string' && queuedIds.has(id.toUpperCase()) ? { _queued: true } : {};
+}
+
+/**
+ * Parse the full board into an array of epic objects with nested stories and tasks.
+ * @returns {Promise<Object[]>}
+ */
+async function parseBoard() {
+  const queuedIds = loadQueuedIds();
+
+  const epicsDir  = path.join(BOARD_ROOT, 'epics');
+  const storiesDir = path.join(BOARD_ROOT, 'stories');
+  const tasksDir  = path.join(BOARD_ROOT, 'tasks');
+
+  const epicFiles  = readMarkdownDir(epicsDir);
+  const storyFiles = readMarkdownDir(storiesDir);
+  const taskFiles  = readMarkdownDir(tasksDir);
+
+  // Build tasks map keyed by story_id
+  const tasksByStory = {};
+  for (const t of taskFiles) {
+    const sid = t.data.story_id;
+    if (!sid) continue;
+    if (!tasksByStory[sid]) tasksByStory[sid] = [];
+    tasksByStory[sid].push({
+      ...t.data,
+      ...queuedFlagFor(queuedIds, t.data.id),
+      _content: t.content,
+      _file: t.file,
+    });
+  }
+
+  // Build stories map keyed by epic_id
+  const storiesByEpic = {};
+  for (const s of storyFiles) {
+    const eid = s.data.epic_id;
+    if (!eid) continue;
+    if (!storiesByEpic[eid]) storiesByEpic[eid] = [];
+    const storyId = s.data.id;
+    storiesByEpic[eid].push({
+      ...s.data,
+      ...queuedFlagFor(queuedIds, storyId),
+      _content: s.content,
+      _file: s.file,
+      tasks: storyId ? (tasksByStory[storyId] || []) : [],
+    });
+  }
+
+  // Build epic objects
+  const epics = epicFiles.map((e) => {
+    const epicId = e.data.id;
+    return {
+      ...e.data,
+      ...queuedFlagFor(queuedIds, epicId),
+      _content: e.content,
+      _file: e.file,
+      stories: epicId ? (storiesByEpic[epicId] || []) : [],
+    };
+  });
+
+  return epics;
+}
+
+module.exports = { parseBoard };

package/project/app/api/parsers/documentation.js

@@ -0,0 +1,125 @@
+/**
+ * @file project/app/api/parsers/documentation.js
+ * Aggregates the project's curated reference documentation into one flat, categorized list of
+ * full-content entries — the "Documentation" tab's backend source (`E58_S01_T04`, consumed by
+ * `E58_S01_T05`'s `GET /v1/documentation` route).
+ *
+ * Four sources, none of which any existing parser touches today:
+ *   - `project/PROJECT_SUMMARY.md`                    -> category `summary`
+ *   - `README.md` (repo root)                         -> category `readme`
+ *   - `docs/STRATEGY.md`                               -> category `strategy`
+ *   - every `.md` file under `project/documentation/examples/` -> category `example`
+ *
+ * The first three are single named files, read directly and parsed with `gray-matter` for
+ * consistency with the directory-based path even though they rarely carry frontmatter. The fourth
+ * reuses `E58_S01_T01`'s shared `readMarkdownDirRecursive()` directory reader.
+ *
+ * Every returned entry shares the same field shape used by `E58_S01_T03`'s rapports aggregate:
+ *   { file, data, content, category, date }
+ * `readMarkdownDirRecursive()`'s own return contract does not include `date` (see its JSDoc), so
+ * it is added here per entry — same pattern already used by `parsers/ideas.js` (E58_S01_T02) and
+ * `parsers/rapports.js`: prefer frontmatter's `date` field, stringified, else `null`.
+ *
+ * A missing single-file source (e.g. no `docs/STRATEGY.md` yet in some projects) is skipped, not
+ * thrown — the same non-throwing precedent used throughout `api/parsers/`.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+const { readMarkdownDirRecursive } = require('./lib/markdown-dir-reader');
+
+/**
+ * Derive the `date` field for an entry from its parsed frontmatter, matching the
+ * `rapports.js`/`ideas.js` convention: prefer frontmatter's `date`, stringified; else `null`.
+ *
+ * Unquoted `YYYY-MM-DD` frontmatter values are parsed by gray-matter/js-yaml into a native `Date`
+ * object rather than a plain string (the same gotcha `E06_S05_T03` hit and fixed for
+ * `isStaleDeployedProd()` — see `project/rapports/problems/E06_S05_T03-stale-filter-fails-on-real-gray-matter-date-objects.md`).
+ * A bare `String(date)` on a `Date` produces a full JS date-with-timezone string, not the
+ * `YYYY-MM-DD` form callers expect, so `Date` inputs are explicitly reduced to their ISO calendar
+ * date (`toISOString().slice(0, 10)`) instead.
+ * @param {Object} data - gray-matter-parsed frontmatter object.
+ * @returns {string|null}
+ */
+function deriveDate(data) {
+  if (!data || !data.date) return null;
+  if (data.date instanceof Date) return data.date.toISOString().slice(0, 10);
+  return String(data.date);
+}
+
+/**
+ * Read and parse a single markdown file into an aggregate entry, or `null` if the file does not
+ * exist or fails to read/parse (skipped with a `console.warn`, never thrown).
+ * @param {string} absPath - absolute path to the file.
+ * @param {string} fileLabel - value for the returned entry's `file` field (e.g. "README.md").
+ * @param {string} category - value for the returned entry's `category` field.
+ * @returns {{ file: string, data: Object, content: string, category: string, date: string|null }|null}
+ */
+function readSingleMarkdownFile(absPath, fileLabel, category) {
+  if (!fs.existsSync(absPath)) return null;
+
+  try {
+    const raw = fs.readFileSync(absPath, 'utf8');
+    const parsed = matter(raw);
+    return {
+      file: fileLabel,
+      data: parsed.data,
+      content: parsed.content.trim(),
+      category,
+      date: deriveDate(parsed.data),
+    };
+  } catch (err) {
+    console.warn(`[documentation] Skipping malformed file: ${absPath} — ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Aggregate all documentation sources into one flat list of full-content, categorized entries.
+ * Returns [] entries for any source that does not exist rather than throwing.
+ * @returns {Promise<Object[]>}
+ */
+async function readDocumentation() {
+  const root = resolveProjectRoot();
+  const results = [];
+
+  const singleFileSources = [
+    {
+      absPath: path.join(root, 'project', 'PROJECT_SUMMARY.md'),
+      fileLabel: 'PROJECT_SUMMARY.md',
+      category: 'summary',
+    },
+    {
+      absPath: path.join(root, 'README.md'),
+      fileLabel: 'README.md',
+      category: 'readme',
+    },
+    {
+      absPath: path.join(root, 'docs', 'STRATEGY.md'),
+      fileLabel: 'STRATEGY.md',
+      category: 'strategy',
+    },
+  ];
+
+  for (const source of singleFileSources) {
+    const entry = readSingleMarkdownFile(source.absPath, source.fileLabel, source.category);
+    if (entry) results.push(entry);
+  }
+
+  const examplesRoot = path.join(root, 'project', 'documentation', 'examples');
+  // Fixed category for every file under this root, regardless of subdirectory — passed as a
+  // function per readMarkdownDirRecursive()'s categorize contract (a bare string is not one of
+  // its two supported forms and would silently fall back to 'uncategorized').
+  const exampleEntries = readMarkdownDirRecursive(examplesRoot, () => 'example');
+  for (const entry of exampleEntries) {
+    results.push({ ...entry, date: deriveDate(entry.data) });
+  }
+
+  return results;
+}
+
+module.exports = { readDocumentation };