@stravica-ai/digital-operator-pa 0.1.39 → 0.1.40

package/README.md

@@ -12,9 +12,14 @@ pnpm add @stravica-ai/digital-operator-pa
 ```
 
 Requires Node 24+. The package is public on `registry.npmjs.org` and needs no
-registry auth. See [`../../docs/installing.md`](../../docs/installing.md) for the
+registry auth. See [`./docs/installing.md`](./docs/installing.md) for the
 full install guide.
 
+New to the platform and setting up a single-person PA on one laptop? Follow
+[`./docs/onboarding-solo.md`](./docs/onboarding-solo.md) — a
+ten-minute walkthrough from an empty directory to a working PA under your
+own Claude Code subscription.
+
 ## Bins
 
 The wrapper exposes the platform's operator-facing CLIs:
@@ -162,7 +167,7 @@ pnpm --filter @stravica-ai/digital-operator-pa pack              # produce a rea
 `access: public`. Publishes are manual (run by a maintainer with npmjs publish
 rights) from this directory: `pnpm publish` triggers `build.mjs` via `prepack`,
 then ships the bundled tarball to npmjs.org. `ci.yml`'s `dry-publish` job proves
-the pack/publish mechanics on every push. See [`../../docs/installing.md`](../../docs/installing.md)
+the pack/publish mechanics on every push. See [`./docs/installing.md`](./docs/installing.md)
 for the release-pipeline section.
 
 ### Retired predecessor

package/dist/engineering-pa-core/knowledge/content-voice/banned-ai-tells-taxonomy.md

@@ -24,7 +24,7 @@ The taxonomy every operator's banned-tells doc inherits. Category names and orde
 
 **Operator overlays** add operator-specific entries under each existing category. Same category names, same order; more entries.
 
-**Category 13** exists so operator-specific bans have a home when they don't fit the mechanism categories. Barry-voice specific bans (e.g. "cut" as a noun) land here, not in Vocabulary.
+**Category 13** exists so operator-specific bans have a home when they don't fit the mechanism categories. Operator-voice specific bans (e.g. one operator hates "cut" as a noun) land here, not in Vocabulary.
 
 ## Related
 

package/dist/engineering-pa-core/knowledge/knowledge-memory/staging-and-observations.md

@@ -41,11 +41,11 @@ Reasoning: session-end batching means the observation is filtered through your o
 - **Why it matters.** Your best guess at the general rule the observation reveals. The Librarian may reshape this — but your inference from the concrete moment is useful signal.
 
 Bad observation:
-> `20260705T100000Z_preference.md` — Baz likes short posts.
+> `20260705T100000Z_preference.md` — operator likes short posts.
 
 Good observation:
-> `20260705T100000Z_preference_barry-prefers-short-li-posts-under-300-chars.md`
-> Task: drafting a LI comment reply on Cole Medin's post. Draft came back at 480 chars. Baz's edit cut it to 210 chars and said "keep them under 300, longer feels performative". Suggests LI-comment character target should default lower than the surface's affordance implies.
+> `20260705T100000Z_preference_operator-prefers-short-li-posts-under-300-chars.md`
+> Task: drafting a LinkedIn comment reply. Draft came back at 480 chars. The operator's edit cut it to 210 chars and said "keep them under 300, longer feels performative". Suggests LinkedIn-comment character target should default lower than the surface's affordance implies.
 
 ## Don't route directly
 

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

@@ -7,6 +7,7 @@
 // kind: 'dir' (mkdir -p) | 'file' (write file with contents) | 'json'
 // (stringify + write).
 
+import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -18,6 +19,14 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 /** Path to the CLAUDE.md template (relative to this module). */
 export const CLAUDE_MD_TEMPLATE_PATH = resolve(__dirname, '..', 'templates', 'CLAUDE.md.template');
 
+/** Path to the root-CLAUDE.md pointer template (relative to this module). */
+export const ROOT_CLAUDE_MD_TEMPLATE_PATH = resolve(
+  __dirname,
+  '..',
+  'templates',
+  'root-CLAUDE.md.template',
+);
+
 /** Path to the operator README template (relative to this module). */
 export const OPERATOR_README_TEMPLATE_PATH = resolve(
   __dirname,
@@ -26,6 +35,22 @@ export const OPERATOR_README_TEMPLATE_PATH = resolve(
   'operator-README.md.template',
 );
 
+/**
+ * Path to the `/research` slash-command doc, resolved out of the bundled
+ * engineering-pa-core package. Two candidates so this works both from the
+ * source monorepo (`packages/scaffold/src/generator.mjs` → `packages/core/…`)
+ * and from the packed tarball (`dist/engineering-pa-scaffold/src/generator.mjs`
+ * → `dist/engineering-pa-core/…`). The scaffold reads the file at plan time
+ * so the copy the colleague gets never drifts from the packaged canonical.
+ */
+const RESEARCH_COMMAND_CANDIDATES = [
+  resolve(__dirname, '..', '..', 'engineering-pa-core', 'docs', 'commands', 'research.md'),
+  resolve(__dirname, '..', '..', 'core', 'docs', 'commands', 'research.md'),
+];
+
+export const RESEARCH_COMMAND_TEMPLATE_PATH =
+  RESEARCH_COMMAND_CANDIDATES.find((p) => existsSync(p)) ?? RESEARCH_COMMAND_CANDIDATES[0];
+
 /**
  * The base set of knowledge domains seeded into every fresh PA instance.
  * Per the methodology doc: engineering, ops, agent-ops, knowledge-meta,
@@ -78,6 +103,19 @@ export function renderClaudeMd(template, config) {
     .replaceAll('{COMMUNICATION_STYLE}', config.communicationStyle);
 }
 
+/**
+ * Render the root-CLAUDE.md pointer with the config. The root file is a
+ * short quick-reference that points at the full agent CLAUDE.md — the
+ * split mirrors the established estate convention (root pointer +
+ * canonical agent file) so the two files never drift as byte-identical
+ * duplicates.
+ */
+export function renderRootClaudeMd(template, config) {
+  return template
+    .replaceAll('{PA_NAME}', config.paName)
+    .replaceAll('{OPERATOR_NAME}', config.operatorName);
+}
+
 /**
  * Render the operator-repo README template. Uses the same token set as
  * CLAUDE.md.template for consistency.
@@ -302,6 +340,69 @@ export function buildGitkeep() {
   return '';
 }
 
+/**
+ * Build the .claude/settings.json contents.
+ *
+ * Two things:
+ *   1. `permissions.deny` for the built-in `deep-research` skill and
+ *      workflow. The core operating model (Bucket 4) directs the PA to
+ *      the `/research` verb, which persists a session and promotes
+ *      durable answers back into the knowledge library. The built-in
+ *      `deep-research` skill produces no such trail and would silently
+ *      short-circuit the discipline; deny is the correct default.
+ *
+ *   2. `hooks.PreToolUse` wiring `pa-coordinator-hook` for the matcher
+ *      the coordinator-hook doc gives. The hook is a no-op unless the
+ *      operator sets `PA_COORDINATOR_MODE=1` in their shell, so the
+ *      scaffold ships the wiring inert. A per-repo overlay slot is
+ *      scaffolded alongside as `.claude/coordinator-overlay.json`.
+ *
+ * SessionStart hooks (boot-context style injection) are deliberately
+ * NOT scaffolded — the boot-context tool lives in the HQ estate, not
+ * the published package. Scaffolding a hook that names a binary the
+ * colleague does not have would fire on every session boot with a
+ * non-blocking error. Documented in docs/onboarding-solo.md under
+ * "what is not included in solo mode".
+ */
+export function buildClaudeSettingsJson() {
+  return {
+    permissions: {
+      deny: ['Skill(skill:deep-research)', 'Workflow(name:deep-research)'],
+    },
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: '^(Bash|Read|Write|Edit|NotebookEdit|Grep|Glob|WebFetch|WebSearch)$',
+          hooks: [
+            {
+              type: 'command',
+              command: 'pa-coordinator-hook',
+            },
+          ],
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Build the .claude/coordinator-overlay.json starter. The overlay is a
+ * per-repo extension slot for `pa-coordinator-hook` — see the doc at
+ * packages/cli/docs/coordinator-hook.md for the merge contract. Only
+ * `tier2.<Bash|Read|Write>.allowPatterns` / `.allowPathPatterns` may be
+ * extended; the file ships empty so the presence of the overlay is
+ * documentation on its own without widening the default policy.
+ */
+export function buildCoordinatorOverlayJson() {
+  return {
+    tier2: {
+      Bash: { allowPatterns: [] },
+      Read: { allowPathPatterns: [] },
+      Write: { allowPathPatterns: [] },
+    },
+  };
+}
+
 /**
  * Compose the full plan. Returns an ordered list of `{ kind, path, contents }`
  * relative to `config.targetDir`. The runner resolves the paths and writes
@@ -309,8 +410,15 @@ export function buildGitkeep() {
  */
 export async function buildPlan(config) {
   const claudeTemplate = await readFile(CLAUDE_MD_TEMPLATE_PATH, 'utf8');
+  const rootClaudeTemplate = await readFile(ROOT_CLAUDE_MD_TEMPLATE_PATH, 'utf8');
   const operatorReadmeTemplate = await readFile(OPERATOR_README_TEMPLATE_PATH, 'utf8');
-  return buildPlanFromTemplates(config, { claudeTemplate, operatorReadmeTemplate });
+  const researchCommand = await readFile(RESEARCH_COMMAND_TEMPLATE_PATH, 'utf8');
+  return buildPlanFromTemplates(config, {
+    claudeTemplate,
+    rootClaudeTemplate,
+    operatorReadmeTemplate,
+    researchCommand,
+  });
 }
 
 /**
@@ -321,6 +429,13 @@ export async function buildPlan(config) {
 export function buildPlanFromTemplates(config, templates) {
   const { paName } = config;
   const claudeMd = renderClaudeMd(templates.claudeTemplate, config);
+  // Root-CLAUDE.md is a short pointer to the full agent file. Falling
+  // back to the agent file when the pointer template is absent keeps
+  // pure-plan tests that only pass `claudeTemplate` working, while the
+  // real buildPlan() path always supplies both.
+  const rootClaudeMd = templates.rootClaudeTemplate
+    ? renderRootClaudeMd(templates.rootClaudeTemplate, config)
+    : claudeMd;
   const readmeMd = renderOperatorReadme(templates.operatorReadmeTemplate, config);
   const pkg = buildOperatorPackageJson(config);
   const gitignore = buildGitignore();
@@ -348,17 +463,36 @@ export function buildPlanFromTemplates(config, templates) {
     'projects',
     'schedules',
     '.vault',
+    '.claude',
+    '.claude/commands',
   ];
 
   const plan = [];
   for (const d of dirs) plan.push({ kind: 'dir', path: d });
 
-  plan.push({ kind: 'file', path: 'CLAUDE.md', contents: claudeMd });
+  plan.push({ kind: 'file', path: 'CLAUDE.md', contents: rootClaudeMd });
   plan.push({ kind: 'file', path: 'README.md', contents: readmeMd });
   plan.push({ kind: 'json', path: 'package.json', contents: pkg });
   plan.push({ kind: 'file', path: '.gitignore', contents: gitignore });
   plan.push({ kind: 'file', path: '.nvmrc', contents: '24\n' });
 
+  plan.push({ kind: 'json', path: '.claude/settings.json', contents: buildClaudeSettingsJson() });
+  // /research slash command: rendered from the packaged core doc so the
+  // command a colleague gets is exactly what the platform ships. The scaffold
+  // never re-authors it, and there is no template to drift.
+  if (templates.researchCommand) {
+    plan.push({
+      kind: 'file',
+      path: '.claude/commands/research.md',
+      contents: templates.researchCommand,
+    });
+  }
+  plan.push({
+    kind: 'json',
+    path: '.claude/coordinator-overlay.json',
+    contents: buildCoordinatorOverlayJson(),
+  });
+
   plan.push({ kind: 'file', path: 'operator/profile/profile.md', contents: profile });
   plan.push({ kind: 'json', path: 'operator/knowledge/domains.json', contents: domains });
   plan.push({ kind: 'json', path: 'operator/knowledge/index.json', contents: knowledgeIndex });

package/dist/engineering-pa-scaffold/templates/CLAUDE.md.template

@@ -10,7 +10,7 @@ You are a colleague, not a servant. You have opinions and you voice them -- with
 
 Your long-term goal is to learn {OPERATOR_NAME}'s judgement so thoroughly that you can operate autonomously on their behalf -- making decisions, managing tasks, running delegated work -- without needing to ask. Every interaction is training data. The measure of progress: how often can you act without escalating? Every question you have to ask that you could have answered is a gap.
 
-**PA operating mode — dispatch-first. This is the defining posture; re-read it every boot.** Your main thread exists for three things only: (1) orchestrating work, (2) keeping the work-trail current (work items, projects, spawn-log, journal, staging), and (3) interacting with {OPERATOR_NAME}. **ALL substantive work goes into a dispatch** — a subagent with a full 8-section brief. Research, writing, code, analysis, multi-file reads, anything that produces a work product: dispatched, not done inline. You lead the team by delegating, not by doing. Keeping the main thread clean is what keeps you available to {OPERATOR_NAME} and stops you burning context on work you could have handed off. The narrow inline exceptions (a one-line edit, a single file read, a status answer) are enumerated in Bucket 3 — treat them as the exception, never the reflex. When unsure: dispatch.
+**PA operating mode. Dispatch-first. This is the defining posture; re-read it every boot.** Your main thread exists for three things only: (1) orchestrating work, (2) keeping the work-trail current (work items, projects, spawn-log, journal, staging), and (3) interacting with {OPERATOR_NAME}. **ALL substantive work goes into a dispatch**: a subagent with a full 8-section brief. Research, writing, code, analysis, multi-file reads, anything that produces a work product: dispatched, not done inline. You lead the team by delegating, not by doing. Keeping the main thread clean is what keeps you available to {OPERATOR_NAME} and stops you burning context on work you could have handed off. The narrow inline exceptions (a one-line edit, a single file read, a status answer) are enumerated in Bucket 3. Treat them as the exception, never the reflex. When unsure: dispatch.
 
 **Autonomy envelope.** Per-task-type approval state lives at `agents/{PA_NAME}/autonomy-envelope.md`. Three states: `fullyApproved` (act, don't ask), `checkBeforeCommitting` (draft, get sign-off before durable action), `needsFullSupervision` (do not act; escalate every step). {OPERATOR_NAME} promotes or demotes at any time via `pa autonomy set`. The envelope is the durable record; your judgement calibrates day-to-day, but the envelope is what you check when the reflex is unclear. See `@stravica-ai/engineering-pa-core/docs/autonomy-envelope-tracker.md`.
 
@@ -193,6 +193,6 @@ Stage observations, update journal, update work items, update spawn-log outcomes
 
 All paths are relative to the operator repo root. Resolve via `.session/environment.json:workingDirectory.projectRoot` or a `*_ROOT` env var, never hard-code absolutes.
 
-Symbolic `@stravica-ai/engineering-pa-core/<subpath>` references resolve on disk to `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-core/<subpath>` — the internal packages ship bundled inside the wrapper package, not under their own names in `node_modules`.
+Symbolic `@stravica-ai/engineering-pa-core/<subpath>` references resolve on disk to `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-core/<subpath>`. The internal packages ship bundled inside the wrapper package, not under their own names in `node_modules`.
 
 <!-- OPERATOR: add any operator-specific paths that are frequently referenced (a vault path, a scratchpad convention, an integration credentials store). -->

package/dist/engineering-pa-scaffold/templates/operator-README.md.template

@@ -1,8 +1,8 @@
-# {PA_NAME} — operator repo
+# {PA_NAME}: operator repo
 
 Personal-assistant instance for {OPERATOR_NAME}, scaffolded with `pa-init`.
 
-This repo holds **only operator content** — your profile, knowledge, work items,
+This repo holds **only operator content**: your profile, knowledge, work items,
 projects, agent run state, schedules, and secrets. The PA platform code is
 supplied by the `@stravica-ai/digital-operator-pa` npm package; you never edit it in
 place.
@@ -17,7 +17,7 @@ place.
 │   ├── profile/              # operator profile (distilled over time)
 │   ├── knowledge/            # domain-organised knowledge tree
 │   └── extensions/           # operator-private extensions (Phase 2+)
-├── agents/{PA_NAME}/         # PA run folder — journal, staging, spawn-log
+├── agents/{PA_NAME}/         # PA run folder: journal, staging, spawn-log
 ├── work/                     # work items (one JSON per item)
 ├── projects/                 # projects (one folder per project)
 ├── schedules/                # scheduled-task definitions
@@ -28,7 +28,7 @@ place.
 
 ```bash
 pnpm install
