@jenga-ai/agent 3.2.0 → 3.4.0

package/README.md

@@ -35,7 +35,7 @@ Jenga AI solves each of these with structure: persistent engineering context mai
 
 - **Three specialised agents** — Scrum Master, Developer, Tester — each with a distinct role and no self-graded work
 - **A persistent, Kanban-style scrum board** — Epics, Stories, and Tasks tracked as Markdown files with structured frontmatter, surviving every session boundary
-- **A coordinated skill pipeline — one agentic workflow, not a command list** — planning skills (`j.pi-plan`, `j.todo`) hand off to execution skills (`j.do`, `j.dooo`), which hand off to review skills (`j.status`, `j.reconcile`), each stage reading and writing the same board state — the old bare `/<name>` form still works everywhere as a permanent alias
+- **A coordinated skill pipeline — one agentic workflow, not a command list** — planning skills (`j.pi-plan`, `j.todo`) hand off to execution skills (`j.do`, `j.dooo`), which hand off to review skills (`j.status`, `j.reconcile`), each stage reading and writing the same board state
 - **An event-driven trigger queue** — async handoffs between agents with a full audit trail in `project/logs/events.json`
 - **Isolated git worktrees per task** — the Developer never works directly on your main branch
 - **Works with any AI coding agent or AI-native IDE** — Claude Code, GitHub Copilot, and Codex CLI are all supported today
@@ -56,7 +56,7 @@ The Tester doesn't read your code and form an opinion about it. It executes the
 
 `CLAUDE.md` and `AGENTS.md` are generated unconditionally by `j.init` — every agent gets a real, populated root-level context file, not just a pointer. If either file already exists as a genuine pre-existing user file, Jenga leaves it untouched, writes its own copy as `J-CLAUDE.md` / `J-AGENTS.md`, and inserts a short reference line into the original.
 
-`.github/copilot-instructions.md` follows a different path, because Copilot needs it before `j.init` may ever run: `npm install` triggers `scripts/postinstall.js`, which writes it unconditionally and non-interactively, so `j.<name>` routing (the bare `/<name>` form still resolves too, as a permanent alias) works from a consumer's very first Copilot command. A later `jenga init` run refines that same file using the project's actual chosen skills path.
+`.github/copilot-instructions.md` follows a different path, because Copilot needs it before `j.init` may ever run: `npm install` triggers `scripts/postinstall.js`, which writes it unconditionally and non-interactively, so `j.<name>` (and `/j-<name>`) routing works from a consumer's very first Copilot command. A later `jenga init` run refines that same file using the project's actual chosen skills path.
 
 ---
 
@@ -171,6 +171,8 @@ Or clone directly:
 
 Run `j.status` at any time to see where the project stands.
 
