@stravica-ai/digital-operator-pa 0.1.47 → 0.1.49

package/dist/engineering-pa-cli/src/pa/cli.mjs

@@ -11,6 +11,10 @@ import { fileURLToPath } from 'node:url';
 import { run as runDesk } from '../../../engineering-pa-core/src/desk/cli.mjs';
 import { PA_PACKAGE_NAME } from '../../../engineering-pa-core/src/config/pa-package-name.mjs';
 import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
+import {
+  computeDistillationHealth,
+  renderHealthLine,
+} from '../../../engineering-pa-core/src/distill/health.mjs';
 import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspect/src/cli.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -180,7 +184,26 @@ async function doStatus(opts = {}) {
   // Workspace-not-running is OK — operators may run pa status before
   // starting the workspace server.
 
-  // 4. Desk overview snapshot.
+  // 4. Distillation health — schedule installed?, last run, staging
+  // count. Load-bearing because the whole self-learning loop dies
+  // silently otherwise (the estate has already been bitten: on the
+  // WSD-laptop cold-install proof of 0.1.41, staged observations piled
+  // up for days without a scheduled sweep to distil them). Rendered on
+  // one line, prefixed `[ok]` or `[warn]` per the health module.
+  out.write('\nDistillation:\n');
+  try {
+    const health = await computeDistillationHealth({ repoRoot });
+    out.write(`  ${renderHealthLine(health)}\n`);
+    // Do NOT flip allOk here — a fresh scaffold with no schedule
+    // installed (the exact moment /onboard is meant to run) would then
+    // exit 2 from pa status, which is the pre-install check for the
+    // scaffold itself. Warnings are visible in the line; exit code is
+    // reserved for structural failures (missing operator/).
+  } catch (e) {
+    out.write(`  distillation health probe failed: ${e?.message || e}\n`);
+  }
+
+  // 5. Desk overview snapshot.
   out.write('\nOverview:\n');
   try {
     const code = await runDesk(['overview']);

package/dist/engineering-pa-core/docs/commands/onboard.md

@@ -28,17 +28,21 @@ Read `.session/onboarding.json` first. Shape:
   "version": 1,
   "startedAt": "<iso>",
   "steps": {
-    "verifyRuntime": "pending" | "done" | "skipped",
-    "verifyVersion": "pending" | "done" | "skipped",
-    "profileIntake": "pending" | "done" | "skipped",
-    "aliasOffer":    "pending" | "done" | "skipped",
-    "workspaceOffer":"pending" | "done" | "skipped",
-    "atlassianOffer":"pending" | "done" | "skipped"
+    "verifyRuntime":     "pending" | "done" | "skipped",
+    "verifyVersion":     "pending" | "done" | "skipped",
+    "profileIntake":     "pending" | "done" | "skipped",
+    "aliasOffer":        "pending" | "done" | "skipped",
+    "workspaceOffer":    "pending" | "done" | "skipped",
+    "librarianSchedule": "pending" | "done",
+    "atlassianOffer":    "pending" | "done" | "skipped"
   },
   "completedAt": null | "<iso>"
 }
 ```
 
+`librarianSchedule` never lands on `skipped`. It is a mandatory step and
+onboarding does not complete until it is `done`.
+
 If the file is missing, the scaffold did not seed it — flag that and stop.
 
 If `completedAt` is set, tell the operator onboarding is already complete and
@@ -114,7 +118,77 @@ shut down cleanly), do NOT stop the walkthrough. Instead:
 On no, note that `pnpm exec pa workspace start` is the verb whenever
 they want it.
 
-### 6. atlassianOffer
+### 6. librarianSchedule (mandatory, no opt-out)
+
+The distillation sweep is what turns staged observations under
+`agents/<paName>/staging/` into knowledge docs under
+`operator/knowledge/`. Without a scheduled sweep the whole self-learning
+loop dies silently: staged notes pile up, no docs get promoted, and
+`pa knowledge search` never sees the new material. The scaffold ships
+the schedule file at `schedules/<paName>-distillation-sweep.json`; this
+step installs it on the OS-native backend and fires one real run to
+prove the wiring.
+
+Do NOT ask the operator whether to do this. State what is happening in
+one short paragraph:
+
+> Installing the librarian distillation sweep so your Digital Operator
+> keeps learning. It runs every four hours in the background, turns your
+> staged observations into knowledge docs, and refreshes the retrieval
+> graph so the new material is searchable straight away. This is the
+> one piece of scheduling every solo instance needs.
+
+Then run:
+
+```
+pnpm exec scheduler install schedules/<paName>-distillation-sweep.json --force-host
+```
+
+Substitute `<paName>` from `operator/config/preferences.json`. The
+`--force-host` is deliberate. macOS hostnames flap between the DHCP
+name and the configured name (Dex 2026-07-16 evidence), and a well-
+formed refusal at first-run onboarding is the worst possible operator
+experience.
+
+Immediately after install, trigger one real sweep through the scheduler
+backend itself (never a shell repro: a shell resolves `node` and PATH
+differently and would hide the launchd/cron spawn behaviour the ledger
+is meant to prove). On macOS/launchd:
+
+```
+launchctl kickstart -k "gui/$(id -u)/com.<paName>.<paName>-distillation-sweep"
+```
+
+On Linux/cron, invoke the exact command line the crontab entry carries,
+from the same working directory, with a minimal PATH the cron job would
+see:
+
+```
+env -i HOME="$HOME" PATH=/usr/local/bin:/usr/bin:/bin \
+  bash -c 'cd <targetDir> && node node_modules/@stravica-ai/digital-operator-pa/bin/distill run'
+```
+
+Wait for the run with a hard timeout of 6 minutes (a real sweep with
+one `claude --print` subprocess is typically 60–120 seconds, but the
+first-ever run on a cold cache can stretch). Poll
+`.cache/distill/logs/runs.jsonl`. A completed run appends one JSON line
+with `"status": "ok"` or `"status": "noop-empty-staging"`. Either
+status is a successful proof: the pipeline ran end to end.
+
+Mark this step `done` only when the ledger shows a completed run. If
+the install fails, or the run times out, or the ledger records a
+`fail-*` status, this step is NOT `done`, onboarding does NOT complete,
+and the operator gets:
+
+1. The exact error message (from the scheduler CLI's stderr, or the
+   ledger's `reason` field, or a timeout notice).
+2. The one command to retry, verbatim:
+   `pnpm exec scheduler install schedules/<paName>-distillation-sweep.json --force-host`
+
+Then stop. Do not silently skip to `atlassianOffer`. The whole
+onboarding is blocked on this step.
+
+### 7. atlassianOffer
 
 Ask if they use Jira or Confluence. On no, mark skipped. On yes, walk them
 through:

package/dist/engineering-pa-core/src/distill/cli.mjs

@@ -10,12 +10,26 @@ import { parseArgs } from 'node:util';
 import { defaultRepoRoot } from './prereqs.mjs';
 import { runDistill } from './run.mjs';
 import { defaultRunner } from './runner.mjs';
+import {
+  buildHealthHookEnvelope,
+  computeDistillationHealth,
+  renderHealthBlock,
+  renderHealthLine,
+} from './health.mjs';
 
 const USAGE = `distill — librarian distillation sweep runner
 
 Usage:
   distill run                Run a real distillation sweep
   distill run --dry-run      Print what would run, don't invoke claude
+  distill health             Print one-line schedule + last-run + staging summary
+  distill health --json      Print the full health object as JSON
+  distill health --block     Print the multi-line markdown block
+  distill health --hook-envelope
+                             Print a Claude Code SessionStart hook envelope
+                             (JSON, {hookSpecificOutput: {...}}) — the shape
+                             scaffolded into .claude/settings.json so the
+                             summary is injected at session boot.
   distill -h, --help         Show this help
 
 Exit codes:
@@ -106,6 +120,57 @@ async function route(argv) {
     process.exit(code ?? 0);
   }
 
+  if (verb === 'health') {
+    const { values } = parseArgs({
+      args: rest,
+      options: {
+        json: { type: 'boolean', default: false },
+        block: { type: 'boolean', default: false },
+        'hook-envelope': { type: 'boolean', default: false },
+        help: { type: 'boolean', short: 'h', default: false },
+      },
+      strict: true,
+    });
+    if (values.help) {
+      process.stdout.write(USAGE);
+      process.exit(0);
+    }
+    const repoRoot = await defaultRepoRoot();
+    if (!repoRoot) {
+      // Preserve exit-code hygiene: no repo root == prerequisite missing.
+      // Still emit a valid hook envelope on --hook-envelope so a badly
+      // configured Claude session never sees invalid JSON on stdout.
+      const fallback = {
+        repoRoot: null, paName: null, cadenceHours: 4,
+        schedule: { present: false, path: null },
+        lastRun: null, stagingCount: { error: 'no repo root resolved' },
+        warnings: ['no operator repo root resolved from cwd (no `.git` ancestor and no DAVE_REPO_ROOT / PA_REPO_ROOT set)'],
+        ok: false,
+        generatedAt: new Date().toISOString(),
+      };
+      if (values['hook-envelope']) {
+        process.stdout.write(JSON.stringify(buildHealthHookEnvelope(fallback)) + '\n');
+        process.exit(0);
+      }
+      if (values.json) process.stdout.write(JSON.stringify(fallback, null, 2) + '\n');
+      else if (values.block) process.stdout.write(renderHealthBlock(fallback));
+      else process.stdout.write(renderHealthLine(fallback) + '\n');
+      process.exit(2);
+    }
+    const health = await computeDistillationHealth({ repoRoot });
+    if (values['hook-envelope']) {
+      process.stdout.write(JSON.stringify(buildHealthHookEnvelope(health)) + '\n');
+      // Hook path: always exit 0. Failing here would surface as a Claude
+      // Code hook error at every session boot, which is worse than a
+      // rendered warning block.
+      process.exit(0);
+    }
+    if (values.json) process.stdout.write(JSON.stringify(health, null, 2) + '\n');
+    else if (values.block) process.stdout.write(renderHealthBlock(health));
+    else process.stdout.write(renderHealthLine(health) + '\n');
+    process.exit(0);
+  }
+
   process.stderr.write(`[distill] unknown command: ${verb}\n`);
   process.stderr.write(USAGE);
   process.exit(1);

package/dist/engineering-pa-core/src/distill/health.mjs

@@ -0,0 +1,322 @@
+// distill — librarian schedule + last-run health surface.
+//
+// Reads:
+//   1. the operator's `schedules/<paName>-distillation-sweep.json` (does the
+//      schedule file exist at all — a scaffolded solo instance ships one but
+//      an older upgrade may not).
+//   2. the distill ledger at `<repoRoot>/.cache/distill/logs/runs.jsonl`
+//      (last run: ts, status, durationSec, stagingCount).
+//   3. the current staged-observation count via `countStagedObservations`
+//      (how much material is queued for the next sweep).
+//
+// Consumers:
+//   * `pa status` prints a distillation line built from `renderHealthLine`.
+//   * A scaffolded `SessionStart` hook injects `buildHealthHookEnvelope`'s
+//     output at the top of every session, so the operator sees the same
+//     summary without asking.
+//   * `distill health --json` prints the raw computed object so scripts
+//     can key on it.
+//
+// This module is READ-ONLY. It never invokes claude, never triggers a
+// sweep, never touches the schedule backend. Cheap to call from a hook.
+
+import { readFile, stat } from 'node:fs/promises';
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { readPreferencesSync } from '../preferences.mjs';
+import { countStagedObservations } from './staging.mjs';
+
+/**
+ * Default sweep cadence in hours. The scaffolded schedule fires every
+ * four hours; the health surface warns when the last run is older than
+ * `staleMultiplier * cadenceHours` (default 2 * 4 = 8 hours), so a
+ * one-cycle miss is quiet but a two-cycle miss surfaces.
+ */
+export const DEFAULT_CADENCE_HOURS = 4;
+
+/**
+ * How many multiples of the cadence a last-run can lag before the health
+ * surface labels it stale. Two is deliberate: a single missed tick is
+ * common (host asleep, laptop closed at the wrong minute) and would
+ * generate false alarms.
+ */
+export const DEFAULT_STALE_MULTIPLIER = 2;
+
+/**
+ * Read the last non-empty line of the distill ledger. Returns null when
+ * the ledger does not exist or has never seen a real run. All other
+ * read failures surface as a `{ error }` object so the caller can render
+ * something honest instead of crashing.
+ *
+ * The ledger is append-only JSONL and typically small (dozens of lines
+ * over months). Reading the whole file is cheaper than streaming the
+ * tail in every context we call this from.
+ */
+export async function readLastLedgerEntry(repoRoot) {
+  const path = join(repoRoot, '.cache', 'distill', 'logs', 'runs.jsonl');
+  let raw;
+  try {
+    raw = await readFile(path, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    return { error: `ledger read failed: ${err.message || err}` };
+  }
+  const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+  if (lines.length === 0) return null;
+  const last = lines[lines.length - 1];
+  try {
+    return JSON.parse(last);
+  } catch (err) {
+    return { error: `ledger last line unparseable: ${err.message || err}` };
+  }
+}
+
+/**
+ * Resolve the schedule file name a fresh scaffold writes. Kept in one
+ * place so the scaffold, the health surface, and the `/onboard`
+ * walkthrough all agree.
+ */
+export function distillationScheduleId(paName) {
+  return `${paName}-distillation-sweep`;
+}
+
+export function distillationScheduleFilename(paName) {
+  return `${distillationScheduleId(paName)}.json`;
+}
+
+/**
+ * Locate the scaffolded distillation schedule file for a given repo.
+ * Returns `{ path, present }`, and when present also `{ enabled, backend,
+ * schedule, host }` parsed from the JSON (best-effort — a corrupt file
+ * lands as `{ present: true, parseError: '...' }`).
+ */
+export function readScheduleFile(repoRoot, paName) {
+  const path = join(repoRoot, 'schedules', distillationScheduleFilename(paName));
+  if (!existsSync(path)) return { path, present: false };
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    return {
+      path,
+      present: true,
+      enabled: parsed.enabled !== false,
+      backend: parsed.backend ?? null,
+      schedule: parsed.schedule ?? null,
+      host: parsed.host ?? null,
+      id: parsed.id ?? null,
+    };
+  } catch (err) {
+    return { path, present: true, parseError: err.message || String(err) };
+  }
+}
+
+/**
+ * Resolve the PA name from `operator/config/preferences.json`. Falls
+ * back to null (the caller reports missing-preferences instead of
+ * guessing a name).
+ */
+export function resolvePaName(repoRoot) {
+  try {
+    const prefs = readPreferencesSync(repoRoot);
+    if (prefs && typeof prefs.paName === 'string' && prefs.paName.length > 0) {
+      return prefs.paName;
+    }
+  } catch { /* fall through */ }
+  return null;
+}
+
+/**
+ * Compose the full distillation-health object for a given operator repo.
+ *
+ * Shape:
+ * {
+ *   repoRoot, paName, cadenceHours,
+ *   schedule: { path, present, enabled?, backend?, schedule?, host?, id? } | { present: false } | { parseError },
+ *   lastRun: null | { ts, status, exitCode, durationSec, stagingCount, log, reason?, ageSeconds? } | { error },
+ *   stagingCount: number | { error },
+ *   warnings: string[],
+ *   ok: boolean,
+ *   generatedAt: string (ISO)
+ * }
+ *
+ * `ok` is true when the schedule file is present and enabled, staging
+ * is readable, and (if there is any last run at all) that run's status
+ * is not a `fail-*` and its age is inside `staleMultiplier * cadenceHours`.
+ * A brand-new instance with no runs yet is `ok: true` with a warning; the
+ * warning describes the exact next action ("run `distill run` to seed
+ * the ledger").
+ */
+export async function computeDistillationHealth({
+  repoRoot,
+  paName = null,
+  cadenceHours = DEFAULT_CADENCE_HOURS,
+  staleMultiplier = DEFAULT_STALE_MULTIPLIER,
+  now = new Date(),
+} = {}) {
+  if (!repoRoot) throw new Error('computeDistillationHealth: repoRoot is required');
+  const resolvedName = paName ?? resolvePaName(repoRoot);
+  const warnings = [];
+  let ok = true;
+
+  // Schedule file — presence is a hard requirement (without it, no
+  // scheduled sweep runs, ever). Missing is a warning, not a throw:
+  // the surface still needs to render for pa status.
+  let schedule;
+  if (!resolvedName) {
+    schedule = { present: false, path: null };
+    warnings.push('no paName in operator/config/preferences.json — cannot resolve the distillation schedule file');
+    ok = false;
+  } else {
+    schedule = readScheduleFile(repoRoot, resolvedName);
+    if (!schedule.present) {
+      warnings.push(
+        `no distillation schedule at schedules/${distillationScheduleFilename(resolvedName)} — run /onboard to install one`,
+      );
+      ok = false;
+    } else if (schedule.parseError) {
+      warnings.push(`distillation schedule file is corrupt: ${schedule.parseError}`);
+      ok = false;
+    } else if (schedule.enabled === false) {
+      warnings.push('distillation schedule is disabled (schedule.enabled === false)');
+      ok = false;
+    }
+  }
+
+  // Last-run ledger — null (never run), an error, or the last record.
+  const lastRun = await readLastLedgerEntry(repoRoot);
+  let annotatedLastRun = lastRun;
+  const cadenceSeconds = cadenceHours * 3600;
+  if (lastRun && !lastRun.error && lastRun.ts) {
+    const ageSeconds = Math.max(0, Math.round((now.getTime() - new Date(lastRun.ts).getTime()) / 1000));
+    annotatedLastRun = { ...lastRun, ageSeconds };
+    if (typeof lastRun.status === 'string' && lastRun.status.startsWith('fail-')) {
+      warnings.push(`last distillation run failed: ${lastRun.status}${lastRun.reason ? ` (${lastRun.reason})` : ''}`);
+      ok = false;
+    }
+    if (ageSeconds > staleMultiplier * cadenceSeconds) {
+      warnings.push(
+        `last distillation run was ${formatDuration(ageSeconds)} ago (cadence ${cadenceHours}h) — the scheduled sweep may not be firing`,
+      );
+      ok = false;
+    }
+  } else if (!lastRun) {
+    warnings.push('no distillation runs recorded yet — the ledger will populate on the first sweep');
+  } else if (lastRun && lastRun.error) {
+    warnings.push(lastRun.error);
+    ok = false;
+  }
+
+  // Staging count — how much material is queued.
+  let stagingCount;
+  try {
+    stagingCount = await countStagedObservations(repoRoot);
+  } catch (err) {
+    stagingCount = { error: `staging read failed: ${err.message || err}` };
+    warnings.push(stagingCount.error);
+  }
+
+  return {
+    repoRoot,
+    paName: resolvedName,
+    cadenceHours,
+    schedule,
+    lastRun: annotatedLastRun,
+    stagingCount,
+    warnings,
+    ok,
+    generatedAt: now.toISOString(),
+  };
+}
+
+/**
+ * Format a duration in seconds as a compact human-readable label. Chosen
+ * so the surface stays scan-friendly at both very-recent (`5s ago`) and
+ * very-stale (`3d 4h ago`) extremes without a dependency.
+ */
+export function formatDuration(seconds) {
+  if (typeof seconds !== 'number' || !Number.isFinite(seconds) || seconds < 0) return 'unknown';
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rMin = minutes % 60;
+  if (hours < 24) return rMin ? `${hours}h ${rMin}m` : `${hours}h`;
+  const days = Math.floor(hours / 24);
+  const rHr = hours % 24;
+  return rHr ? `${days}d ${rHr}h` : `${days}d`;
+}
+
+/**
+ * Render a single-line summary suitable for the `pa status` output or a
+ * one-line boot briefing. Always fits on a terminal line, and never
+ * omits the warning class when one is present.
+ */
+export function renderHealthLine(health) {
+  const parts = [];
+  if (health.schedule?.present && health.schedule.enabled !== false) {
+    parts.push(`schedule: installed (${health.schedule.backend || 'backend?'}, ${health.schedule.schedule || '?'})`);
+  } else if (health.schedule?.present === false) {
+    parts.push('schedule: MISSING');
+  } else if (health.schedule?.enabled === false) {
+    parts.push('schedule: DISABLED');
+  } else if (health.schedule?.parseError) {
+    parts.push('schedule: CORRUPT');
+  } else {
+    parts.push('schedule: unknown');
+  }
+  if (health.lastRun && !health.lastRun.error && health.lastRun.ts) {
+    const age = typeof health.lastRun.ageSeconds === 'number'
+      ? formatDuration(health.lastRun.ageSeconds) + ' ago'
+      : health.lastRun.ts;
+    parts.push(`last run: ${health.lastRun.status || '?'} (${age})`);
+  } else if (health.lastRun && health.lastRun.error) {
+    parts.push('last run: ledger read failed');
+  } else {
+    parts.push('last run: never');
+  }
+  if (typeof health.stagingCount === 'number') {
+    parts.push(`staging: ${health.stagingCount}`);
+  } else if (health.stagingCount && health.stagingCount.error) {
+    parts.push('staging: unreadable');
+  }
+  const status = health.warnings.length === 0 ? 'ok' : 'warn';
+  return `[${status}] ${parts.join(' | ')}`;
+}
+
+/**
+ * Render a multi-line markdown block suitable for a SessionStart hook's
+ * `additionalContext` — the same shape autonomy-injection uses. Kept
+ * compact: a heading, the one-line summary, the warnings list, and the
+ * remediation command when the surface is not ok.
+ */
+export function renderHealthBlock(health) {
+  const lines = [];
+  lines.push('# distillationHealth (live)');
+  lines.push('');
+  lines.push(renderHealthLine(health));
+  if (health.warnings.length > 0) {
+    lines.push('');
+    lines.push('Warnings:');
+    for (const w of health.warnings) lines.push(`- ${w}`);
+  }
+  if (!health.ok) {
+    lines.push('');
+    lines.push('Remediation: run `/onboard` (idempotent), then `pnpm exec distill run` to seed the ledger.');
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+/**
+ * Build the full Claude Code SessionStart hook envelope. The hook prints
+ * this JSON to stdout; Claude Code injects `additionalContext` into the
+ * session.
+ */
+export function buildHealthHookEnvelope(health) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext: renderHealthBlock(health),
+    },
+  };
+}