-pnpm status            # alias for `pa status` — boot-time sanity check
+pnpm status            # alias for `pa status`, a boot-time sanity check
 ```
 
 Then launch your PA via Claude Code in this repo; it reads `CLAUDE.md`

package/dist/engineering-pa-scaffold/templates/root-CLAUDE.md.template

@@ -0,0 +1,13 @@
+# {PA_NAME}
+
+Personal assistant platform instance for {OPERATOR_NAME}. See `agents/{PA_NAME}/CLAUDE.md` for the full operating instructions. That file is the source of truth for how {PA_NAME} works and is the one Claude Code loads when you start a session from the agent directory.
+
+## Quick reference
+
+- Work items: `work/w-YYYY-MM-DD-NNN.json`
+- Projects: `projects/{id}/project.json`
+- Operator content: `operator/`
+- Agent run folder: `agents/{PA_NAME}/`
+- Platform package: installed as an npm dependency (`@stravica-ai/digital-operator-pa`); invoke tooling via `pnpm exec <bin>` (`pa`, `desk`, `secrets`, `distill`, etc.)
+- Workspace: `pnpm exec pa workspace start` then http://localhost:4200
+- Onboarding guide: `node_modules/@stravica-ai/digital-operator-pa/docs/onboarding-solo.md`

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

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Home — Dave</title>
+<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>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
@@ -503,11 +503,11 @@
   <!-- ═════════ SPARSE / FRESH FORK LAYOUT ═════════ -->
   <div class="sparse-layout">
     <div class="hero">
-      <div class="logo">D</div>
+      <div class="logo">PA</div>
       <h1>Welcome. Your workspace is empty.</h1>
-      <p>Dave is your personal assistant — a learned, on-repo AI colleague that tracks your projects, runs your team of sub-agents, and gets sharper the more you talk to it. There's nothing here yet because nothing's been set up. That takes about five minutes.</p>
+      <p>Your PA is a learned, on-repo AI colleague that tracks your projects, runs your team of sub-agents, and gets sharper the more you talk to it. There's nothing here yet because nothing's been set up. That takes about five minutes.</p>
       <a class="cta" href="/onboarding.html" target="_top">Start onboarding →</a>
-      <a class="cta secondary" href="https://github.com/Stravica/dave" target="_blank" rel="noopener">Read the docs</a>
+      <a class="cta secondary" href="https://github.com/Stravica/digital-operator-pa" target="_blank" rel="noopener">Read the docs</a>
     </div>
 
     <div class="next-steps">
@@ -521,7 +521,7 @@
       <div class="step">
         <div class="idx">02 ○</div>
         <div>
-          <div class="title">Tell Dave who you are <a class="go" href="/onboarding.html" target="_top">go →</a></div>
+          <div class="title">Tell your PA who you are <a class="go" href="/onboarding.html" target="_top">go →</a></div>
           <div class="desc">Name, role, skills, purpose. Five fields, two minutes. This populates your profile and configures your PA.</div>
         </div>
       </div>
@@ -529,14 +529,14 @@
         <div class="idx">03 ○</div>
         <div>
           <div class="title">Name your PA <a class="go" href="/onboarding.html" target="_top">go →</a></div>
-          <div class="desc">The assistant has a name and a personality. Mine is Dave. Yours could be Jeeves, Max, Hal, whatever fits.</div>
+          <div class="desc">The assistant has a name and a personality. Yours could be Jeeves, Max, Hal, Alex, whatever fits.</div>
         </div>
       </div>
       <div class="step">
         <div class="idx">04 ○</div>
         <div>
           <div class="title">Open your first project <a class="go" onclick="nav('/projects.html')">go →</a></div>
-          <div class="desc">Once onboarded, create a project. Dave will track it, open work items against it, and route dispatches to specialists.</div>
+          <div class="desc">Once onboarded, create a project. Your PA will track it, open work items against it, and route dispatches to specialists.</div>
         </div>
       </div>
       <div class="step">

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

@@ -3,7 +3,7 @@
 <head>
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
-<title>Welcome to Dave</title>
+<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>
 <link rel="stylesheet" href="/core/tools/workspace/app/assets/theme.css">
 <script src="/core/tools/workspace/app/assets/theme.js" defer></script>
@@ -58,7 +58,7 @@
 <div id="global-banner"></div>
 <div class="onboard-card">
   <div class="logo">D</div>
-  <h1>Welcome to Dave</h1>
+  <h1>Welcome to your PA</h1>
   <p class="description">Let's set up your personal assistant. This takes about a minute.</p>
   <form id="onboard-form" autocomplete="off">
     <div class="form-group">
@@ -84,7 +84,7 @@
     <hr class="divider">
     <div class="form-group">
       <label class="form-label">Name your PA <span class="required">*</span></label>
-      <input type="text" id="pa-name" name="paName" required value="Dave" placeholder="e.g. Alex, Sam, Max">
+      <input type="text" id="pa-name" name="paName" required placeholder="e.g. Alex, Sam, Max">
     </div>
     <div class="form-group">
       <label class="form-label">Communication style</label>
@@ -567,7 +567,7 @@
       role: document.getElementById('owner-role').value.trim(),
       skills: document.getElementById('owner-skills').value.trim(),
       purpose: document.getElementById('owner-goals').value.trim(),
-      paName: document.getElementById('pa-name').value.trim() || 'Dave',
+      paName: document.getElementById('pa-name').value.trim(),
       communicationStyle: cs === 'custom' ? document.getElementById('custom-style').value.trim() || 'custom' : cs,
       taskManagement: tt === 'other' ? document.getElementById('other-tracker').value.trim() || 'other' : tt,
     };

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

@@ -37,7 +37,7 @@ export function handleApi(req, res, url, repoRoot, deps = {}) {
   // changes) instead of silently skipping.
   if (method === 'GET' && pathname === '/__api/identity') {
     sendJson(res, 200, {
-      server: 'dave-workspace',
+      server: 'digital-operator-pa-workspace',
       repoRoot: repoRoot,
       pid: process.pid,
       startedAt: SERVER_STARTED_AT,

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

@@ -644,7 +644,7 @@ if (isMainModule) (async function () {
     if (!IS_LOOPBACK_BIND) {
       warnAlways('[workspace] WARNING: bound to ' + host + ':' + port + ' — reachable from other hosts. Set WORKSPACE_HOST=127.0.0.1 or omit --host to restore loopback-only.');
     }
-    log('[workspace] Dave Workspace running at ' + url + ' (bind ' + host + ')');
+    log('[workspace] Workspace running at ' + url + ' (bind ' + host + ')');
     log('[workspace] Serving from: ' + REPO_ROOT);
     if (EXT_DIR) log('[workspace] Extensions: ' + EXT_DIR.replace(REPO_ROOT + '/', ''));
     log('[workspace] Idle timeout: ' + (noTimeout ? 'disabled (persistent)' : timeoutMinutes + ' minutes'));

package/docs/installing.md

@@ -0,0 +1,78 @@
+# Installing `@stravica-ai/digital-operator-pa`
+
+`@stravica-ai/digital-operator-pa` is published to the **public npm registry**
+(`registry.npmjs.org`). It is a public package, so **no registry authentication is
+required to install it**: a plain `pnpm add` works on any host.
+
+## Prerequisites
+
+- **Node.js 24+** (current active LTS).
+- **pnpm 10+** (the wrapper is tested with pnpm but `npm`/`yarn` also work).
+
+No PAT, `~/.npmrc`, or org-membership step is needed for install. (The `@stravica-ai`
+scope resolves to npmjs.org by default; you only need an `~/.npmrc` entry if you have
+previously pointed that scope somewhere else.)
+
+## Step 1: install in a project
+
+In your operator-repo (or a fresh directory):
+
+```sh
+pnpm add @stravica-ai/digital-operator-pa
+```
+
+Smoke-test:
+
+```sh
+pnpm exec pa launch --help     # exit 0
+pnpm exec pa --help            # exit 0
+pnpm exec desk --help          # exit 0
+```
+
+## What the wrapper ships
+
+`@stravica-ai/digital-operator-pa` is a **single-bundled** package. One install gives
+you:
+
+- All operator-facing bins: `pa`, `desk`, `launch`, `estate-sync`, `sync`, `secrets`,
+  `scheduler`, `smoke`, `distill`, `memory-sync`, `migrate-inspect`, `pa-init`,
+  `slice`, `research`, `pa-coordinator-hook`.
+- All internal platform code (core spine, runbook validator, workspace server,
+  scaffold templates, role packs, optional core-extensions), bundled inside
+  the tarball at `dist/<package-name>/`. The internal packages stay
+  `private: true` in the monorepo and are never individually published.
+
+## Troubleshooting
+
+- **`404 Not Found`**: usually the `@stravica-ai` scope is routed to the wrong
+  registry. Confirm you do **not** have a stale
+  `@stravica-ai:registry=https://npm.pkg.github.com` line in your `~/.npmrc`; the
+  scope should resolve to `https://registry.npmjs.org` (the default). Older setups
+  pointed this scope at GitHub Packages. Remove that line.
+- **`Could not resolve dependency` for `@stravica-ai/engineering-pa-core`**
+  (or any other `engineering-pa-*` internal). The wrapper bundles those
+  internally and does not declare them as runtime deps; you should never
+  see this in normal use. If it appears, the wrapper's `dist/` was likely
+  stripped during install. Re-run `pnpm add @stravica-ai/digital-operator-pa`
+  with `--force`.
+
+> **Historical note.** The predecessor package `@stravica/engineering-pa` lived on
+> **GitHub Packages** and needed a `read:packages` PAT. The current
+> `@stravica-ai/digital-operator-pa` bundle is public on npmjs.org, so that auth step
+> no longer applies.
+
+## Release pipeline (for maintainers)
+
+Publishing is **manual**, from `packages/engineering-pa`, and targets npmjs.org via the
+package's `publishConfig` (`registry.npmjs.org`, `access: public`):
+
+```sh
+cd packages/engineering-pa
+pnpm publish            # runs the prepack build.mjs, then publishes the bundled tarball
+```
+
+`ci.yml`'s `dry-publish` job runs `pnpm dry-publish` (`build.mjs` + `pnpm publish
+--dry-run`) on every push to prove the pack/publish mechanics, and a follow-up job
+re-installs the packed tarball into a clean consumer directory and exercises the bins.
+The actual publish is run by a maintainer with npmjs publish rights once CI is green
+on `main`.

package/docs/onboarding-solo.md

@@ -0,0 +1,111 @@
+# Onboarding: solo PA
+
+Ten minutes end to end. This guide takes you from an empty directory to a working single-person PA on your own laptop, running under your own Claude Code subscription.
+
+## 0. Prerequisites
+
+You need Node.js 24 or newer, pnpm, git, and the Claude Code CLI signed in to your own subscription. macOS example:
+
+```sh
+brew install node@24 pnpm git
+sudo npm install -g @anthropic-ai/claude-code   # or: curl -fsSL https://claude.ai/install.sh | sh
+claude                                          # follow the interactive login, then Ctrl-C once you see the prompt
+```
+
+Linux and WSL are equivalent. Install Node 24 through your platform's normal channel.
+
+## 1. Scaffold the PA
+
+```sh
+mkdir ~/pa-bootstrap && cd ~/pa-bootstrap
+pnpm init -y
+pnpm add @stravica-ai/digital-operator-pa
+pnpm exec pa-init --mode=solo --name=<pa-name> --operator=<your-name> \
+  --target=$HOME/<pa-name>-instance --non-interactive
+cd $HOME/<pa-name>-instance
+pnpm install
+git add -A && git commit -m "scaffold"
+```
+
+Pick a `<pa-name>` in lowercase kebab-case (`alex`, `sam`, `hal-9000`). It becomes the agent directory (`agents/<pa-name>/`) and shows up in every log line.
+
+## 2. Sanity-check the install
+
+```sh
+pnpm exec pa environment
+pnpm exec pa status
+pnpm exec pa knowledge context     # first line: library.mode = simple  (variant token: simple)
+```
+
+`pa environment` populates `.session/environment.json` with the machine's Node, pnpm, git, and workspace state. `pa status` prints the installed platform version. `pa knowledge context` confirms the local library is in SIMPLE mode (no remote services).
+
+## 3. Start the workspace
+
+```sh
+pnpm exec pa workspace start       # opens http://localhost:4200
+```
+
+The workspace serves a viewer, a home page, and an onboarding form. Long notes from your PA land here rather than in chat.
+
+## 4. Start your first session
+
+```sh
+pnpm exec pa session
+```
+
+That changes directory into `agents/<pa-name>/` and execs `claude`. Your PA reads its own `CLAUDE.md`, the operator profile, and the autonomy envelope, then greets you.
+
+## 5. First project and first work item
+
+Inside the session, ask your PA to open a project. It will call `pa project create` and `pa work create` on your behalf. If you would rather run them yourself:
+
+```sh
+pnpm exec pa project create my-first-project --name "..." --category chore
+pnpm exec pa work create --title "..."
+pnpm exec desk overview            # read-only view of what is in flight
+```
+
+## What you get
+
+- A generic personal-assistant operating model rendered into your own `agents/<pa-name>/CLAUDE.md` (with a short root pointer at `CLAUDE.md`). Seven buckets, dispatch-first, autonomy envelope.
+- The `pa` CLI: `status`, `session`, `workspace`, `project`, `work`, `knowledge`, `research`, `autonomy`, `environment`, `agent`, `lint`, `launch`, `gsc`.
+- The read-only `desk` CLI: overview, today, projects, work.
+- A local workspace server on `http://localhost:4200`.
+- A SIMPLE-mode local knowledge library: `pa knowledge search / related / domain / orphans / path / context`, seeded with the five base domains.
+- Self-learning loop primitives: `agents/<pa-name>/staging/`, `journal.md`, `next-session.md`, `spawn-log.json`, autonomy envelope, and the Librarian distillation sweep via `pnpm exec distill run`.
+- The `research` CLI with the light / normal / deep session store persisted under `.cache/research/`.
+- Scheduler (cron on Linux, launchd on macOS): `pnpm exec scheduler --help`.
+- Secrets vault (SOPS + age) if you opt in: `pnpm exec secrets --help`.
+- `.claude/settings.json` with the `pa-coordinator-hook` wired in as a `PreToolUse` hook (inert until you export `PA_COORDINATOR_MODE=1`) and `deep-research` denied at the permission layer (the CLAUDE.md points you at the `/research` verb instead, which persists a session and promotes durable answers back into your library).
+- The `/research` slash command scaffolded to `.claude/commands/research.md`, rendered from the bundled core doc, so the verb is directly available in your PA's Claude Code session.
+
+## What is not included in solo mode
+
+- **`SessionStart` boot-context hook.** In some estates a `SessionStart` hook injects a live workState block (a desk overview tail, spawn-log tail, distillation health) at the top of every session. That hook is not in this package. If you want it, write your own `SessionStart` hook in `.claude/settings.json`. The coordinator-hook doc at `node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-cli/docs/coordinator-hook.md` shows the settings.json shape.
+- **Team modes.** `pa-init --mode=lead` and `--mode=member` exit with "not implemented". The SIMPLE-mode local library is single-operator by design. When team mode lands, the migration will be a fresh install with a knowledge / extension / vault import, not an in-place upgrade of a solo install.
+- **Remote knowledge library.** The `remote` library mode requires a service on a persistent host, an age keypair, and a tunnel. Solo mode stays SIMPLE and runs entirely on your one laptop.
+- **HQ-specialised roles.** The bundled role set is the core seven (`pa`, `agent-ops`, `dispatch-briefer`, `librarian`, `system-admin`, `tool-developer`, `writer`) plus `product-engineer` from the engineering types pack. Other tier-ladder roles (`web-developer`, `rcf-lite-engineer`, `rcf-engineer`) and estate-specific extensions like `site-cloner`, `seo-*`, `infographic-designer`, `linkedin-writer` are not shipped.
+- **Content publishing tool, Cloudflare / GSC live integrations, cross-host memory sync.** Out of scope for solo. Those all assume a multi-machine estate.
+
+## Known first-run friction
+
+- **`LIBRARY_KNOWLEDGE_EXTRA_ROOTS`.** If this env var is set in your shell (unlikely on a fresh laptop), unset it before running `pa knowledge`. Set, it silently merges other knowledge trees into your local graph.
+- **`pa workspace stop`** on a machine that had the workspace daemon installed refuses and points you at the `launchctl unload` or `systemctl --user stop` command in its own error message. `pa workspace restart` is the intended path.
+- **`pa work create --status planned` is ignored on create.** The item lands as `draft`. Use `pa work status <id> planned` as a second step.
+- **Start sessions via `pnpm exec pa session`.** The coordinator hook (`pa-coordinator-hook`) is wired into `.claude/settings.json` as a bare bin name. `pnpm exec pa session` prepends `node_modules/.bin` to `PATH` before launching `claude`, which resolves the hook cleanly. If you launch `claude` directly from `agents/<pa-name>/` without `pnpm exec` in front, the hook resolves to nothing (silent no-op, safe but inert). Prefer the `pa session` entry point, or alias it as your PA name.
+- **CLAUDE.md updates.** Every `pnpm update @stravica-ai/digital-operator-pa` may bring platform operating-model changes into the CLAUDE.md template. The scaffold rendered your CLAUDE.md once, at `pa-init` time; subsequent template updates do not overwrite your file. Pin the package version and read the CHANGELOG before you upgrade.
+
+## Where things live
+
+| What | Where |
+|---|---|
+| Root pointer | `CLAUDE.md` |
+| Full operating instructions | `agents/<pa-name>/CLAUDE.md` |
+| Operator profile | `operator/profile/profile.md` |
+| Preferences | `operator/config/preferences.json` |
+| Autonomy envelope | `agents/<pa-name>/autonomy-envelope.md` |
+| Work items | `work/w-YYYY-MM-DD-<author>-NNN.json` (<author> is your PA name, e.g. `w-2026-09-16-alex-001`) |
+| Projects | `projects/{id}/project.json` |
+| Session environment | `.session/environment.json` |
+| Claude Code settings | `.claude/settings.json` |
+| Coordinator-hook overlay | `.claude/coordinator-overlay.json` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.39",
+  "version": "0.1.40",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",
@@ -30,6 +30,7 @@
     "index.mjs",
     "bin",
     "dist",
+    "docs",
     "templates",
     "README.md",
     "LICENSE"