@hanzlaa/rcode 4.1.1 → 4.3.0

package/rcode/workflows/plan.md

@@ -64,6 +64,20 @@ Valid rcode subagent types (use exact names — do not fall back to 'general-pur
 
 <process>
 
+## 0. Project-Status Preflight
+
+```bash
+PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || echo uninitialized)
+```
+
+If `PROJECT_STATUS` is `uninstalled`, `uninitialized`, or `stub`:
+
+```
+Project not initialized. Run /rcode-init first (or /rcode-new-project for a greenfield project), then return here.
+```
+
+Stop. Do not proceed until `project-status` returns `real`.
+
 ## 1. Initialize
 
 Load all context in one call (paths only to minimize orchestrator context):
@@ -117,7 +131,7 @@ fi
 
 When `GAPS_MODE=true`, the workflow switches to **gap-closure planning**: read the phase's VERIFICATION.md, extract verification gaps classified `gap_found` or `partial`, and produce a single new numbered plan file (`NNN-NN-SPRINT.md`) that closes them. Research, CONTEXT.md gating, and VALIDATION.md creation are skipped — gaps are grounded in already-shipped code, not new design work.
 
-**Detect from-stub mode (closes #736):**
+**Detect from-stub mode:**
 ```bash
 if [[ "$ARGUMENTS" =~ (^|[[:space:]])--from-stub($|[[:space:]]) ]]; then
   FROM_STUB_MODE=true
@@ -154,7 +168,7 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
 
 **Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
 
-**TASKS.md ingestion (#385 chain).** If the phase directory contains a `TASKS.md` file (typically auto-extracted by `/rcode-add-phase` from a bulk `/rcode-quick` or `/rcode-do` route), read it now:
+**TASKS.md ingestion.** If the phase directory contains a `TASKS.md` file (typically auto-extracted by `/rcode-add-phase` from a bulk `/rcode-quick` or `/rcode-do` route), read it now:
 
 ```bash
 TASKS_FILE=".planning/phases/${padded_phase}-${phase_slug}/TASKS.md"
@@ -187,6 +201,12 @@ Exit workflow.
 ## 3. Validate Phase
 
 ```bash
+# Stub-ROADMAP guard — emit a warning if ROADMAP.md has no real phase headings.
+ROADMAP_PHASE_COUNT=$(grep -c "^## Phase " "${ROADMAP_PATH}" 2>/dev/null || echo 0)
+if [ "${ROADMAP_PHASE_COUNT}" -eq 0 ]; then
+  echo "⚠ WARN: ROADMAP.md appears to be a stub — add real ## Phase headings before running plan."
+  exit 1
+fi
 PHASE_INFO=$(node ".rcode/bin/rcode-tools.cjs" roadmap get-phase "${PHASE}")
 ```
 
@@ -326,7 +346,7 @@ Otherwise use AskUserQuestion:
 If "Continue without context": Proceed to step 5.
 If "Run discuss-phase first":
   **IMPORTANT:** Do NOT invoke discuss-phase as a nested Skill/Task call — AskUserQuestion
-  does not work correctly in nested subcontexts (#1009). Instead, display the command
+  does not work correctly in nested subcontexts. Instead, display the command
   and exit so the user runs it as a top-level command:
   ```
   Run this command first, then re-run /rcode-plan {X} ${RCODE_WS}:
@@ -362,7 +382,7 @@ Always offer exactly three numbered options:
 
 Wait for the user's choice before proceeding. Do not auto-select.
 
-**If user picks option 1 (Add more plans) — issue #650:**
+**If user picks option 1 (Add more plans):**
 
 This is **NOT** a license to hand-write a new SPRINT.md inline. Continue down the
 normal pipeline exactly as if no plans existed yet:
@@ -376,8 +396,7 @@ normal pipeline exactly as if no plans existed yet:
    first-time plan. The "PLANNED ✓" banner is gated on a passing CHECK.md.
 
 A run that emits a SPRINT.md without a corresponding planner Task() invocation
-in the same turn is a malfunction — see issue #650. Stop and report instead of
-shipping a hand-rolled plan.
+in the same turn is a malfunction. Stop and report instead of shipping a hand-rolled plan.
 
 **If user picks option 3 (Replan from scratch):**
 
@@ -390,7 +409,7 @@ still mandatory.
 
 Display a sprint summary table (sprint id → one-line goal).
 
-Then run a **best-effort codebase overlap check** before showing the execute prompt — Closes #596.
+Then run a **best-effort codebase overlap check** before showing the execute prompt.
 
 **This check is always informational. It never blocks, never errors, never fails the workflow.** If any step below cannot complete for any reason, skip it silently and proceed straight to the execute prompt.
 
@@ -534,7 +553,7 @@ It never silently passes a plan where two sprints create the same file.
 - **`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation (step 12)
 - **`## PLANNING INCONCLUSIVE`:** Show attempts, offer: Add context / Retry / Manual
 
-**Sprint count guard (token cost protection — closes #584):**
+**Sprint count guard (token cost protection):**
 
 After planner returns `## PLANNING COMPLETE`, immediately count sprint files:
 
@@ -670,7 +689,7 @@ If thinking_partner disabled: skip this block entirely.
 
 ## 12. Revision Loop (Max 3 Iterations, 1 in autonomous/yolo mode)
 
-**Mode-based iteration cap (token cost protection — closes #585):**
+**Mode-based iteration cap (token cost protection):**
 
 ```bash
 MAX_ITERATIONS=$($TOOL config-get workflow.max_checker_iterations 2>/dev/null || echo "")
@@ -686,7 +705,7 @@ Track `stall_reentry_count` (starts at 0; incremented each time "Adjust approach
 
 **If iteration_count < MAX_ITERATIONS:**
 
-**Sprint-checker malfunction guard (BLOCKER-class — added in v3.1.0 after #440):**
+**Sprint-checker malfunction guard (BLOCKER-class):**
 
 Before parsing issues, verify the checker actually invoked tools. The checker MUST exhibit at least one of these evidence markers in its return:
 
@@ -695,11 +714,11 @@ Before parsing issues, verify the checker actually invoked tools. The checker MU
 - At least one `path:` field in any block (e.g. `path: src/components/Foo.tsx:42`)
 - A summary line of the form `Verified N of M files` or `Checked N symbols`
 
-If NONE of these evidence markers are present, the checker malfunctioned (returned narrative without invoking tools — see #440). BLOCK execution:
+If NONE of these evidence markers are present, the checker malfunctioned (returned narrative without invoking tools). BLOCK execution:
 
 ```
 Display: "Sprint-checker returned without evidence of tool use — likely
-         malfunctioned (cf. issue #440). Refusing to advance the plan
+         malfunctioned (returned narrative without tool use). Refusing to advance the plan
          on unverified output. Re-run /rcode-plan or inspect the agent."
 Halt the workflow with a non-zero exit signal.
 ```
@@ -771,7 +790,7 @@ Display: `Max iterations reached. {N} issues remain:` + issue list
 
 Offer: 1) Force proceed, 2) Provide guidance and retry, 3) Abandon
 
-## 12.5. Wave Parallelism File-Overlap Check (added in v3.1.0 after #442)
+## 12.5. Wave Parallelism File-Overlap Check
 
 Before declaring plans ready, validate the wave-parallelism rule the planner declares: **same wave + overlapping `files_modified` = sequential, not parallel**. If two plans share `depends_on` (same wave) and both list the same file in `files_modified`, the planner should have marked the later one `sequential: true`. Catch the cases where it didn't.
 
@@ -814,7 +833,7 @@ The CLI helper returns a JSON report:
 
 **If `conflicts` is empty:** Display `Wave parallelism: ✓ no file-overlap conflicts.` and proceed.
 
-This closes the gap from #442 — the rule was stated in `rcode-planner.md` but not enforced. Now it's enforced automatically.
+This closes the wave-overlap gap — the rule was stated in `rcode-planner.md` but not enforced. Now it's enforced automatically.
 
 ## 13. Requirements Coverage Gate
 
@@ -948,7 +967,7 @@ Route to `<offer_next>` (existing behavior).
 </process>
 
 <banner_emission_gate>
-Issue #655 — the success banner is gated on real verification, not vibes.
+The success banner is gated on real verification, not vibes.
 Before emitting `PLANNED ✓`, confirm one of these is true:
 
 1. A passing CHECK.md exists at `${PHASE_DIR}/*-CHECK.md` from rcode-sprint-checker

package/rcode/workflows/review.md

@@ -82,6 +82,8 @@ Error: rcode-tools init failed. Verify .rcode/ is installed and state.json is va
 
 Read from init: `phase_dir`, `phase_number`, `padded_phase`.
 
+If `phase_dir` is null or empty, STOP and tell the user: "Phase directory not found on disk. Create the phase directory under `.planning/phases/` first (e.g. `mkdir -p .planning/phases/1-name`), then re-run."
+
 Then read:
 1. `.planning/PROJECT.md` (first 80 lines — project context)
 2. Phase section from `.planning/ROADMAP.md`

package/rcode/workflows/scaffold-project.md

@@ -1,7 +1,11 @@
 # Workflow: rcode-scaffold-project
 
 <purpose>
-Scaffold a new project from the official rcode template repo. Delegates to the rcode-scaffold-project skill.
+Scaffold a new project from the official rcode template repo, or initialize rcode
+in an existing project (brownfield mode). Delegates to the rcode-scaffold-project skill.
+
+Use `--here` (or say "scaffold here") to add rcode to an existing directory without
+cloning the template. Existing files are never modified in brownfield mode.
 </purpose>
 
 ## Execution

package/rcode/workflows/session-report.md

@@ -79,7 +79,7 @@ Extract counts:
 
 ### Step 5a — Prefer measured totals from cost.jsonl
 
-If the `cost-track` hook (#745) is enabled, it appends one usage record per
+If the `cost-track` hook is enabled, it appends one usage record per
 response to `.rcode/telemetry/cost.jsonl`. Check for it first:
 
 ```bash

package/rcode/workflows/ship.md

@@ -34,6 +34,45 @@ the plan → execute → verify → **ship** loop.
 ```
 </purpose>
 
+<prerequisites>
+
+**Required before running `/rcode-ship`:**
+
+1. **Git remote configured** — `git remote -v` must list at least one remote (typically `origin`). Without a remote, the push and PR steps will fail.
+2. **`gh` CLI authenticated** — `gh auth status` must succeed. Without this, PR creation will fail.
+3. **Clean working tree** — no uncommitted changes (`git status --short` returns nothing).
+4. **On a feature branch** — not on `main` or `develop` directly.
+5. **Verification passed** — `/rcode-verify-phase <phase>` must have run and produced a VERIFICATION.md with `status: passed`.
+
+</prerequisites>
+
+<warning>
+
+**If your workspace has no git remote or `gh` is not authenticated, the push and PR steps will fail.**
+
+Check before running:
+```bash
+git remote -v          # must list at least one remote
+gh auth status         # must exit 0
+```
+
+**Manual fallbacks if these are missing:**
+
+- **No remote:** Add one with `git remote add origin <repo-url>`, then re-run `/rcode-ship`. Or push manually:
+  ```bash
+  git push origin <branch>
+  ```
+  Then open a PR via the GitHub web UI at `https://github.com/<owner>/<repo>/compare/<branch>`.
+
+- **`gh` not authenticated:** Run `gh auth login` to authenticate, then re-run `/rcode-ship`. Or create the PR directly at:
+  ```
+  https://github.com/<owner>/<repo>/compare/<branch>
+  ```
+
+- **Git worktree context:** If `.git` is a file (not a directory), you are in a worktree. Remotes are shared with the main repo — run `git remote -v` from the main repo root to verify. If the main repo has `origin`, the worktree inherits it automatically.
+
+</warning>
+
 <required_reading>
 Read all files referenced by the invoking prompt's execution_context before starting.
 </required_reading>

package/rcode/workflows/sprint-planning.md

@@ -73,6 +73,33 @@ If `$ARGUMENTS` contains `--help` or `-h`:
 
 STOP — do not proceed.
 
+## Preflight — Project-status check
+
+```bash
+PROJECT_STATUS=$(node .rcode/bin/rcode-tools.cjs project-status 2>/dev/null || echo uninitialized)
+```
+
+If `PROJECT_STATUS` is `uninstalled`, `uninitialized`, or `stub`:
+
+```
+Project not initialized. Run /rcode-init first (or /rcode-new-project for a greenfield project), then return here.
+```
+
+Stop. Do not proceed until `project-status` returns `real`.
+
+## Preflight — Dependency check
+
+If a `package.json` exists in the project root but `node_modules/` is absent or empty, emit a WARNING before planning begins:
+
+```
+⚠ WARNING: package.json found but node_modules/ is missing or empty.
+  Run: pnpm install   (or npm install if pnpm is not available)
+  Sprint planning can continue, but the resulting sprint tasks will fail at execution time
+  unless dependencies are installed first.
+```
+
+Do NOT auto-run the install. Emit the message and let the user decide.
+
 ## Step 1 — Load context
 
 ```bash

package/rcode/workflows/status.md

@@ -1,7 +1,7 @@
 # Workflow: rcode-status
 
 <purpose>
-Render a human-readable project status dashboard. All data comes from a single `rcode-tools progress init` call — this workflow does NOT parse ROADMAP.md, walk SUMMARY.md files, or grep state.json itself. Rendering only. See `rcode-tools.cjs` `cmdProgress` for the source-of-truth logic (issue #159 M2.5).
+Render a human-readable project status dashboard. All data comes from a single `rcode-tools progress init` call — this workflow does NOT parse ROADMAP.md, walk SUMMARY.md files, or grep state.json itself. Rendering only. See `rcode-tools.cjs` `cmdProgress` for the source-of-truth logic.
 
 **SSOT:** `.rcode/state.json`. `/rcode-status` and `/rcode-progress` both call the same CLI so they cannot disagree. If the CLI reports a drift insight, surface it — do not silently compensate.
 </purpose>
@@ -53,7 +53,7 @@ Then stop.
 If `SNAPSHOT.weighted_progress > 0` but `SNAPSHOT.completed_count === 0`, display
 the weighted bar as the primary progress indicator to avoid a misleading `0/N (0%)`.
 
-### Milestone health (issue #718)
+### Milestone health
 
 After the main dashboard, call `rcode-tools milestone-health` and surface
 a gauge when the milestone is full:
@@ -108,7 +108,7 @@ Phases:
 
 If a phase number starts with `999.`, render with a `🅿` marker and the label `(parking lot)`.
 
-## Step 4 — Insights (NEW — issue #159)
+## Step 4 — Insights
 
 If `SNAPSHOT.insights[]` is non-empty, print above the Next Up section:
 

package/server/dashboard.js

@@ -31,7 +31,7 @@ const { spawn } = require('child_process');
 const CLIENT_DIR = path.join(__dirname, 'lib', 'html', 'client');
 
 const { scanState } = require('./lib/scanner');
-const { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory } = require('./lib/api');
+const { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory, handleApiAgents } = require('./lib/api');
 const { renderHtml } = require('./lib/html/shell');
 
 // ---------- Configuration ----------
@@ -60,7 +60,20 @@ function loadOrchToken() {
 const ORCH_TOKEN = loadOrchToken();
 
 // ---------- HTTP Server ----------
+// Every request runs through a try/catch so an unanticipated throw inside a
+// handler (e.g. a pathological .planning tree in the scanner) returns a 500
+// instead of crashing the whole server process.
 const server = http.createServer((req, res) => {
+  try {
+    handleRequest(req, res);
+  } catch (err) {
+    console.error('[dashboard] request handler failed:', err && err.stack || err);
+    if (!res.headersSent) res.writeHead(500, { 'Content-Type': 'text/plain' });
+    res.end('Internal server error');
+  }
+});
+
+function handleRequest(req, res) {
   const url = req.url || '/';
 
   if (url === '/health') {
@@ -79,6 +92,11 @@ const server = http.createServer((req, res) => {
     return;
   }
 
+  if (url === '/api/agents') {
+    handleApiAgents(req, res, PROJECT_ROOT);
+    return;
+  }
+
   if (url.startsWith('/api/file')) {
     handleApiFile(req, res, PROJECT_ROOT);
     return;
@@ -104,10 +122,12 @@ const server = http.createServer((req, res) => {
 
   if (url.startsWith('/js/')) {
     const name = url.slice(4).split('?')[0];
-    // Allow exactly one optional subdirectory (e.g. components/App.js, views/Foo.js)
-    // while still rejecting traversal attempts. The regex blocks `..`, encoded
-    // separators, and anything other than word chars, dots, hyphens, and one `/`.
-    if (!/^(?:[\w.-]+\/)?[\w.-]+\.js$/.test(name)) { res.writeHead(404); res.end('Not found'); return; }
+    // Allow nested subdirectories (e.g. components/App.js, views/Foo.js,
+    // components/dashboard/ProgressDonut.js) while still rejecting traversal.
+    // The regex limits each segment to word chars, dots, and hyphens; the
+    // resolved-path check below is the real traversal guard (a `..` segment
+    // would pass this pattern but fail the CLIENT_DIR containment check).
+    if (!/^(?:[\w.-]+\/)*[\w.-]+\.js$/.test(name)) { res.writeHead(404); res.end('Not found'); return; }
     // Defense-in-depth: resolved path must stay inside CLIENT_DIR even after
     // any OS-level resolution (handles encoded traversal the regex might miss).
     const resolved = path.resolve(CLIENT_DIR, name);
@@ -135,7 +155,7 @@ const server = http.createServer((req, res) => {
 
   res.writeHead(404);
   res.end('Not found');
-});
+}
 
 server.listen(PORT, '127.0.0.1', () => {
   console.log(`\n🕌 Majlis (مجلس) — rcode Dashboard`);
@@ -144,7 +164,6 @@ server.listen(PORT, '127.0.0.1', () => {
   console.log(`   URL:        http://localhost:${PORT}`);
   console.log(`   Scanning:   ${RCODE_DIR}`);
   console.log(`   Refresh:    30s soft poll`);
-  console.log(`   Keys:       R=refresh  1-9=views  F=filter`);
   console.log(`   Stop:       kill $(ss -ltnp 'sport = :${PORT}' | awk 'NR>1{match($6,/pid=([0-9]+)/,m); print m[1]}')`);
   console.log(`━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n`);
 });

package/server/lib/api.js

@@ -8,7 +8,8 @@ const { scanState, scanMemoryBank } = require('./scanner');
 function handleApiState(req, res, rcodeDir) {
   const state = scanState(rcodeDir);
   res.writeHead(200, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(state, null, 2));
+  // Compact JSON — pretty-printing roughly doubled the polled payload.
+  res.end(JSON.stringify(state));
 }
 
 function handleApiFiles(req, res, projectRoot) {
@@ -192,13 +193,70 @@ function handleApiHierarchy(req, res, rcodeDir) {
     })),
   };
   res.writeHead(200, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(hierarchy, null, 2));
+  res.end(JSON.stringify(hierarchy));
 }
 
 function handleApiMemory(req, res, rcodeDir) {
   const memory = scanMemoryBank(rcodeDir);
   res.writeHead(200, { 'Content-Type': 'application/json' });
-  res.end(JSON.stringify(memory, null, 2));
+  res.end(JSON.stringify(memory));
 }
 
-module.exports = { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory };
+// Parse the keys we surface on agent cards out of an agent definition's
+// YAML frontmatter. Deliberately not a YAML parser: top-level `key: value`
+// scalar lines are read directly; for `description` (usually a `|` block
+// scalar) the first two indented lines are captured as a card-sized summary.
+function parseAgentFrontmatter(raw) {
+  const meta = { name: null, model: null, tools: [], color: null, description: null };
+  if (!raw.startsWith('---')) return meta;
+  const end = raw.indexOf('\n---', 3);
+  if (end === -1) return meta;
+  let inDescription = false;
+  const descLines = [];
+  for (const line of raw.slice(3, end).split('\n')) {
+    const m = line.match(/^([A-Za-z][\w-]*):\s*(.*)$/);
+    if (m) {
+      inDescription = false;
+      const key = m[1].toLowerCase();
+      const value = m[2].trim();
+      if (key === 'description') {
+        if (value && value !== '|' && value !== '>') descLines.push(value);
+        else inDescription = true;
+        continue;
+      }
+      if (!value || value === '|' || value === '>') continue;
+      if (key === 'name')  meta.name  = value;
+      if (key === 'model') meta.model = value;
+      if (key === 'color') meta.color = value;
+      if (key === 'tools') meta.tools = value.split(',').map(t => t.trim()).filter(Boolean);
+    } else if (inDescription && descLines.length < 2 && /^\s+\S/.test(line)) {
+      descLines.push(line.trim());
+    }
+  }
+  meta.description = descLines.join(' ') || null;
+  return meta;
+}
+
+// Read-only roster metadata for the Agents view. Scans the fixed
+// rcode/agents/ directory (no user-supplied paths — nothing to contain) and
+// returns one small frontmatter summary per agent .md file. Full prompt
+// bodies are NOT included; the client fetches those lazily per agent via the
+// existing /api/file handler when a card is opened.
+function handleApiAgents(req, res, projectRoot) {
+  const agentsDir = path.join(projectRoot, 'rcode', 'agents');
+  let entries = [];
+  try { entries = fs.readdirSync(agentsDir, { withFileTypes: true }); }
+  catch { /* no agents dir — return an empty roster */ }
+  const agents = [];
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith('.md')) continue;
+    let raw;
+    try { raw = fs.readFileSync(path.join(agentsDir, e.name), 'utf8'); }
+    catch { continue; }
+    agents.push({ file: e.name, ...parseAgentFrontmatter(raw) });
+  }
+  res.writeHead(200, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(agents));
+}
+
+module.exports = { handleApiState, handleApiFiles, handleApiFile, handleApiHierarchy, handleApiMemory, handleApiAgents };

package/server/lib/html/client/agents-data.js

@@ -3,25 +3,29 @@
  *
  * Previously lived in shell.js:17-36 as a server-rendered array.
  * Now exported as a pure ESM constant so AgentsView can render it.
+ *
+ * `file` is the agent's definition under rcode/agents/ — fetched lazily by
+ * AgentsView when a card is opened. null = no prompt file on disk (system
+ * entries like Raees/Majlis/Diwan are skills, not agent definitions).
  */
 
 export const AGENTS = [
-  { name: 'Sadiq Damani',         arabic: 'صادق',         role: 'Director of Strategy',              real: true, type: 'leadership' },
-  { name: 'Waleed Al Harthi',     arabic: 'وليد',         role: 'CTO',                               real: true, type: 'leadership' },
-  { name: 'Ahmed Al Hassani',     arabic: 'أحمد الحسني',  role: 'Technology & Development Director', real: true, type: 'leadership' },
-  { name: 'Nasser',               arabic: 'ناصر',         role: 'Engineering Manager',               real: true, type: 'leadership' },
-  { name: 'Hussain',              arabic: 'حسين',         role: 'PM + Scrum Master',                                type: 'product' },
-  { name: 'Layla',                arabic: 'ليلى',         role: 'Lead UX Designer',                                 type: 'design' },
-  { name: 'Zahra',                arabic: 'زهرة',         role: 'Branding & Creative Director',                    type: 'design' },
-  { name: 'Omar',                 arabic: 'عمر',          role: 'Full-Stack Engineer',                              type: 'engineering' },
-  { name: 'Haitham Al Khamiyasi', arabic: 'هيثم',        role: 'Senior Frontend',                   real: true, type: 'engineering' },
-  { name: 'Yousef',               arabic: 'يوسف',         role: 'Senior Backend',                                   type: 'engineering' },
-  { name: 'Zayd',                 arabic: 'زيد',          role: 'ML Engineer',                                      type: 'engineering' },
-  { name: 'Fatima',               arabic: 'فاطمة',        role: 'QA Lead',                                          type: 'quality' },
-  { name: 'Khalid',               arabic: 'خالد',         role: 'DevOps',                                           type: 'engineering' },
-  { name: 'Noor',                 arabic: 'نور',          role: 'Scribe',                                           type: 'support' },
-  { name: 'Mariam',               arabic: 'مريم',         role: 'Marketing Lead',                                   type: 'product' },
-  { name: 'Raees',                arabic: 'رئيس',         role: 'Orchestration Director',                          type: 'system' },
-  { name: 'Majlis',               arabic: 'مجلس',         role: 'Consulting Council',                               type: 'system' },
-  { name: 'Diwan',                arabic: 'ديوان',        role: 'Dashboard Registry',                               type: 'system' },
+  { name: 'Sadiq Damani',         arabic: 'صادق',         role: 'Director of Strategy',              real: true, type: 'leadership',  file: 'rcode-sadiq.md' },
+  { name: 'Waleed Al Harthi',     arabic: 'وليد',         role: 'CTO',                               real: true, type: 'leadership',  file: 'rcode-waleed.md' },
+  { name: 'Ahmed Al Hassani',     arabic: 'أحمد الحسني',  role: 'Technology & Development Director', real: true, type: 'leadership',  file: 'rcode-ahmed.md' },
+  { name: 'Nasser',               arabic: 'ناصر',         role: 'Engineering Manager',               real: true, type: 'leadership',  file: 'rcode-nasser.md' },
+  { name: 'Hussain',              arabic: 'حسين',         role: 'PM + Scrum Master',                                type: 'product',     file: 'rcode-hussain-pm.md' },
+  { name: 'Layla',                arabic: 'ليلى',         role: 'Lead UX Designer',                                 type: 'design',      file: 'rcode-layla.md' },
+  { name: 'Zahra',                arabic: 'زهرة',         role: 'Branding & Creative Director',                    type: 'design',      file: 'rcode-zahra.md' },
+  { name: 'Omar',                 arabic: 'عمر',          role: 'Full-Stack Engineer',                              type: 'engineering', file: 'rcode-omar.md' },
+  { name: 'Haitham Al Khamiyasi', arabic: 'هيثم',        role: 'Senior Frontend',                   real: true, type: 'engineering', file: 'rcode-haitham.md' },
+  { name: 'Yousef',               arabic: 'يوسف',         role: 'Senior Backend',                                   type: 'engineering', file: 'rcode-yousef.md' },
+  { name: 'Zayd',                 arabic: 'زيد',          role: 'ML Engineer',                                      type: 'engineering', file: 'rcode-zayd.md' },
+  { name: 'Fatima',               arabic: 'فاطمة',        role: 'QA Lead',                                          type: 'quality',     file: 'rcode-fatima.md' },
+  { name: 'Khalid',               arabic: 'خالد',         role: 'DevOps',                                           type: 'engineering', file: 'rcode-khalid.md' },
+  { name: 'Noor',                 arabic: 'نور',          role: 'Scribe',                                           type: 'support',     file: 'rcode-noor.md' },
+  { name: 'Mariam',               arabic: 'مريم',         role: 'Marketing Lead',                                   type: 'product',     file: 'rcode-mariam.md' },
+  { name: 'Raees',                arabic: 'رئيس',         role: 'Orchestration Director',                          type: 'system',      file: null },
+  { name: 'Majlis',               arabic: 'مجلس',         role: 'Consulting Council',                               type: 'system',      file: null },
+  { name: 'Diwan',                arabic: 'ديوان',        role: 'Dashboard Registry',                               type: 'system',      file: null },
 ];

package/server/lib/html/client/app.js

@@ -11,5 +11,8 @@ import { App } from './components/App.js';
 
 const root = document.getElementById('app-root');
 if (root) {
+  // Drop the SSR loading shell — Preact diffs against existing children,
+  // so the spinner must be gone before the first render.
+  root.textContent = '';
   render(html`<${App}/>`, root);
 }

package/server/lib/html/client/components/AgentCard.js

@@ -0,0 +1,127 @@
+/**
+ * AgentCard — card, avatar, chips, and detail drawer for the Agents view.
+ *
+ * Extracted from AgentsView so the view module stays focused on grouping,
+ * search, and fetch state. Per-role accent colors are driven by a single
+ * `agent-accent--<type>` class on the card/drawer root: it sets the
+ * --agent-accent custom property that the avatar, role badge, and hover
+ * border all read (see the AGENTS VIEW block at the end of css.js).
+ */
+
+import { html } from '../preact.js';
+import { setState } from '../store.js';
+import { pressable, showToast } from './shared.js';
+import { renderMd } from '../util.js';
+
+const MAX_CARD_TOOL_CHIPS = 4;
+
+/** "Sadiq Damani" -> "SD", "Hussain" -> "H". */
+function initialsOf(name) {
+  return name.split(/\s+/).filter(Boolean).slice(0, 2).map(w => w[0]).join('').toUpperCase();
+}
+
+/** Per-role accent class — types map 1:1 to the CSS accent variants. */
+export function accentClass(agent) {
+  return 'agent-accent--' + (agent.type || 'system');
+}
+
+// ---- Avatar circle with initials ----
+function Avatar({ agent, large }) {
+  return html`<span class=${'agent-avatar' + (large ? ' agent-avatar--lg' : '')} aria-hidden="true">${initialsOf(agent.name)}</span>`;
+}
+
+// ---- Metadata chips (model + tools), shared by card and drawer ----
+export function MetaChips({ meta, maxTools }) {
+  if (!meta) return null;
+  const tools = meta.tools || [];
+  const shown = maxTools ? tools.slice(0, maxTools) : tools;
+  const extra = tools.length - shown.length;
+  if (!meta.model && !shown.length) return null;
+  return html`
+    <div class="agent-chips">
+      ${meta.model ? html`<span class="agent-chip agent-chip--model">${meta.model}</span>` : null}
+      ${shown.map(t => html`<span class="agent-chip" key=${t}>${t}</span>`)}
+      ${extra > 0 ? html`<span class="agent-chip agent-chip--more">+${extra}</span>` : null}
+    </div>
+  `;
+}
+
+// ---- Single agent card ----
+export function AgentCard({ agent, meta, onOpen }) {
+  return html`
+    <div class=${'agent-card ' + accentClass(agent)} ...${pressable(() => onOpen(agent))}>
+      <div class="agent-card-top">
+        <${Avatar} agent=${agent} />
+        <div class="agent-card-id">
+          <div class="agent-card-name">
+            ${agent.name}
+            ${agent.real ? html`<span class="real-badge">real</span>` : null}
+          </div>
+          <span class="role-badge">${agent.role}</span>
+        </div>
+        <span class="agent-card-arabic">${agent.arabic}</span>
+      </div>
+      ${meta && meta.description ? html`<p class="agent-card-desc">${meta.description}</p>` : null}
+      <${MetaChips} meta=${meta} maxTools=${MAX_CARD_TOOL_CHIPS} />
+    </div>
+  `;
+}
+
+// ---- Detail drawer ----
+export function AgentDrawer({ agent, meta, prompt, onClose }) {
+  const filePath = agent.file ? 'rcode/agents/' + agent.file : null;
+
+  function copyPath() {
+    navigator.clipboard.writeText(filePath).then(() => {
+      showToast('Path copied!');
+    }).catch(() => {});
+  }
+
+  function openInFiles() {
+    setState({ requestedFile: filePath });
+    window.location.hash = 'files';
+  }
+
+  let body;
+  if (!agent.file) {
+    body = html`<div class="agent-drawer-empty">No prompt file on disk — this is a system entry without an agent definition.</div>`;
+  } else if (prompt.loading) {
+    body = html`
+      <div class="skeleton"></div>
+      <div class="agent-drawer-skeleton skeleton"></div>
+    `;
+  } else if (prompt.error) {
+    body = html`<div class="agent-drawer-error">${prompt.error}</div>`;
+  } else if (prompt.text) {
+    body = html`<div class="md-render" dangerouslySetInnerHTML=${{ __html: renderMd(prompt.text) }} />`;
+  } else {
+    body = null;
+  }
+
+  return html`
+    <div class="agent-drawer-backdrop" onClick=${onClose}></div>
+    <aside class=${'agent-drawer ' + accentClass(agent)} role="dialog" aria-modal="true" aria-label="${agent.name} — full prompt">
+      <div class="agent-drawer-head">
+        <${Avatar} agent=${agent} large />
+        <div class="agent-drawer-titles">
+          <div class="agent-drawer-name">
+            ${agent.name}
+            <span class="agent-drawer-arabic">${agent.arabic}</span>
+            ${agent.real ? html`<span class="real-badge">real</span>` : null}
+          </div>
+          <span class="role-badge">${agent.role}</span>
+          <${MetaChips} meta=${meta} />
+        </div>
+        <button class="agent-drawer-close" onClick=${onClose} aria-label="Close">×</button>
+      </div>
+      ${filePath ? html`
+        <div class="agent-drawer-meta">
+          <span class="agent-drawer-meta-path">${filePath}</span>
+          <button class="agent-drawer-btn" onClick=${copyPath}>Copy path</button>
+          <button class="agent-drawer-btn agent-drawer-btn--link" onClick=${openInFiles}>View in Files →</button>
+        </div>
+      ` : null}
+      <div class="agent-drawer-body">${body}</div>
+    </aside>
+  `;
+}