package/dist/engineering-pa-scaffold/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/engineering-pa-scaffold",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "pa-init scaffolder + onboarding flows (solo, lead, member).",
   "type": "module",
   "main": "./index.mjs",
@@ -11,7 +11,8 @@
     "pa-init": "bin/pa-init"
   },
   "dependencies": {
-    "@stravica-ai/engineering-pa-core": "workspace:*"
+    "@stravica-ai/engineering-pa-core": "workspace:*",
+    "@stravica-ai/engineering-pa-workspace": "workspace:*"
   },
   "private": true,
   "license": "MIT",

package/dist/engineering-pa-scaffold/src/commands/init-workspace-extension.mjs

@@ -21,6 +21,18 @@ import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
 
+// Direct file import (not the bare package specifier) so the build.mjs
+// import-rewriter produces a full-filename relative path — Node ESM won't
+// resolve a directory-only path without a package.json main entry, and
+// the bundled dist tree does not carry one for internal packages.
+import {
+  BANNER_JS_TAG,
+  GLOBAL_BANNER_HTML,
+  THEME_CSS_LINK,
+  THEME_JS_TAG,
+  prepaintScriptTag,
+} from '../../../engineering-pa-workspace/index.mjs';
+
 /** Kebab-case validator: 2-40 chars, lowercase letters + digits + hyphen, starts with a letter. */
 const NAME_RE = /^[a-z][a-z0-9-]{1,39}$/;
 