+📖 **New to Jenga AI?** The [Intro Guide](https://samwelmunga.github.io/jenga-npm/getting-started.html) walks through the philosophy, the three pillars (role separation, board hierarchy, session continuity), and a full first-15-minutes walkthrough for both a new project and an existing codebase — mirrored at [project/.wiki/intro-guide.md](project/.wiki/intro-guide.md).
+
 **CLI maintenance commands.** The `jenga` binary installed alongside the package (`jenga --help`)
 also ships a couple of maintenance commands, distinct from the in-agent `j.<name>` skills above:
 
@@ -196,29 +198,67 @@ The framework is platform-agnostic by design — any AI agent that can read Mark
 
 ## Skills (Slash Commands)
 
-Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your AI agent or IDE's command interface — the old bare `/<name>` form also keeps working permanently as an alias. A handful of the most foundational commands:
+Skills live in `.agents/skills/<name>/SKILL.md`. Invoke with `j.<name>` in your AI agent or IDE's command interface, or with its `/j-<name>` directory form (e.g. `/j-init`) — both resolve to the same skill. A handful of the most foundational commands:
 
-> ⚠️ **Command collision with a host tool?** Some host tools ship their own built-in command that can
-> shadow one of Jenga's — e.g. GitHub Copilot's own built-in `/init`, which could silently shadow
-> Jenga's `/init` skill. Every skill (except `init`, already handled) has a collision-safe `/j-<name>`
-> directory-twin form — e.g. `/j-init` — that always resolves to the genuine Jenga skill regardless of
-> what else is installed. This is separate from the `j.<name>` prefix form above: it's a real duplicate
-> directory under a distinct name, not a routing alias, generated and kept in sync via
-> `scripts/generate-j-alias.sh`. If a `j.<name>` or bare `/<name>` command isn't behaving as
-> documented, try its `/j-<name>` form instead.
+> **Why `/j-<name>`, not a bare `/<name>`?** Some host tools ship their own built-in command that can
+> shadow one of Jenga's — e.g. GitHub Copilot's own built-in `/init`. Jenga sidesteps this
+> structurally: every skill ships under the collision-safe `/j-<name>` directory name, so there's no
+> bare `/<name>` directory for a host tool's own command to collide with in the first place.
+> `/j-<name>` isn't a fallback to reach for when something misbehaves — it's simply how the skill is
+> named. Two permanent exceptions ship bare-only, with no `/j-<name>` form: `/jenga` and
+> `/jenga-permission-level` — deliberately excluded, since neither is the kind of skill a host tool's
+> own built-in command is likely to name-collide with.
 
 | Command | Description |
 |---|---|
 | `j.init` | Scaffold project directories, `workflow.json`, `PROJECT_SUMMARY.md`, initial git commit |
-| `j.jenga` | Interactive-by-default board orchestrator — bare shows a picker + confirmation tree, `<ids>` scopes and confirms, `*` runs fully automated with no prompts |
 | `j.todo` | Add missions to `project/todo.md` linked to epics and stories |
 | `j.do` | Execute tasks from the scrum board, drives the Developer agent through the full loop |
 | `j.status` | Print a full scrum board overview — epics, stories, tasks, rapports, queue depth |
 
+### `/jenga` — one command, several behaviors
+
+`/jenga` doesn't fit the table above, because what it does depends entirely on how it's invoked:
+
+| Invocation | Behavior |
+|---|---|
+| `/jenga` (bare) | Renders a picker + confirmation tree before scoping the run |
+| `/jenga <ids>` | Resolves an explicit fuzzy-ID scope and confirms it |
+| `/jenga *` | Fully automated — decomposes, queues, and executes everything eligible, no prompts |
+| `/jenga <free text>` | Natural-language dispatch — matches a single skill directly, or proposes a multi-skill [playbook](#playbooks) when the request spans more than one |
+
+It's one of the two permanent bare-only exceptions noted above — there's no `/j-jenga` form.
+
 > 📖 **Full skill list** (planning, review, committing & maintenance commands): [Docs site](https://samwelmunga.github.io/jenga-npm/skills.html) — mirrored at [project/.wiki/documentation.md#skills](project/.wiki/documentation.md#skills)
 
 ---
 
+## Playbooks
+
+Some workflows are always the same sequence of skills — plan it, build it, commit it. A **playbook** is a named, pre-defined chain of skills, run and confirmed as one unit instead of typed out one skill at a time.
+
+Invoke one by describing what you want in plain language to `j.jenga` — it proposes a matching playbook as a numbered, editable list before anything runs — or name one directly:
+
+```
+j.playbook idea-to-committed
+```
+
+which resolves to:
+
+```
+j.brainstorm → j.todo → j.do → j.commit
+```
+
+Calling `j.playbook` with no id prints a table of every available playbook (id, name, and steps) instead of resolving one.
+
+Nothing executes until you confirm the chain, and any step can be unchecked first. `brainstorm-to-mirror` extends the same chain through `j.dev-done` and `j.mirror-public` for a full public release; `understand-then-ship` prepends `j.uncharted` investigation for unfamiliar code before running the same pipeline.
+
+When a step forwards its result into the next one, that value has a declared **output type** (a plain string, a list of board IDs, a list of files) so the chain can be validated before it runs. See [Getting Started](https://samwelmunga.github.io/jenga-npm/getting-started.html#how-playbooks-know-what-a-skill-produces) for how that works.
+
+Want your own recurring chain? `j.playbook-new` walks you through authoring one — id, name, description, keywords, examples, and an ordered list of skills — writes it to `project/.playbooks/<id>.json` alongside the built-in ones, and self-validates the result before reporting success.
+
+---
+
 ## When to Use Jenga AI
 
 **Use it when:**

package/agents/developer.md

@@ -225,6 +225,21 @@ This list is fixed and verbatim across both this file and `agents/tester.md` —
 
 You do not run tests. Before calling the tester agent, **write an execution summary** to `project/documentation/summaries/<E##_S##_T##>-summary.md` using `$([ -f templates/EXECUTION_SUMMARY_TEMPLATE.md ] && echo templates/EXECUTION_SUMMARY_TEMPLATE.md || echo node_modules/@jenga-ai/agent/templates/EXECUTION_SUMMARY_TEMPLATE.md)`. Fill in all sections — what was implemented, files changed, commit SHAs, acceptance criteria coverage, and any concerns for the tester. This step is mandatory before every tester invocation.
 
+### Tester Concurrency Cap (acquire before invoking, release on every exit)
+
+Before any in-session tester invocation described below, acquire a tester slot:
+
+```
+scripts/acquire-concurrency-slot.sh tester <task_id> <orchestrator_session_id>
+```
+
+`<orchestrator_session_id>` is the same session-id concept already used elsewhere in this file to name `project/queue/concurrency-slots-<session_id>.json` and `project/queue/handoffs/developer-<session_id>-<task_id>.json` — thread through that same value rather than inventing a new one (when this developer session is itself the orchestrating session, that is simply the current session's `session_id`).
+
+- **On success (exit 0):** proceed with the tester invocation exactly as documented below, in-session. When the tester's session ends — regardless of outcome (`Passed`, `Failed`, `Rejected`, or `"error"`) — call `scripts/release-concurrency-slot.sh tester <task_id> <orchestrator_session_id>`. Every exit path out of the tester invocation releases the slot; a failed or errored tester run is not an exception to this.
+- **On a full cap (non-zero exit):** do not poll or wait for a slot to free up — the "Prohibited — ad-hoc completion-polling loops" rule (Session Start — Queue Processing, above) applies here without exception; a retry loop waiting on the counter file would be exactly the kind of ad-hoc polling that rule forbids. Instead, skip the in-session tester invocation entirely and fall back to the existing mandatory mechanism in "Session End — Handoff" above: write `project/queue/handoffs/developer-<session_id>-<task_id>.json` in its documented shape (`status: "implementation_complete"`), unchanged from what's already specified there. A later tester session picks up the work via `on_session_end.sh`'s normal routing to the tester queue. A routine cap-full condition is expected flow control, not a blocking issue — do not write a problem rapport for it.
+
+This gate governs only the in-session tester call described in this section; it does not change worktree creation, commit discipline, or the handoff file's shape.
+
 When you reach a meaningful milestone within a task where verification is appropriate — or when the task is complete — call the tester agent. Before invoking the tester, compose a short `resolved_context` digest of what you already resolved during implementation — which files you touched and why, which acceptance criteria map to which changes, any conventions or precedent you followed — and persist it by calling `bash "$([ -f scripts/write-context-digest.sh ] && echo scripts/write-context-digest.sh || echo node_modules/@jenga-ai/agent/scripts/write-context-digest.sh)" --agent developer --session-id <session_id> --task-id <task_id>` with that content (stays under the ~100-line/few-hundred-token cap defined in `$([ -f templates/SCRUM_BOARD_SCHEMA.md ] && echo templates/SCRUM_BOARD_SCHEMA.md || echo node_modules/@jenga-ai/agent/templates/SCRUM_BOARD_SCHEMA.md)`'s `resolved_context` subsection; the script rejects oversized input rather than truncating it). Place the script's returned path in the sender object's `resolved_context` field. Always pass the following sender object when invoking the tester:
 
 ```json
@@ -245,7 +260,7 @@ When you reach a meaningful milestone within a task where verification is approp
 
 All fields must be present except `resolved_context`, which is optional. This digest is a starting point only, never a restriction: the tester may and should still read the full execution summary, the diff itself, or any other source file when the digest doesn't cover what it needs. In addition to the sender object, include a short plain-text implementation summary: what was implemented, which files changed, and any known edge cases or concerns. Reference the execution summary at `project/documentation/summaries/<E##_S##_T##>-summary.md` for full detail.
 
-Wait for the tester's response before continuing. If the tester returns `"failed"` or `"error"`, address the findings before proceeding.
+Wait for the tester's response before continuing. If the tester returns `"failed"` or `"error"`, address the findings before proceeding. Either way — pass, fail, or error — release the tester slot now per "Tester Concurrency Cap" above; the slot must not remain held once the tester's response has been received.
 
 ---
 

package/agents/scrum-master.md

@@ -77,6 +77,7 @@ This is a self-contained procedure, not a session-start-only step. It may be inv
    - `status_review`: Review the scrum board for any tasks or stories whose status should be updated based on recent activity.
    - `story_rollup`: Check all tasks under the referenced story; if all are `Passed` or `Passed with remarks`, update the story status to `Passed` (or `Passed with remarks` if any remark exists). Then check epic rollup (see Rollup Logic).
    - `elicitation_resume`: A `j.uncharted` conversational architecture elicitation session (`onboard`'s default flow, or `segment --mode investigate` — E20_S08_T03) ended mid-run without converging. Read `state_file` (`project/queue/elicitation-state/<elicitation_id>.json`, written by `skills/uncharted/scripts/elicitation-state.sh`) to see exactly where it left off — which nodes already converged, which are still pending or flagged, and any directory-triage/checkpoint data already confirmed — then resume the conversational flow documented in `skills/uncharted/SKILL.md`'s Multi-Session Persistence subsection from that point rather than restarting the elicitation from scratch. If the state file is missing or unreadable, report that to the user rather than silently starting a fresh elicitation under the same id.
+   - `capacity_starvation`: `skills/do/SKILL.md`'s per-session concurrency cap (E32_S15) blocked the same board item for 3 consecutive dispatch waves because its role (`developer` or `tester`) stayed at cap. Surface a plain warning naming the affected item and its consecutive-block wave count, suggesting the configured cap (`max_concurrent_developers` / `max_concurrent_testers` in `project/configs/scope-thresholds.json`) may be too low or the session may be starved. No automatic remediation — this trigger is informational only.
    - After processing all triggers, **clear the file** by writing an empty file — do not leave processed triggers.
 
 2. **Check `project/queue/project_summary_updates.jsonl`** — If non-empty, review each proposed update and apply, revise, or reject it with a short note. Clear the file after processing.

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-10T17:03:15.911Z",
-  "skill_count": 37,
+  "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",
@@ -28,6 +31,7 @@
     "lgtm",
     "pi-plan",
     "playbook",
+    "playbook-new",
     "proceed",
     "publish",
     "reconcile",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jenga-ai/agent",
-  "version": "3.2.0",
+  "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 };