@stravica-ai/digital-operator-pa 0.1.46 → 0.1.48

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

@@ -94,8 +94,25 @@ line to run; do not run it for them (their shell rc is not our file to write).
 
 Ask if they want the local workspace started now. On yes, run
 `pnpm exec pa workspace start` in the background and print the URL from
-`operator/config/preferences.json:workspacePort` (default 4200). On no, note
-that `pnpm exec pa workspace start` is the verb whenever they want it.
+`operator/config/preferences.json:workspacePort` (default 4200).
+
+If the start fails because the configured port is already in use (the
+operator has something else on 4200, or the previous session did not
+shut down cleanly), do NOT stop the walkthrough. Instead:
+
+1. Pick a free port at or above 4210 (probe 4210, 4211, 4212 ... in
+   order until one is free).
+2. Retry `pnpm exec pa workspace start --port N` with that port.
+3. On success, update `operator/config/preferences.json` with
+   `"workspacePort": N` so subsequent sessions start on the same port
+   without asking again. Preserve the rest of the file exactly, and
+   round-trip through `JSON.parse` / `JSON.stringify` with a two-space
+   indent to keep the on-disk shape stable.
+4. Tell the operator you moved the workspace off 4200 and named the
+   port that stuck.
+
+On no, note that `pnpm exec pa workspace start` is the verb whenever
+they want it.
 
 ### 6. atlassianOffer
 

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.',
     '',

package/dist/engineering-pa-scaffold/src/prompts.mjs

@@ -25,10 +25,54 @@ export function validatePaName(value) {
   return { ok: true, value: trimmed };
 }
 