@@ -163,21 +175,41 @@ export async function mergeNavEntry({ navPath, name, label, section }) {
 
 /**
  * The static-page skeleton written for `<name>.html`. Kept minimal on
- * purpose: the operator's PA fills in the real content on the next
- * dispatch, and a heavier template would just be deleted.
+ * content but complete on chrome: an extension page carries the same
+ * head + top-of-body contract every core page ships, so a freshly
+ * scaffolded page renders in the operator's chosen theme and shows the
+ * global status banner from the first load.
+ *
+ * The head tags come from
+ * `@stravica-ai/engineering-pa-workspace/src/workspace-page-contract.mjs`
+ * so a scaffolded page and a core page can never drift on the theme
+ * storage key or the tag order. Previously this used a single
+ * `<link rel="stylesheet" href="/core/tools/workspace/app/shell.css" />`
+ * — that path never shipped, so every scaffolded page rendered
+ * unstyled and outside the theme system.
+ *
+ * Core pages still hand-copy the contract for now (their inline `<style>`
+ * blocks sit between the theme tags and `banner.js`, so a full migration
+ * is more than a mechanical substitution and is tracked as a follow-up).
+ * A parity test pins the tokens so a rename in either place fails fast.
  */
 export function buildHtmlSkeleton({ name, label }) {
+  const title = escapeHtml(label);
   return `<!doctype html>
 <html lang="en">
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${escapeHtml(label)}</title>
-  <link rel="stylesheet" href="/core/tools/workspace/app/shell.css" />
+  <title>${title}</title>
+  ${prepaintScriptTag()}
+  ${THEME_CSS_LINK}
+  ${THEME_JS_TAG}
+  ${BANNER_JS_TAG}
 </head>
 <body>
+  ${GLOBAL_BANNER_HTML}
   <main class="page">
-    <h1>${escapeHtml(label)}</h1>
+    <h1>${title}</h1>
     <!-- workspace-extension:${name} -->
     <p>Replace this with the real page. Data lives under <code>/__api/${name}/...</code> if you scaffolded the api stub.</p>
   </main>

package/dist/engineering-pa-scaffold/src/commands/init.mjs

@@ -112,6 +112,12 @@ export async function runInit(options) {
  */
 function writeNextStepMessage(config) {
   const { paName, targetDir } = config;
+  // Prose renders the PA name Title-Cased so a sentence starting with it
+  // reads naturally (e.g. "Arry walks you through..." rather than
+  // "arry walks you through..."). The shell-alias lines still use the
+  // lowercase kebab-case identifier because that's what gets typed at a
+  // shell prompt.
+  const paTitle = paName.length ? paName[0].toUpperCase() + paName.slice(1) : paName;
   const lines = [
     '',
     'Next step, start your PA:',
@@ -119,7 +125,7 @@ function writeNextStepMessage(config) {
     `  cd ${targetDir}`,
     '  pnpm exec pa session',
     '',
-    `Inside the session, type \`/onboard\`. ${paName} walks you through the`,
+    `Inside the session, type \`/onboard\`. ${paTitle} walks you through the`,
     'remaining verification and optional setup (runtime check, version check,',
     'profile intake, alias, workspace, Atlassian). Every step is idempotent.',
     '',