-/** Non-empty, 1-80 chars, trimmed. Allows letters / spaces / punctuation. */
+/**
+ * Strip one wrapping pair of straight or typographic quotes around a
+ * string, if present, then trim. Applied to name-class identity fields so
+ * an operator who types their name with wrapping quotes ("Barry" or
+ * U+201CBarryU+201D) never lands a quoted value in preferences.json — the
+ * greeting renderer is faithful, so a quoted store shows up on the home
+ * screen ("Evening, "Barry"").
+ *
+ * Handled pairs (any single pair around the whole value, whitespace
+ * tolerated on the outside):
+ *   - ASCII double quote      U+0022
+ *   - ASCII single quote      U+0027
+ *   - Left/right double quote U+201C U+201D
+ *   - Left/right single quote U+2018 U+2019
+ *   - Left/right guillemet    U+00AB U+00BB
+ *
+ * Only ONE wrapping pair is stripped; a value that is deliberately quoted
+ * for another reason (e.g. `'''`) still surfaces as data. Whitespace
+ * inside the quotes is preserved by the trim after the strip.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function stripWrappingQuotes(value) {
+  if (typeof value !== 'string') return value;
+  let s = value.trim();
+  const pairs = [
+    ['"', '"'],
+    ["'", "'"],
+    ['“', '”'],
+    ['‘', '’'],
+    ['«', '»'],
+  ];
+  for (const [open, close] of pairs) {
+    if (s.length >= 2 && s.startsWith(open) && s.endsWith(close)) {
+      s = s.slice(open.length, s.length - close.length).trim();
+      break;
+    }
+  }
+  return s;
+}
+
+/** Non-empty, 1-80 chars, trimmed, wrapping quotes stripped. Allows letters / spaces / punctuation. */
 export function validateOperatorName(value) {
   if (typeof value !== 'string') return { ok: false, reason: 'must be a string' };
-  const trimmed = value.trim();
+  // Strip wrapping quotes BEFORE the length check so a padded typographic
+  // pair around a short name never trips the max-length ceiling.
+  const trimmed = stripWrappingQuotes(value);
   if (trimmed.length < 1) return { ok: false, reason: 'must not be empty' };
   if (trimmed.length > 80) return { ok: false, reason: 'must be at most 80 characters' };
   return { ok: true, value: trimmed };
@@ -64,7 +108,7 @@ export async function promptValues(seam, defaults) {
   out.operatorName = await ensureValid(
     seam,
     defaults.operatorName,
-    "Operator name (the human this PA serves, e.g. 'Baz'): ",
+    'Operator name (the human this PA serves, e.g. Baz): ',
     validateOperatorName,
   );
 

package/dist/engineering-pa-workspace/app/assets/theme.css

@@ -3,8 +3,9 @@
  *
  * Two themes live here: dark (default) and light, toggled by the operator
  * via the banner button. Selection is persisted in localStorage under
- * `dave.theme` and applied to `documentElement.dataset.theme` before first
- * paint by the inline init script in each page's <head>.
+ * `dop.theme` (product-generic; legacy `dave.theme` is read once and
+ * migrated forward) and applied to `documentElement.dataset.theme` before
+ * first paint by the inline init script in each page's <head>.
  *
  * Token set is the union of every page's prior `:root` block. Both themes
  * MUST define the same set of names — any unilateral token becomes invisible

package/dist/engineering-pa-workspace/app/assets/theme.js

@@ -4,7 +4,7 @@
  * Two responsibilities split across two surfaces:
  *
  * 1. Pre-paint init. Each page also embeds a tiny inline <script> in <head>
- *    that reads `localStorage.dave.theme` and sets
+ *    that reads `localStorage.dop.theme` and sets
  *    `documentElement.dataset.theme` BEFORE first paint. That avoids a
  *    light-flash on a dark-preference user (FOUC). The inline script is the
  *    duplicate of `applyStoredTheme()` below; keeping it inline is the
@@ -18,7 +18,17 @@
  *    context (matching banner.js's behaviour) so a page opened directly
  *    still owns its own toggle.
  *
- * Storage: localStorage key `dave.theme`, values 'dark' | 'light'.
+ * Storage: localStorage key `dop.theme`, values 'dark' | 'light'. The
+ * canonical token lives in `src/workspace-page-contract.mjs`; this file
+ * hand-copies the literal because it runs in the browser and cannot
+ * import ESM modules from that path. The theme parity test pins the two
+ * copies to the same value.
+ *
+ * Legacy: `dave.theme` is the pre-rename key. On first boot after the
+ * rename we read it once, copy the value to `dop.theme`, and never touch
+ * it again — nobody re-picks their theme just because the estate went
+ * product-generic. See `src/workspace-page-contract.mjs`.
+ *
  * Default when unset: 'dark' (operator preference — see CLAUDE.md). We do
  * NOT consult prefers-color-scheme; dark is the chosen default and we don't
  * want auto-detection overriding it on first load.
@@ -26,15 +36,22 @@
 (function () {
   'use strict';
 
-  var STORAGE_KEY = 'dave.theme';
+  var STORAGE_KEY = 'dop.theme';
+  var LEGACY_STORAGE_KEY = 'dave.theme';
   var DEFAULT_THEME = 'dark';
   var VALID = { dark: 1, light: 1 };
-  var MESSAGE_TYPE = 'dave.theme.set';
+  var MESSAGE_TYPE = 'dop.theme.set';
 
   function readStored() {
     try {
       var raw = localStorage.getItem(STORAGE_KEY);
       if (raw && VALID[raw]) return raw;
+      // Legacy fallback: one-time migration from the pre-rename key.
+      var legacy = localStorage.getItem(LEGACY_STORAGE_KEY);
+      if (legacy && VALID[legacy]) {
+        try { localStorage.setItem(STORAGE_KEY, legacy); } catch (_e) { /* no-op */ }
+        return legacy;
+      }
     } catch (_e) { /* storage unavailable — fall through to default */ }
     return DEFAULT_THEME;
   }
@@ -148,12 +165,18 @@
     boot();
   }
 
-  // Expose for tests + the inline init helper.
-  window.__daveTheme = {
+  // Expose for tests + the inline init helper. `__daveTheme` is kept as an
+  // alias for anything under `operator/extensions/**` that grew a direct
+  // reference before the rename; `__dopTheme` is the canonical name and
+  // is what new callers should use.
+  var api = {
     read: readStored,
     write: writeStored,
     apply: applyTheme,
     storageKey: STORAGE_KEY,
+    legacyStorageKey: LEGACY_STORAGE_KEY,
     defaultTheme: DEFAULT_THEME,
   };
+  window.__dopTheme = api;
+  window.__daveTheme = api;
 })();

package/dist/engineering-pa-workspace/app/banner.js

@@ -22,7 +22,11 @@
 
   const ENDPOINT = '/__api/status-mon';
   const POLL_INTERVAL_MS = 30_000;
-  const DISMISSED_KEY = 'dave.statusmon.dismissed';
+  // Product-generic key; the pre-rename store was 'dave.statusmon.dismissed'.
+  // Read-once fallback keeps existing dismissals across the rename so a
+  // resolved incident someone had already dismissed doesn't reappear.
+  const DISMISSED_KEY = 'dop.statusmon.dismissed';
+  const LEGACY_DISMISSED_KEY = 'dave.statusmon.dismissed';
 
   const SLOT_ID = 'global-banner';
 
@@ -36,7 +40,15 @@
 
   function readDismissed() {
     try {
-      const raw = localStorage.getItem(DISMISSED_KEY);
+      var raw = localStorage.getItem(DISMISSED_KEY);
+      if (!raw) {
+        // Legacy fallback: read the pre-rename store once and migrate.
+        var legacy = localStorage.getItem(LEGACY_DISMISSED_KEY);
+        if (legacy) {
+          try { localStorage.setItem(DISMISSED_KEY, legacy); } catch { /* no-op */ }
+          raw = legacy;
+        }
+      }
       if (!raw) return [];
       const parsed = JSON.parse(raw);
       if (!Array.isArray(parsed)) return [];

package/dist/engineering-pa-workspace/app/delegations.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Delegations — Workspace</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/home.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Home</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/index.html

@@ -6,7 +6,7 @@
 <title>Digital Operator</title>
 <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Crect width='16' height='16' rx='3' fill='%236366f1'/%3E%3Ctext x='8' y='12' font-family='monospace' font-size='11' font-weight='bold' text-anchor='middle' fill='%23121218'%3ED%3C/text%3E%3C/svg%3E">
 <script src="/banner.js" defer></script>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/knowledge-map.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Knowledge Map — Workspace</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/knowledge.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Knowledge</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/notes.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Notes — Dave</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/onboarding.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Welcome to your PA</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/profile.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Profile</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/project-detail.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Project Detail</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/projects.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Projects — Dave</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/repos.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Git Overview — Workspace</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/schedules.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Schedules — Workspace</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/secrets.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Secrets</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/staging.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Staging Inbox — Workspace</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/tasks.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Tasks — Dave</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/app/viewer.html

@@ -4,7 +4,7 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>Document Viewer</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/index.mjs

@@ -10,3 +10,19 @@ export const version = '0.1.1';
 export { loadNav } from './src/nav.mjs';
 export { startPoller as startStatusMonPoller } from './src/status-mon/poller.mjs';
 export { handleApi } from './src/api.mjs';
+
+// Shared workspace-page contract — every core page and every scaffolded
+// extension page carries the same head + top-of-body markup. Owning the
+// tokens here stops the scaffold and the core pages drifting on the theme
+// storage key.
+export {
+  THEME_STORAGE_KEY,
+  THEME_LEGACY_STORAGE_KEY,
+  THEME_MESSAGE_TYPE,
+  THEME_CSS_LINK,
+  THEME_JS_TAG,
+  BANNER_JS_TAG,
+  GLOBAL_BANNER_HTML,
+  prepaintScriptTag,
+  standardHeadInner,
+} from './src/workspace-page-contract.mjs';

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

@@ -1,11 +1,12 @@
 {
   "name": "@stravica-ai/engineering-pa-workspace",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Workspace server + viewer — operator-facing local web UI for the PA platform.",
   "type": "module",
   "main": "./index.mjs",
   "exports": {
-    ".": "./index.mjs"
+    ".": "./index.mjs",
+    "./index.mjs": "./index.mjs"
   },
   "dependencies": {
     "@stravica-ai/engineering-pa-cli": "workspace:*",

package/dist/engineering-pa-workspace/src/install-daemon.mjs

@@ -46,6 +46,7 @@ import { homedir, platform } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { readPreferencesSync } from '../../engineering-pa-core/src/preferences.mjs';
+import { findRepoRootSync } from './repo-root.mjs';
 import {
   darwinLogBasenames,
   launchdLabelFor,
@@ -60,25 +61,13 @@ import {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
-// Resolve the operator repo root. In v2 this package is installed at
-// node_modules/@stravica-ai/engineering-pa-workspace/, so walking up three
-// __dirname levels lands inside node_modules/, not at the operator repo
-// root. Precedence:
-//   1. DAVE_REPO_ROOT or PA_REPO_ROOT env (explicit override)
-//   2. Walk up from process.cwd() looking for .git or pnpm-workspace.yaml
-//   3. Fall back to process.cwd() (best-effort; lets dry-run work in odd
-//      checkouts)
-function findRepoRoot(start) {
-  let d = start;
-  while (d && d !== resolve(d, '..')) {
-    if (existsSync(join(d, '.git')) || existsSync(join(d, 'pnpm-workspace.yaml'))) return d;
-    d = resolve(d, '..');
-  }
-  return null;
-}
-
-const envRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
-const REPO_ROOT = envRoot ? resolve(envRoot) : (findRepoRoot(process.cwd()) || process.cwd());
+// Instance-root resolution routed through the shared helper (see
+// `./repo-root.mjs`). Under the published tarball layout, `__dirname`-relative
+// walks land inside `node_modules/@stravica-ai/digital-operator-pa/dist/` and
+// mis-target every derived path; the shared resolver walks up from cwd for
+// `.git`, `operator/config/preferences.json`, or `pnpm-workspace.yaml`, and
+// honours `DAVE_REPO_ROOT` / `PA_REPO_ROOT` overrides.
+const REPO_ROOT = findRepoRootSync();
 const SERVER_SCRIPT = join(__dirname, 'server.mjs');
 
 /**

package/dist/engineering-pa-workspace/src/repo-root.mjs

@@ -0,0 +1,100 @@
+// repo-root.mjs — shared sync resolver for the operator instance root.
+//
+// Under the published tarball layout, `@stravica-ai/engineering-pa-workspace`
+// lives at `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-workspace/`.
+// A `resolve(__dirname, '..', '..', '..')` walk from `src/` therefore lands
+// inside the `digital-operator-pa` package directory (a pnpm-store hard-link),
+// NOT at the operator repo root — silently misdirecting every file the
+// workspace derives from that path (`.ws.pid`, `.ws.log`, preferences overlay
+// reads, `paName` lookups, the server subprocess cwd).
+//
+// The resolver mirrors the precedence the rest of the workspace package
+// already uses (`server.mjs`, `install-daemon.mjs`):
+//
+//   1. `DAVE_REPO_ROOT` or `PA_REPO_ROOT` env override (tests + operator-set).
+//   2. Walk up from `process.cwd()` looking for a marker that identifies an
+//      operator instance root:
+//        - `.git` (present in every scaffolded instance — pa-init runs `git
+//          init` at scaffold time).
+//        - `operator/config/preferences.json` (the canonical instance marker;
+//          matches instances that lost their `.git` for any reason).
+//        - `pnpm-workspace.yaml` (matches monorepo checkouts, e.g. this
+//          engineering-pa-dev repo itself, so package-local tests still work).
+//   3. Fall back to `process.cwd()` so pre-scaffold and dry-run flows still
+//      have a stable value to render.
+//
+// The `startDir` argument is injectable for tests and callers that need to
+// resolve from a directory other than `process.cwd()`. Prod callers use
+// the default.
+
+import { existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const MARKERS = [
+  '.git',
+  join('operator', 'config', 'preferences.json'),
+  'pnpm-workspace.yaml',
+];
+
+/**
+ * Walk up from `start` looking for the first directory that contains any
+ * marker in {@link MARKERS}. Returns the directory path, or null when the
+ * walk reaches the filesystem root without a hit.
+ *
+ * @param {string} start
+ * @returns {string|null}
+ */
+export function walkUpForMarker(start) {
+  let d = resolve(start);
+  while (d && d !== resolve(d, '..')) {
+    for (const marker of MARKERS) {
+      if (existsSync(join(d, marker))) return d;
+    }
+    d = resolve(d, '..');
+  }
+  return null;
+}
+
+// Process-level guard so the fallback warning fires at most once per
+// process, no matter how many callers hit the resolver. Tests can reset
+// via the exported `_resetFallbackWarningForTests` helper below.
+let _fallbackWarned = false;
+
+/** Test-only reset for the once-per-process fallback warning latch. */
+export function _resetFallbackWarningForTests() {
+  _fallbackWarned = false;
+}
+
+/**
+ * Resolve the operator instance root. Deterministic and synchronous; safe
+ * to call at module top-level. See the header comment for the full
+ * precedence rule.
+ *
+ * When no marker is found AND no env override is set, emit ONE stderr
+ * warning naming the cwd we're falling back to and the two overrides that
+ * would silence it. The walk still returns cwd so pre-scaffold and dry-run
+ * flows keep working — the warning is a diagnostic, not an error.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.startDir=process.cwd()] Directory to start the walk from.
+ * @param {NodeJS.ProcessEnv} [opts.env=process.env] Env source (tests inject).
+ * @param {(msg: string) => void} [opts.warn] Optional warn sink (tests inject).
+ * @returns {string} Absolute path.
+ */
+export function findRepoRootSync(opts = {}) {
+  const env = opts.env || process.env;
+  const startDir = opts.startDir || process.cwd();
+  const envRoot = env.DAVE_REPO_ROOT || env.PA_REPO_ROOT;
+  if (envRoot) return resolve(envRoot);
+  const found = walkUpForMarker(startDir);
+  if (found) return found;
+  const fallback = resolve(startDir);
+  if (!_fallbackWarned) {
+    _fallbackWarned = true;
+    const warn = opts.warn || ((m) => process.stderr.write(m + '\n'));
+    warn(
+      `workspace: no instance marker (.git, operator/config/preferences.json, pnpm-workspace.yaml) found walking up from ${fallback}; falling back to cwd. Set DAVE_REPO_ROOT or PA_REPO_ROOT to silence.`,
+    );
+  }
+  return fallback;
+}

package/dist/engineering-pa-workspace/src/server.mjs

@@ -33,32 +33,18 @@ import { buildAllowedHosts, buildAllowedOrigins, checkRequestGuards, isGuardedPa
 import { readTeamScopeConfigSync } from '../../engineering-pa-core/src/desk/team-scope.mjs';
 import { readPreferencesSync } from '../../engineering-pa-core/src/preferences.mjs';
 import { startPoller as startStatusMonPoller } from './status-mon/poller.mjs';
+import { findRepoRootSync } from './repo-root.mjs';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
 
 // In v2 the workspace package is installed inside the operator repo at
-// `node_modules/@stravica-ai/engineering-pa-workspace/`. The operator repo root
-// is wherever `.git` lives — discovered by walking up from process.cwd(), or
-// taken from DAVE_REPO_ROOT / PA_REPO_ROOT for tests and ephemeral harnesses.
-// The package's own assets live at `../app/` (one level up from src/).
-function findRepoRootSync(start) {
-  let d = start;
-  let prev;
-  while (d && d !== prev) {
-    try {
-      const s = existsSync(join(d, '.git'));
-      if (s) return d;
-    } catch { /* ignore */ }
-    prev = d;
-    d = resolve(d, '..');
-  }
-  return null;
-}
-
-const envRepoRoot = process.env.DAVE_REPO_ROOT || process.env.PA_REPO_ROOT;
-const REPO_ROOT = envRepoRoot
-  ? resolve(envRepoRoot)
-  : (findRepoRootSync(process.cwd()) || process.cwd());
+// `node_modules/@stravica-ai/engineering-pa-workspace/`. The operator repo
+// root is resolved via the shared helper (`./repo-root.mjs`), which walks
+// up from cwd for `.git`, `operator/config/preferences.json`, or
+// `pnpm-workspace.yaml`, and honours `DAVE_REPO_ROOT` / `PA_REPO_ROOT`
+// overrides. The package's own assets live at `../app/` (one level up
+// from src/).
+const REPO_ROOT = findRepoRootSync();
 const APP_DIR = resolve(__dirname, '..', 'app');
 
 // Silent by default. Set WS_DEBUG=1 to re-enable startup banner, file-change
@@ -232,8 +218,9 @@ function resetIdle() {
 // palette block, which broke the theme toggle on the content-calendar
 // preview iframe (operator-reported, 2026-06-27). The fix matches what
 // viewer.html does: link the shared theme.css, defer-load theme.js, pre-paint
-// init reads localStorage 'dave.theme', body in humanist sans for prose, and
-// .md-body strong uses the new --emphasis token (matching .content strong).
+// init reads localStorage 'dop.theme' (with a one-time legacy 'dave.theme'
+// fallback), body in humanist sans for prose, and .md-body strong uses the
+// new --emphasis token (matching .content strong).
 // Exported so unit tests can assert on the output without spinning up the
 // HTTP server.
 export function markdownPage(rawContent, filePath) {
@@ -248,7 +235,7 @@ export function markdownPage(rawContent, filePath) {
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>${title}</title>
-<script>(function(){try{var t=localStorage.getItem('dave.theme');document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
+<script>(function(){try{var t=localStorage.getItem('dop.theme');if(!t){var legacy=localStorage.getItem('dave.theme');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('dop.theme',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
 <style>

package/dist/engineering-pa-workspace/src/status-mon/run.mjs

@@ -29,6 +29,7 @@ import { fileURLToPath } from 'node:url';
 
 import { readPreferencesSync } from '../../../engineering-pa-core/src/preferences.mjs';
 import { poll, resolveSources, mergeWithPrevious } from './poll.mjs';
+import { findRepoRootSync } from '../repo-root.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -61,15 +62,15 @@ function parseArgs(argv) {
 }
 
 function findRepoRoot() {
+  // DAVE_ROOT is the historical status-mon env; keep it as a first-class
+  // override so scheduled runs already setting it are unaffected. Otherwise
+  // route through the shared resolver (`../repo-root.mjs`), which walks up
+  // from cwd for the instance markers and also honours DAVE_REPO_ROOT /
+  // PA_REPO_ROOT. The old fallback (`resolve(__dirname, '..', '..', '..')`)
+  // was broken under the installed tarball layout — see
+  // `w-2026-09-17-dave-016`.
   if (process.env.DAVE_ROOT) return process.env.DAVE_ROOT;
-  let dir = __dirname;
-  while (dir !== '/' && dir !== '.') {
-    if (existsSync(join(dir, '.git'))) return dir;
-    const parent = dirname(dir);
-    if (parent === dir) break;
-    dir = parent;
-  }
-  return resolve(__dirname, '..', '..', '..');
+  return findRepoRootSync();
 }
 
 function readPreviousState(statePath) {

package/dist/engineering-pa-workspace/src/workspace-page-contract.mjs

@@ -0,0 +1,98 @@
+// workspace-page-contract.mjs — the single source of truth for the head
+// and top-of-body markup every workspace HTML page must ship.
+//
+// Every page served by the workspace (core pages under `packages/workspace/app/`
+// and extension pages scaffolded by `pa-init workspace-extension`) has to
+// carry the same four head tags in the same order:
+//
+//   1. Inline pre-paint script that reads the theme from localStorage and
+//      sets `documentElement.dataset.theme` BEFORE first paint. Without
+//      this, dark-preference users see a light-flash (FOUC).
+//   2. Link to `/core/tools/workspace/app/assets/theme.css` (the shared
+//      palette + `[data-theme=...]` token blocks).
+//   3. Deferred `/core/tools/workspace/app/assets/theme.js` (toggle button,
+//      cross-frame coordination, storage sync).
+//   4. Deferred `/banner.js` (the global status banner poller).
+//
+// And the body's first child must be `<div id="global-banner"></div>` so
+// `banner.js` has a mount point.
+//
+// This module owns the string forms of all four so a scaffold-generated
+// extension page and a hand-authored core page can never drift. Core pages
+// still hand-copy the block for now (their inline `<style>` sits after
+// theme.js in the head, so a full migration is more than a mechanical
+// substitution and is left as a follow-up); the scaffold and the theme
+// parity test import from here.
+//
+// Storage-key policy: the theme key is `'dop.theme'` (product-generic —
+// `dop` = Digital Operator PA). Legacy stores under `'dave.theme'` are
+// migrated on first read (see `theme.js`) so nobody re-picks their theme
+// after the rename.
+
+/**
+ * localStorage key the theme selection persists under. Product-generic;
+ * shared by the pre-paint bootstrap, theme.js, and every consuming page.
+ */
+export const THEME_STORAGE_KEY = 'dop.theme';
+
+/**
+ * Legacy localStorage key. Read once on first boot when the new key is
+ * absent and copied forward. Never written. Kept exported so tests can
+ * pin the migration path without hardcoding the literal.
+ */
+export const THEME_LEGACY_STORAGE_KEY = 'dave.theme';
+
+/**
+ * postMessage type the shell uses to broadcast a theme change into
+ * same-origin iframed pages. Product-generic; renamed alongside the
+ * storage key.
+ */
+export const THEME_MESSAGE_TYPE = 'dop.theme.set';
+
+/**
+ * The inline pre-paint bootstrap. Reads the new key, falls back to the
+ * legacy key when the new one is unset, applies to
+ * `documentElement.dataset.theme` before first paint. Same shape the
+ * markdownPage renderer emits so a fresh direct-load never flashes.
+ *
+ * Returned as a self-contained `<script>...</script>` tag; embed it in
+ * `<head>` BEFORE the theme.css link and before any body content.
+ */
+export function prepaintScriptTag() {
+  return `<script>(function(){try{var t=localStorage.getItem('${THEME_STORAGE_KEY}');if(!t){var legacy=localStorage.getItem('${THEME_LEGACY_STORAGE_KEY}');if(legacy==='light'||legacy==='dark'){t=legacy;try{localStorage.setItem('${THEME_STORAGE_KEY}',legacy);}catch(_){}}}document.documentElement.dataset.theme=(t==='light'||t==='dark')?t:'dark';}catch(_){document.documentElement.dataset.theme='dark';}})();</script>`;
+}
+
+/** Link tag for the shared theme stylesheet. */
+export const THEME_CSS_LINK = '<link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">';
+
+/** Deferred script tag for the shared theme.js toggle + storage coordinator. */
+export const THEME_JS_TAG = '<script src="/core/tools/workspace/app/assets/theme.js" defer></script>';
+
+/** Deferred script tag for the global status banner. */
+export const BANNER_JS_TAG = '<script src="/banner.js" defer></script>';
+
+/**
+ * The mount point banner.js expects. Insert as the first child of `<body>`.
+ */
+export const GLOBAL_BANNER_HTML = '<div id="global-banner"></div>';
+
+/**
+ * Build the standard `<head>` inner markup a workspace page must ship.
+ * Charset, viewport, `<title>`, then the four theme + banner tags in the
+ * documented order. Callers append their own `<style>` block (if any) AFTER
+ * the returned string and BEFORE closing `</head>`.
+ *
+ * @param {object} opts
+ * @param {string} opts.title  page title (already HTML-escaped by caller)
+ */
+export function standardHeadInner({ title }) {
+  return [
+    '<meta charset="utf-8" />',
+    '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+    `<title>${title}</title>`,
+    prepaintScriptTag(),
+    THEME_CSS_LINK,
+    THEME_JS_TAG,
+    BANNER_JS_TAG,
+  ].join('\n');
+}

package/dist/engineering-pa-workspace/src/ws.mjs

@@ -28,10 +28,20 @@ import {
   restartCommand,
 } from './supervisor.mjs';
 import { resolvePaName } from './unit-name.mjs';
+import { findRepoRootSync } from './repo-root.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
-const REPO_ROOT = resolve(__dirname, '..', '..', '..');
+// Instance root — NOT `resolve(__dirname, '..', '..', '..')`. Under the
+// published `@stravica-ai/digital-operator-pa` tarball layout the workspace
+// package lives under `dist/engineering-pa-workspace/`, so a three-parent
+// __dirname walk lands inside the pnpm-store hard-linked package directory
+// rather than at the operator instance root. `findRepoRootSync` walks up
+// from `process.cwd()` for `.git` / `operator/config/preferences.json` /
+// `pnpm-workspace.yaml` and honours `DAVE_REPO_ROOT` / `PA_REPO_ROOT`
+// overrides. See `./repo-root.mjs` for the full precedence rule and
+// `w-2026-09-17-dave-016` for the P1 that caused this to be extracted.
+const REPO_ROOT = findRepoRootSync();
 
 const SERVER_SCRIPT = join(__dirname, 'server.mjs');
 // Env overrides let tests point at a temp directory so the real repo's
@@ -326,6 +336,7 @@ async function cmdStart() {
       const who = holder ? ` (held by PID ${holder.pid}${holder.command ? ` — ${holder.command}` : ''})` : '';
       console.error(`Error: Stale PID file references dead PID ${existing.pid}, but port ${existing.port} is in use${who}.`);
       console.error('Refusing to kill an unrelated process. Remove the PID file manually or use a different port.');
+      console.error('Hint: run `pa workspace start --port <N>` with a free port, or set `workspacePort` in operator/config/preferences.json.');
       process.exit(1);
     }
     removePid();
@@ -334,6 +345,7 @@ async function cmdStart() {
   // Check if port is already in use by something else
   if (await checkPort(port)) {
     console.error(`Error: Port ${port} is already in use by another process.`);
+    console.error('Hint: run `pa workspace start --port <N>` with a free port, or set `workspacePort` in operator/config/preferences.json.');
     process.exit(1);
   }
 

package/docs/what-it-can-do.md

@@ -43,7 +43,7 @@ The PA is a Digital Operator that runs inside Claude Code on your laptop: it run
 
 - The dispatch-briefer analyses your request and writes an eight-section brief in fresh context, covering boundaries, outputs and completion criteria.
 - Work can go to a single agent or a task group with a coordinator and workers, or stay in the current conversation.
-- Parallel workers use separate git worktrees in the assistant's own repositories; writes to downstream project repositories run sequentially.
+- Parallel workers use separate git worktrees in the operator's own repositories; writes to downstream project repositories run sequentially.
 - A coordinator hook enforces tool-use policy inside Claude Code.
 
 ## The roles it comes with
@@ -74,12 +74,12 @@ The PA is a Digital Operator that runs inside Claude Code on your laptop: it run
 
 - Solo use is the shipped setup; team lead and member modes are not implemented.
 - The remote library is dormant in the default local mode.
-- HQ additions, including specialised roles, the boot-context hook and distillation-health injection, are not shipped.
+- Specialised roles and the session-boot context injections used on the first-party estate are not part of the shipped package.
 - Connections to services through MCP need your own Claude Code configuration.
 - You supply your voice guide, personal writing rules, principles and profile knowledge; the starter content is structure and placeholders.
 - Sharing repositories or memory across machines needs a remote and coordination that you set up.
 
 ## How to start
 
-Open the getting started guide.  
-Follow it to set up the assistant on your laptop.
+Open [docs/onboarding-solo.md](./onboarding-solo.md).
+Follow it to set up your Digital Operator on your laptop.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
@@ -39,11 +39,8 @@
     "LICENSE"
   ],
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Stravica/digital-operator-pa.git",
-    "directory": "packages/engineering-pa"
-  },
+  "homepage": "https://stravica.ai",
+  "bugs": "https://stravica.ai",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"