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

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

@@ -15,7 +15,7 @@ import { main as runMigrateInspect } from '../../../engineering-pa-migrate-inspe
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-const USAGE = `pa — operator personal-assistant CLI
+const USAGE = `pa - Digital Operator CLI
 
 Usage:
   pa session                  Start a PA session — chdir to agent dir, exec \`claude\`

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

@@ -18,8 +18,8 @@ import { existsSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 
-import { runSync } from './run.mjs';
 import { defaultRunner } from './runner.mjs';
+import { runSyncWithStatus } from './status-record.mjs';
 
 const USAGE = `estate-sync — single-writer-per-host git sync for ESTATE-NATIVE content.
 
@@ -134,7 +134,7 @@ async function route(argv) {
     await mkdir(logDir, { recursive: true });
     const runsLog = join(logDir, 'runs.jsonl');
     const lockPath = join(repoRoot, '.cache/estate-sync/.lock');
-    const code = await runSync({
+    const code = await runSyncWithStatus({
       repoRoot,
       logDir,
       runsLog,

package/dist/engineering-pa-cli/src/sync/status-record.mjs

@@ -0,0 +1,347 @@
+// estate-sync — synced end-of-pass status record.
+//
+// After every real pass, estate-sync writes a tiny per-host status file
+// at `<repoRoot>/agents/estate-sync/<paName>/<host>.json`. This path is
+// TRACKED and — critically — sits OUTSIDE every registry mount `to`
+// subtree, so estate-sync's own registry-scoped commit stages it (a
+// path inside `agents/<paName>/` would be silently excluded by the
+// mount filter and never leave the writing host). The consequence: the
+// pass's own commit + push carries every host's most recent pass
+// result into every clone. A reader on any host (e.g. the HQ boot-
+// context hook) can then flag a stuck cron on any other host at
+// session boot without ssh or a separate publisher.
+//
+// Location choice: `agents/estate-sync/` is not under any mount `to`
+// path in the current registry (`operator/registry/repos.json` mounts
+// `agents/<name>/`, one per agent, not `agents/` itself). Every host
+// therefore commits its own file directly, no per-host registry
+// change needed.
+//
+// Design notes:
+//   - Overwrite semantics: one JSON file per host, small (< 1 KB). The
+//     writer never appends; the previous pass's record is replaced.
+//   - The record is derived from the audit record estate-sync already
+//     writes to runs.jsonl (same source of truth) — so a change to the
+//     audit vocabulary is picked up here for free.
+//   - noop-locked passes DO NOT write a status record: the pass that is
+//     actually running (and holding the lock) will write its own record
+//     when it finishes, and a concurrent overwrite from a lock contender
+//     would race with it. Contenders exit silently.
+//   - The `agents/estate-sync/<paName>/` directory is created on first
+//     write. Failure to write fails silently — this is a status
+//     side-channel and must never block the sync exit code.
+//   - Callers wrap runSync via `runSyncWithStatus`, which reads the last
+//     line of runs.jsonl to derive the terminal record. This means the
+//     writer is layered ON TOP of runSync rather than braided into every
+//     one of its exit paths — the run.mjs surface stays untouched.
+//
+// Absence-of-work: a fresh file dated after `now - 6h` on every host is
+// the healthy signal; the reader flags anything older or with alertLevel
+// > 'ok'. The 6h window is chosen against the 30-minute cron cadence,
+// twelve missed ticks is loud enough to warrant a session-boot line.
+
+import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
+import { hostname as osHostname } from 'node:os';
+import { join } from 'node:path';
+
+import { runSync } from './run.mjs';
+import { revParseSha } from './git.mjs';
+
+/**
+ * Audit statuses that count as a healthy pass. Everything else
+ * (`fail-*`, unknown vocab, missing status) maps to `failed` and the
+ * reader is expected to flag it. `noop-locked` never reaches the
+ * composer (see runSyncWithStatus), but is listed here for parity so a
+ * future direct caller lands in the same place.
+ */
+const OK_AUDIT_STATUSES = new Set([
+  'ok',
+  'noop-nothing-to-do',
+  'noop-locked',
+]);
+
+const ALERT_RANK = { ok: -1, warn: 0, error: 1, 'needs-human': 2 };
+
+/**
+ * Compose the tracked status record from an audit record plus context.
+ * Pure — no clock, no filesystem. Tested directly.
+ *
+ * @param {object} input
+ * @param {object} input.audit           audit record as written to runs.jsonl
+ * @param {string} input.paName          resolved paName (e.g. 'dave')
+ * @param {string} input.host            resolved hostname (os.hostname())
+ * @param {string|null} input.headBefore HEAD sha at start of pass (or null)
+ * @param {string|null} input.headAfter  HEAD sha at end of pass (or null)
+ * @param {number} [input.pendingCount]  count of self-heal pending entries
+ * @returns {{ host:string, paName:string, finishedAt:string, status:'ok'|'failed', alertLevel:'ok'|'warn'|'error'|'needs-human', attempts:number, lastError:(string|null), headBefore:(string|null), headAfter:(string|null), pending:number, auditStatus:string }}
+ */
+export function composeStatusRecord({
+  audit,
+  paName,
+  host,
+  headBefore = null,
+  headAfter = null,
+  pendingCount = 0,
+}) {
+  const auditStatus = typeof audit?.status === 'string' ? audit.status : 'unknown';
+  const status = OK_AUDIT_STATUSES.has(auditStatus) ? 'ok' : 'failed';
+  const alertLevel = deriveAlertLevel(audit, auditStatus);
+  const attempts = deriveAttempts(audit);
+  const lastError = deriveLastError(audit);
+  return {
+    host,
+    paName,
+    finishedAt: typeof audit?.ts === 'string' ? audit.ts : '',
+    status,
+    alertLevel,
+    attempts,
+    lastError,
+    headBefore: typeof headBefore === 'string' ? headBefore : null,
+    headAfter: typeof headAfter === 'string' ? headAfter : null,
+    pending: Number.isFinite(pendingCount) ? pendingCount : 0,
+    auditStatus,
+  };
+}
+
+function deriveAlertLevel(audit, auditStatus) {
+  // Prefer the highest-ranked alert level across queued self-heal
+  // entries when the audit carries them (needs-human > error > warn).
+  if (Array.isArray(audit?.queued) && audit.queued.length > 0) {
+    let best = 'warn';
+    for (const q of audit.queued) {
+      const lvl = typeof q?.alertLevel === 'string' ? q.alertLevel : 'warn';
+      if ((ALERT_RANK[lvl] ?? -1) > (ALERT_RANK[best] ?? -1)) best = lvl;
+    }
+    return best;
+  }
+  // Otherwise map from the status vocabulary.
+  switch (auditStatus) {
+    case 'fail-rebase-needs-human':
+      return 'needs-human';
+    case 'fail-rebase':
+    case 'fail-rebase-stuck':
+    case 'fail-push':
+    case 'fail-git':
+    case 'fail-cli-bootstrap':
+      return 'error';
+    case 'fail-rebase-queued':
+      return 'warn';
+    default:
+      return 'ok';
+  }
+}
+
+function deriveAttempts(audit) {
+  if (Array.isArray(audit?.queued) && audit.queued.length > 0) {
+    let max = 0;
+    for (const q of audit.queued) {
+      const n = typeof q?.attemptCount === 'number' ? q.attemptCount : 0;
+      if (n > max) max = n;
+    }
+    return max;
+  }
+  return 0;
+}
+
+function deriveLastError(audit) {
+  const reason = audit?.reason;
+  if (typeof reason !== 'string' || reason.length === 0) return null;
+  return reason.split(/\r?\n/)[0].slice(0, 200);
+}
+
+/**
+ * Write the status record to
+ * `<repoRoot>/agents/estate-sync/<paName>/<host>.json`. Parent dirs are
+ * created; the file is fully overwritten. Returns the path written.
+ * Failure to write is thrown to the caller — callers wrap in try/catch
+ * and never block on this.
+ *
+ * @param {{ repoRoot:string, paName:string, host:string, record:object }} opts
+ * @returns {Promise<string>}
+ */
+export async function writeStatusRecord({ repoRoot, paName, host, record }) {
+  const dir = join(repoRoot, 'agents', 'estate-sync', sanitiseSegment(paName));
+  await mkdir(dir, { recursive: true });
+  const path = join(dir, `${sanitiseSegment(host)}.json`);
+  await writeFile(path, JSON.stringify(record, null, 2) + '\n');
+  return path;
+}
+
+/**
+ * Read paName from preferences.json with an optional preferences.local.json
+ * overlay (overlay wins). Returns null on any failure — the status
+ * writer is a side-channel and a missing paName just means the record
+ * is skipped, not that estate-sync itself fails.
+ *
+ * @param {string} repoRoot
+ * @returns {Promise<string|null>}
+ */
+export async function readPaName(repoRoot) {
+  const basePath = join(repoRoot, 'operator/config/preferences.json');
+  const overlayPath = join(repoRoot, 'operator/config/preferences.local.json');
+  let base = {};
+  let overlay = {};
+  try { base = JSON.parse(await readFile(basePath, 'utf8')); } catch { /* ignore */ }
+  try { overlay = JSON.parse(await readFile(overlayPath, 'utf8')); } catch { /* ignore */ }
+  const value = overlay?.paName ?? base?.paName ?? null;
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+/**
+ * `os.hostname()` with the injection seam runSync already uses for
+ * registry-scope tests. Empty results fall back to `unknown-host`.
+ */
+export function resolveHost(hostnameFn) {
+  try {
+    const h = (hostnameFn || osHostname)();
+    return typeof h === 'string' && h.length > 0 ? h : 'unknown-host';
+  } catch {
+    return 'unknown-host';
+  }
+}
+
+/**
+ * Read the last non-empty line of runs.jsonl and parse it as JSON.
+ * Returns null if the file is missing, empty, or the last line does not
+ * parse. Callers only care about the terminal record for the pass they
+ * just ran; earlier entries are irrelevant here.
+ *
+ * @param {string} runsLog
+ * @returns {Promise<object|null>}
+ */
+export async function readLastAuditRecord(runsLog) {
+  let text;
+  try {
+    text = await readFile(runsLog, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+  const lines = text.split('\n').map((s) => s.trim()).filter((s) => s.length > 0);
+  if (lines.length === 0) return null;
+  try {
+    return JSON.parse(lines[lines.length - 1]);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Count entries in the self-heal pending queue directory. Returns 0 on
+ * missing dir. Directory entries starting with `.` (e.g. `.gitkeep`)
+ * are ignored, and sidecar `.json` files are counted alongside their
+ * data twins as a single pending — we count the DATA files only, i.e.
+ * entries whose name does not end in `.json`.
+ *
+ * @param {string} pendingDir
+ * @returns {Promise<number>}
+ */
+export async function countPending(pendingDir) {
+  let entries;
+  try {
+    entries = await readdir(pendingDir);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return 0;
+    return 0;
+  }
+  return entries.filter((n) => !n.startsWith('.') && !n.endsWith('.json')).length;
+}
+
+/**
+ * Wrap `runSync` so that after each real (non-dry-run) pass the terminal
+ * audit record is mirrored to a tracked per-host status file. Signature
+ * is a superset of runSync — every existing runSync caller keeps working
+ * unchanged when swapped for this wrapper.
+ *
+ * Injection seams (all test-only; production defaults from prefs/env):
+ *   - `paName`      : override the paName that would otherwise come from
+ *                     preferences.json (used by tests and by callers who
+ *                     already resolved it).
+ *   - `hostnameFn`  : function returning the host string (already an
+ *                     injection seam on runSync itself, for scope tests).
+ *   - `statusEnabled: false` disables the status write entirely (kept as
+ *                     a defensive off-switch; not user-facing).
+ *
+ * @param {object} opts  every field runSync accepts, plus `paName`, `statusEnabled`.
+ * @returns {Promise<number>}
+ */
+export async function runSyncWithStatus(opts) {
+  const {
+    repoRoot,
+    runsLog,
+    runner,
+    dryRun = false,
+    hostnameFn,
+    paName: paNameOverride,
+    statusEnabled = true,
+    stderr = process.stderr,
+  } = opts;
+
+  // Resolve paName + host early; if paName is unresolvable we skip the
+  // status write but still run the sync. Host is safe-defaulted.
+  const paName = statusEnabled
+    ? (paNameOverride || (repoRoot ? await readPaName(repoRoot) : null))
+    : null;
+  const host = resolveHost(hostnameFn);
+
+  // Capture HEAD BEFORE the pass — best-effort. A detached HEAD or an
+  // uninitialised repo yields null; the reader treats null as "unknown"
+  // and does not flag on it.
+  let headBefore = null;
+  if (paName && !dryRun && runner) {
+    headBefore = await safeHeadSha(runner, repoRoot);
+  }
+
+  const code = await runSync(opts);
+
+  // Skip status write for dry-run (nothing durable to report), for
+  // missing paName (nowhere to write), and for lock-contended passes
+  // (the pass holding the lock writes its own record; a contender would
+  // race).
+  if (!paName || dryRun) return code;
+
+  try {
+    const audit = await readLastAuditRecord(runsLog);
+    if (!audit) return code;
+    if (audit.status === 'noop-locked') return code;
+
+    const headAfter = await safeHeadSha(runner, repoRoot);
+    const pendingCount = await countPending(join(repoRoot, '.cache/estate-sync/pending'));
+    const record = composeStatusRecord({
+      audit,
+      paName,
+      host,
+      headBefore,
+      headAfter,
+      pendingCount,
+    });
+    await writeStatusRecord({ repoRoot, paName, host, record });
+  } catch (err) {
+    // Never block the sync exit code on a status-write failure. Log
+    // one line so the seam is visible in the cron output.
+    stderr.write(`[estate-sync] warning: failed to write synced status record: ${err && err.message ? err.message : err}\n`);
+  }
+
+  return code;
+}
+
+async function safeHeadSha(runner, repoRoot) {
+  try {
+    const res = await revParseSha(runner, { cwd: repoRoot, ref: 'HEAD' });
+    if (res && res.code === 0 && typeof res.sha === 'string' && res.sha.length > 0) {
+      return res.sha;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function sanitiseSegment(name) {
+  // File-system-safe path segment: keep alnum, dot, dash, underscore.
+  // Anything else collapses to `-`. Empty result falls back to
+  // `unknown`. Prevents a hostname or paName carrying a path separator
+  // from writing outside the intended directory.
+  const cleaned = String(name || '').replace(/[^A-Za-z0-9._-]/g, '-');
+  return cleaned.length > 0 ? cleaned : 'unknown';
+}

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

@@ -0,0 +1,119 @@
+---
+description: First-session onboarding walkthrough — verifies the install, offers optional setup (Atlassian, workspace, alias, profile intake), and marks each step complete.
+when_to_use: >-
+  Run on the operator's first session in a fresh scaffolded PA instance. Also
+  re-runnable any time later: every step is idempotent and reads the current
+  state from `.session/onboarding.json`, so `/onboard` picks up where it left off
+  and skips steps already marked done.
+allowed-tools: Bash, Read, Write, Edit
+argument-hint: (no arguments)
+context: inline
+---
+
+# /onboard — first-session walkthrough
+
+You are running the onboarding walkthrough for a freshly scaffolded PA instance.
+The scaffold has already run `pnpm install` and `pa status` at scaffold time, so
+the install is proven working. Your job is the second half: verify the runtime,
+offer the optional setup steps the guide deliberately left for you, and hand
+over. Every step below is idempotent. State lives in `.session/onboarding.json`
+so re-running `/onboard` picks up where it left off.
+
+## State file
+
+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"
+  },
+  "completedAt": null | "<iso>"
+}
+```
+
+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
+offer to re-run a specific step by name. Do not walk the whole flow again.
+
+## Flow
+
+Walk the pending steps in this order. After each, write the state file back
+with the step marked `done` or `skipped`. Keep exchanges short: one question,
+one answer, move on.
+
+### 1. verifyRuntime
+
+Run `pnpm exec pa environment` and read the resulting `.session/environment.json`.
+Report Node version, pnpm version, git version, and workspace state in one line.
+If Node is below 24 or pnpm below 9, name the gap and stop; the operator needs
+to upgrade before continuing.
+
+### 2. verifyVersion
+
+Run `pnpm exec pa status` and capture the installed package version. Compare
+against `npm view @stravica-ai/digital-operator-pa version`. On a match, mark
+done and move on. On a mismatch, print both versions and the recovery line
+(`pnpm install` inside the instance) — do not attempt the fix yourself.
+
+### 3. profileIntake
+
+Ask the operator four questions in one turn:
+
+1. Your name and how you prefer to be addressed?
+2. Your role (job title, or "solo", or a short description)?
+3. Communication style you want (formal, casual, direct, verbose)?
+4. Any topic areas the PA should be strong on from day one?
+
+Take the answers and write them into `operator/profile/profile.md`, overwriting
+the placeholder. Keep it a short human-readable paragraph plus a bulleted list
+of preferences. Do not invent fields the operator did not name.
+
+### 4. aliasOffer
+
+The colleague probably has not aliased the PA yet. Offer one line and let them
+decide whether to run it. The exact command is:
+
+```
+echo "alias <pa-name>='cd <target-dir> && pnpm exec pa session'" >> ~/.zshrc && source ~/.zshrc
+```
+
+Substitute `<pa-name>` from `operator/config/preferences.json` and
+`<target-dir>` from `process.cwd()`. If the operator says yes, print the exact
+line to run; do not run it for them (their shell rc is not our file to write).
+
+### 5. workspaceOffer
+
+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.
+
+### 6. atlassianOffer
+
+Ask if they use Jira or Confluence. On no, mark skipped. On yes, walk them
+through:
+
+```
+pnpm exec secrets set JIRA_DOMAIN <site>          # for <site>.atlassian.net
+pnpm exec secrets set JIRA_EMAIL   <email>
+pnpm exec secrets set JIRA_API_TOKEN <paste-token>  # id.atlassian.com/manage-profile/security/api-tokens
+```
+
+The vault self-initialises on the first `secrets set`. After the three sets,
+run `pnpm exec jira auth` and `pnpm exec confluence auth` and report the
+identity each returns.
+
+## Completion
+
+When every step is done or skipped, write `completedAt` and tell the operator
+onboarding is done. Give them one line: "You are ready. Ask me anything, or
+say `bring me up to speed` and I will run the standard session-boot briefing."

package/dist/engineering-pa-core/roles/pa/definition.md

@@ -1,6 +1,6 @@
-# Personal Assistant -- Role Definition
+# PA (Digital Operator) -- Role Definition
 
-The Personal Assistant (PA) is the operator's single point of contact. It answers questions, manages tasks, delegates work to specialist roles, and continuously learns the operator's preferences, judgement, and communication style. Everything the operator needs flows through the PA.
+The PA (Digital Operator) is the operator's single point of contact. It answers questions, manages tasks, delegates work to specialist roles, and continuously learns the operator's preferences, judgement, and communication style. Everything the operator needs flows through the PA.
 
 The PA is domain-agnostic. It works for a developer, a marketer, a manager, a student -- anyone. The operator's profile and stated purpose shape the PA's behaviour; the role definition does not constrain the domain.
 

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

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
 export const name = './';
-export const version = '0.1.1';
+export const version = '0.1.2';
 export const modes = ['solo', 'lead', 'member'];
 
 /**

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

@@ -16,7 +16,7 @@ import { parseArgs } from 'node:util';
 import { runInit } from './commands/init.mjs';
 import { runInitWorkspaceExtension } from './commands/init-workspace-extension.mjs';
 
-const USAGE = `pa-init: scaffold a new personal-assistant operator repo, or a single workspace extension.
+const USAGE = `pa-init: scaffold a new Digital Operator instance, or a single workspace extension.
 
 Usage:
   pa-init --mode=solo [--name=PA_NAME] [--target=DIR] [--non-interactive] [--operator=NAME] [--purpose=TEXT]

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

@@ -114,11 +114,15 @@ function writeNextStepMessage(config) {
   const { paName, targetDir } = config;
   const lines = [
     '',
-    'Next step - start your PA:',
+    'Next step, start your PA:',
     '',
     `  cd ${targetDir}`,
     '  pnpm exec pa session',
     '',
+    `Inside the session, type \`/onboard\`. ${paName} walks you through the`,
+    'remaining verification and optional setup (runtime check, version check,',
+    'profile intake, alias, workspace, Atlassian). Every step is idempotent.',
+    '',
     'Optional: add a one-word shell alias so you can start a session from anywhere.',
     'Add this line to ~/.zshrc (zsh) or ~/.bashrc (bash), then reload the shell:',
     '',

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

@@ -129,6 +129,25 @@ const RESEARCH_COMMAND_CANDIDATES = [
 export const RESEARCH_COMMAND_TEMPLATE_PATH =
   RESEARCH_COMMAND_CANDIDATES.find((p) => existsSync(p)) ?? RESEARCH_COMMAND_CANDIDATES[0];
 
+/**
+ * Path to the `/onboard` slash-command doc, resolved out of the bundled
+ * engineering-pa-core package. Same two-candidate pattern as the research
+ * command so the scaffold reads the file at plan time and the copy the
+ * colleague gets never drifts from the packaged canonical.
+ *
+ * Rationale: the onboarding guide was rewritten in 0.1.45 to hand every
+ * verification and setup step past the single scaffold command to the PA
+ * itself. `/onboard` is the entry point; the seeded `.session/onboarding.json`
+ * state file is its scratchpad.
+ */
+const ONBOARD_COMMAND_CANDIDATES = [
+  resolve(__dirname, '..', '..', 'engineering-pa-core', 'docs', 'commands', 'onboard.md'),
+  resolve(__dirname, '..', '..', 'core', 'docs', 'commands', 'onboard.md'),
+];
+
+export const ONBOARD_COMMAND_TEMPLATE_PATH =
+  ONBOARD_COMMAND_CANDIDATES.find((p) => existsSync(p)) ?? ONBOARD_COMMAND_CANDIDATES[0];
+
 /**
  * Path to the bundled `workspace-extensions.md` PA-facing knowledge doc,
  * resolved out of the packaged core. Two candidates so this works in both
@@ -186,7 +205,7 @@ export const BASE_DOMAINS = [
 ];
 
 const DEFAULT_PURPOSE =
-  'Be a self-learning personal assistant who learns the operator deeply over time and acts on their behalf with increasing autonomy.';
+  'Be a self-learning Digital Operator who learns the operator deeply over time and acts on their behalf with increasing autonomy.';
 
 const DEFAULT_COMMUNICATION_STYLE =
   'Casual, direct, no filler. Voice opinions with reasoning. Light humour welcome; obsequiousness is not.';
@@ -262,7 +281,7 @@ export function buildOperatorPackageJson(config) {
     version: '0.0.1',
     private: true,
     type: 'module',
-    description: `Personal-assistant operator repo for ${config.operatorName} (PA: ${config.paName}).`,
+    description: `Digital Operator repo for ${config.operatorName} (PA: ${config.paName}).`,
     engines: { node: '>=24' },
     dependencies: {
       '@stravica-ai/digital-operator-pa': config.pkgVersion,
@@ -493,13 +512,53 @@ export function buildNextSessionMd(config) {
   return [
     '# Next session',
     '',
-    `(Empty — generated at ${config.generatedAt}.)`,
+    '## Top priority, start here',
+    '',
+    'First session in a fresh install. Run `/onboard` before anything else. It',
+    'reads `.session/onboarding.json`, walks the operator through the remaining',
+    'verification and optional setup steps (runtime check, version check,',
+    'profile intake, shell alias, workspace start, Atlassian), and marks each',
+    'step complete. Re-runnable at any point; already-done steps are skipped.',
     '',
-    'Maintain this file continuously. The "Top priority — start here" section is operator-facing.',
+    'After `/onboard` reports complete, this file is the standard pickup surface',
+    'for every subsequent session. Overwrite it as work rolls over between',
+    'sessions.',
+    '',
+    `Generated at ${config.generatedAt}.`,
     '',
   ].join('\n');
 }
 
+/**
+ * Build the `.session/onboarding.json` seed file.
+ *
+ * The scaffold is the "install" half of onboarding; this state file plus the
+ * `/onboard` slash command are the "walk through everything else" half. On a
+ * fresh scaffold every step is `pending`. The PA reads this file on its first
+ * `/onboard` invocation, walks the pending steps, and rewrites the file after
+ * each step. Idempotent by construction: a `done` or `skipped` step is not
+ * revisited.
+ *
+ * Keys are camelCase per the firm rule. Step names mirror the section headers
+ * in the `/onboard` slash command doc so a reader can map state to prose.
+ */
+export function buildOnboardingStateJson(config) {
+  return {
+    version: 1,
+    generatedAt: config.generatedAt,
+    startedAt: null,
+    steps: {
+      verifyRuntime: 'pending',
+      verifyVersion: 'pending',
+      profileIntake: 'pending',
+      aliasOffer: 'pending',
+      workspaceOffer: 'pending',
+      atlassianOffer: 'pending',
+    },
+    completedAt: null,
+  };
+}
+
 /**
  * Build the staging/.gitkeep contents. Empty directories cannot be tracked
  * by git directly; we drop a .gitkeep marker so the directory is preserved.
@@ -581,6 +640,9 @@ export async function buildPlan(config) {
   const rootClaudeTemplate = await readFile(ROOT_CLAUDE_MD_TEMPLATE_PATH, 'utf8');
   const operatorReadmeTemplate = await readFile(OPERATOR_README_TEMPLATE_PATH, 'utf8');
   const researchCommand = await readFile(RESEARCH_COMMAND_TEMPLATE_PATH, 'utf8');
+  const onboardCommand = existsSync(ONBOARD_COMMAND_TEMPLATE_PATH)
+    ? await readFile(ONBOARD_COMMAND_TEMPLATE_PATH, 'utf8')
+    : null;
   const workspaceExtensionsKnowledge = await readFile(WORKSPACE_EXTENSIONS_KNOWLEDGE_PATH, 'utf8');
   const rcfLiteKnowledge = await readRcfLiteKnowledge(RCF_LITE_KNOWLEDGE_DIR_PATH);
   return buildPlanFromTemplates(config, {
@@ -588,6 +650,7 @@ export async function buildPlan(config) {
     rootClaudeTemplate,
     operatorReadmeTemplate,
     researchCommand,
+    onboardCommand,
     workspaceExtensionsKnowledge,
     rcfLiteKnowledge,
   });
@@ -655,6 +718,7 @@ export function buildPlanFromTemplates(config, templates) {
     '.vault',
     '.claude',
     '.claude/commands',
+    '.session',
   ];
 
   const plan = [];
@@ -678,6 +742,25 @@ export function buildPlanFromTemplates(config, templates) {
       contents: templates.researchCommand,
     });
   }
+  // /onboard slash command: first-session walkthrough. Seeded alongside
+  // `.session/onboarding.json` (see below). Both files are read at plan
+  // time from the packaged core doc; the scaffold never re-authors the body.
+  if (templates.onboardCommand) {
+    plan.push({
+      kind: 'file',
+      path: '.claude/commands/onboard.md',
+      contents: templates.onboardCommand,
+    });
+  }
+  // Onboarding state seed. `.session/` is per-host and gitignored; a fresh
+  // scaffold seeds one file here so `/onboard` has something to read on the
+  // colleague's very first session. Every step is `pending`. See the doc at
+  // `.claude/commands/onboard.md` for the flow the PA walks.
+  plan.push({
+    kind: 'json',
+    path: '.session/onboarding.json',
+    contents: buildOnboardingStateJson(config),
+  });
   plan.push({
     kind: 'json',
     path: '.claude/coordinator-overlay.json',

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

@@ -4,7 +4,7 @@
 
 # {PA_NAME}
 
-You are {PA_NAME}, {OPERATOR_NAME}'s personal assistant. You are a self-learning AI PA built on Claude Code. Your purpose: {PURPOSE}
+You are {PA_NAME}, {OPERATOR_NAME}'s Digital Operator. You are a self-learning AI operator built on Claude Code. Your purpose: {PURPOSE}
 
 You are a colleague, not a servant. You have opinions and you voice them -- with reasoning. If {OPERATOR_NAME} overrides you, you execute without friction and log the decision so you learn from it. You are always doing two things at once: executing the task, and learning from the interaction.
 

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

@@ -1,6 +1,6 @@
 # {PA_NAME}: operator repo
 
-Personal-assistant instance for {OPERATOR_NAME}, scaffolded with `pa-init`.
+Digital Operator instance for {OPERATOR_NAME}, scaffolded with `pa-init`.
 
 This repo holds **only operator content**: your profile, knowledge, work items,
 projects, agent run state, schedules, and secrets. The PA platform code is

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

@@ -1,6 +1,6 @@
 # {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.
+Digital Operator 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
 

package/docs/onboarding-solo.md

@@ -1,183 +1,96 @@
 # 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.
+Ten minutes end to end. One command scaffolds the PA, one command starts a session, then the PA walks you through the rest.
 
-## 0. Prerequisites
+## Prerequisites
 
-You need Node.js 24 or newer, pnpm, git, and the Claude Code CLI signed in to your own subscription. macOS example:
+Working installs of the following, then sign in to Claude Code:
 
-```sh
-brew install node@24 pnpm git
-curl -fsSL https://claude.ai/install.sh | bash    # native installer; symlinks ~/.local/bin/claude and self-updates
-# alternative on macOS: brew install --cask claude-code
-claude                                             # follow the interactive login, then Ctrl-C once you see the prompt
-```
-
-Do not install Claude Code with `npm -g` (or `sudo npm -g`): global npm installs of Claude Code have caused problems in this estate, and running a user-scoped tool under `sudo` is wrong on principle.
+- Node.js 24 or newer: https://nodejs.org (or your platform's Node 24 channel; on macOS `brew install node@24`)
+- pnpm: https://pnpm.io/installation (or `brew install pnpm`)
+- git: https://git-scm.com (or `brew install git`) with your identity already configured
+- Claude Code CLI: https://claude.ai/install (or `brew install --cask claude-code`). Run `claude` once, sign in, then Ctrl-C.
 
-Linux and WSL are equivalent. Install Node 24 through your platform's normal channel.
+Do not install Claude Code with `npm -g` or `sudo npm -g`.
 
 ## 1. Scaffold the PA
 
-```sh
-mkdir ~/pa-bootstrap && cd ~/pa-bootstrap
-# Two files, one heredoc each. `pnpm init -y` writes a `devEngines.packageManager`
-# line pnpm 11.14 then rejects, and `-y` is silently ignored, so write a minimal
-# package.json directly. The `pnpm-workspace.yaml` is the load-bearing file:
-# pnpm holds packages published in the last week back by default (the
-# `minimumReleaseAge` supply-chain gate; it defaults to 0 on pnpm 10 and to a
-# non-zero window on some pnpm 11 defaults), and this repo releases often, so
-# without an explicit exclude an unversioned `pnpm add` silently resolves down
-# to a previous version with a different bin surface. pnpm reads
-# `minimumReleaseAge*` settings ONLY from `pnpm-workspace.yaml` (not from
-# `.npmrc`), and the exclude below trusts only this one package by name so
-# every other dependency your bootstrap ever pulls still honours the operator's
-# global gate.
-cat > package.json <<'JSON'
-{ "name": "pa-bootstrap", "private": true }
-JSON
-cat > pnpm-workspace.yaml <<'YAML'
-minimumReleaseAgeExclude:
-  - "@stravica-ai/digital-operator-pa"
-YAML
-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
-git config user.name  "Your Name"           # cold laptops have no global git identity
-git config user.email "you@example.com"      # local to this repo; skip if you already have a global one
-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.
-
-`pa-init` writes the instance's `package.json` with an EXACT `@stravica-ai/digital-operator-pa` dependency (the version it just installed into `pa-bootstrap`, not a caret range) and drops a `pnpm-workspace.yaml` inside the instance that excludes `@stravica-ai/digital-operator-pa` from the same age gate. Together they belt-and-brace pnpm's supply-chain gate: without them a freshly-published tarball can silently resolve down to the previous version, which may ship a different bin surface.
-
-**Sanity check the version.** `pa-init` prints `package: @stravica-ai/digital-operator-pa@<version>` right after the target line. If the version you see is older than the one `npm view @stravica-ai/digital-operator-pa version` reports, the exclude in your bootstrap `pnpm-workspace.yaml` did not take (rare; usually a stale pnpm store or a typo in the yaml). The `@latest` tag does NOT bypass the release-age gate, so the recovery is to pin the version npm names: `pnpm add @stravica-ai/digital-operator-pa@<version npm view prints>` inside the bootstrap dir, then re-run `pa-init`. When pnpm 11 sees a pinned version that would otherwise be gated, it adds an entry of its own to `pnpm-workspace.yaml` under `minimumReleaseAgeExclude`; the file the guide already asked you to write covers that write.
-
-`pnpm install` in the instance runs automatically as the last step of `pa-init` (skip it with `--skip-install` for CI). The `pa status` verification also runs at the end and prints the resolved package version; a mismatch between the scaffold pin and the installed version prints a WARNING line naming both, so a broken guard surfaces immediately instead of hiding behind a "Command not found" later.
-
-**Do not put the instance under a directory that already contains a `pnpm-workspace.yaml`.** pnpm treats the instance as a workspace member, `pnpm install` silently no-ops, and `node_modules/.bin/pa` never appears. Keep `--target` outside any pnpm workspace root (a top-level `$HOME/<pa-name>-instance`, as shown above, is safe; `~/pa-bootstrap` itself is such a workspace root now, so never nest the `--target` inside it).
-
-## 2. Sanity-check the install
+Pick a `<pa-name>` in lowercase kebab-case (`alex`, `sam`, `hal-9000`). It becomes the agent directory and shows up in every log line.
 
 ```sh
-pnpm exec pa environment
-pnpm exec pa status
-pnpm exec pa knowledge context     # first line: library.mode = simple  (variant token: simple)
+npx -y -p @stravica-ai/digital-operator-pa@latest pa-init \
+  --mode=solo \
+  --name=<pa-name> \
+  --operator="Your Name" \
+  --target=$HOME/<pa-name>-instance \
+  --non-interactive
 ```
 
-`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).
+That is the whole install. `pa-init` writes the instance under `$HOME/<pa-name>-instance`, pins the exact package version, runs `pnpm install`, and runs `pa status` to prove the install booted. It also seeds a `.session/onboarding.json` and a `/onboard` slash command so your PA can walk you through the rest on its first session.
 
-## 3. Start the workspace
+Without flags, `npx -y @stravica-ai/digital-operator-pa@latest pa-init --mode=solo` prompts for each value.
 
-```sh
-pnpm exec pa workspace start                     # opens http://localhost:4200
-pnpm exec pa workspace start --port 4300         # pick a different port if 4200 is taken
-```
-
-The workspace serves a viewer, a home page, and an onboarding form. Long notes from your PA land here rather than in chat. The default port is `4200` (localhost only); the server refuses to start with `Error: Port 4200 is already in use by another process.` when the port is bound by something else (a docker container, another dev server). Pick a free port with `--port N` or set `WORKSPACE_PORT` in your environment; `pa status` reads the resolved port from `operator/config/preferences.json` so keep the two in step for the port to persist across restarts.
-
-## 4. Start your first session
+## 2. Start a session and run /onboard
 
 ```sh
+cd $HOME/<pa-name>-instance
 pnpm exec pa session
 ```
 
-That changes directory into `agents/<pa-name>/` and execs `claude --dangerously-skip-permissions`. Your PA reads its own `CLAUDE.md`, the operator profile, and the autonomy envelope, then greets you.
+Inside the session, type `/onboard`. The PA verifies the runtime, checks the installed version against npm, asks you a few profile questions, offers an optional shell alias, offers to start the local workspace, and offers to wire up Atlassian (Jira, Confluence) if you use it. Every step is idempotent; re-run `/onboard` anytime to redo a specific step.
 
-`pa session` starts Claude Code with the per-call permission prompts switched off. The PA's operating model runs many tool calls per task, and the control layer is the autonomy envelope plus your own review of the commits it produces, not per-call yes/no prompts. Only run it on a machine and a repository you own; the flag is named that way on purpose. If you want prompts back for a session, `cd agents/<pa-name>/ && claude` runs plain Claude Code from the same directory.
+## 3. Alias (optional)
 
-Give your PA a one-word alias so you can start a session from anywhere on the machine. For zsh or bash, append this line to `~/.zshrc` or `~/.bashrc`:
+`pa-init` prints the exact alias line at the end of a successful scaffold. Copy it into `~/.zshrc` or `~/.bashrc` and reload the shell:
 
 ```sh
 alias <pa-name>='cd $HOME/<pa-name>-instance && pnpm exec pa session'
 ```
 
-Then `source ~/.zshrc` (or open a new shell) and typing `<pa-name>` starts the session. `pa-init --mode=solo` prints this exact alias line at the end of a successful scaffold as a reminder.
-
-## 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
-```
+After that, typing `<pa-name>` from anywhere starts a session.
 
 ## 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.
+- A generic Digital Operator operating model rendered into `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 local workspace server on `http://localhost:4200` (start with `pnpm exec pa workspace start`).
 - 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.
-- Workspace-extension prompting: `operator/knowledge/platform-tooling/workspace-extensions.md` teaches your PA when to propose a workspace page (a repeated manual view, an ask for "a page to see X", an installed tool with a natural page) and `pa-init workspace-extension <name>` scaffolds the HTML skeleton plus a `nav.json` entry so the accepted proposal costs thirty seconds instead of thirty minutes. Add `--with-api` when the page needs a server route.
-
-## Workspace extensions
-
-Once your PA has been with you long enough to notice a pattern, expect it to propose a workspace page. Static overlays go under `operator/extensions/workspace/`, additional API routes hang off `operator/extensions/workspace/api.mjs`, and nav entries live in `operator/extensions/workspace/nav.json` (or team-scoped `nav.<team>.json` fragments if you run more than one team on the same box).
-
-To scaffold a new page:
-
-```sh
-pnpm exec pa-init workspace-extension standup           # HTML skeleton + nav entry
-pnpm exec pa-init workspace-extension jira --with-api   # + api.mjs stub
-```
-
-The full mechanism lives in the packaged workspace README (`node_modules/@stravica-ai/digital-operator-pa/dist/engineering-pa-workspace/README.md`, extension mechanism section) and the PA-facing prompting guide is at `operator/knowledge/platform-tooling/workspace-extensions.md`.
+- `.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.
+- Two slash commands out of the box: `/research` (persisted research sessions) and `/onboard` (this walkthrough).
+- Workspace-extension prompting: `operator/knowledge/platform-tooling/workspace-extensions.md` teaches your PA when to propose a workspace page and `pa-init workspace-extension <name>` scaffolds the HTML skeleton plus a `nav.json` entry. Add `--with-api` when the page needs a server route.
 
 ## rcf-lite: build small apps and services
 
 Your PA has the `rcf-lite-engineer` role baked in. It builds greenfield applications from a weekend utility up to a small commercial SaaS, using the `rcf-lite` npm package as the spec-and-build spine (PRD, REQ, US, AC, FBS, with a green test suite gating each build). The link-led knowledge bucket at `operator/knowledge/rcf-lite/` seeds into every fresh solo instance and points at the current [Stravica RCF docs](https://stravica.ai/docs/rcf/); one local `create-a-small-app.md` walks a numbered command sequence from a fresh directory to a candidate build. Ask your PA to "build me a small app for X on rcf-lite" and it dispatches an `rcf-lite-engineer` instance with the deploy target, autonomy envelope, and RCF chain wired in.
 
-## Optional: Jira and Confluence
-
-The `@stravica-ai/digital-operator-pa` package ships three Atlassian CLIs on `PATH`: `jira` (issues, search, transitions, worklogs), `confluence` (spaces, pages, CQL search, mirror), and `confluence-fetch` (search + fetch + save a page under `operator/notes/`). Run `pnpm exec jira --help`, `pnpm exec confluence --help`, `pnpm exec confluence-fetch --help` for the verbs.
-
-Both CLIs share three credentials pointing at the same Atlassian site. Setup:
-
-```sh
-pnpm exec secrets set JIRA_DOMAIN yoursite               # for yoursite.atlassian.net
-pnpm exec secrets set JIRA_EMAIL   you@example.com       # your Atlassian account
-pnpm exec secrets set JIRA_API_TOKEN <paste-token>       # id.atlassian.com/manage-profile/security/api-tokens
-```
-
-`secrets set` self-initialises the vault (age keypair, `.vault/recipients.txt`, empty encrypted store) on the first write when there is nothing at `.vault/` yet. It prints a one-line notice on stderr saying so and continues. You do not need to run `secrets init` manually first. Every `secrets set` also prints one stderr line naming which vault it wrote to; on a fresh solo install with no scope configured that says the write went to the `(legacy)` pot (no scope specified, no default configured). Informational, safe to ignore. Set `SECRETS_DEFAULT_SCOPE` in your environment or configure `defaultScope` in `~/.config/stravica-pa/defaults.json` if you want a named scope; solo mode does not require one.
-
-The age key that self-init generates lives at `~/.config/stravica-pa/age-key.txt` (one per laptop, not per instance). If that file already exists when you scaffold a second PA on the same machine, self-init reuses it, so both instances read and write the same encrypted vault content when a `.vault/` sits under both. That is the point: a single key per operator per machine. To force a fresh key, move the existing one aside (`mv ~/.config/stravica-pa/age-key.txt ~/.config/stravica-pa/age-key.txt.prev`) before the first `secrets set` in the new instance; the vault contents in the old instance will then be unreadable to the new key.
-
-Verify with `pnpm exec jira auth` and `pnpm exec confluence auth`; each prints the current user on success. Credentials also resolve from environment variables of the same names, so a `.env` or shell profile works as an alternative to `secrets`. The `atlassian` entry in `operator/extensions/manifest.json` records the extension is enabled and repeats the setup line.
-
-`jira mine` returns your open issues across every project the account can see. If you spend most of your Jira time in one project, set `JIRA_DEFAULT_PROJECT` (env var or a vault key of the same name) and `jira mine` narrows to it unless you pass `--project KEY` or `--all`:
-
-```sh
-pnpm exec secrets set JIRA_DEFAULT_PROJECT PROJ    # narrow `jira mine` to PROJ by default
-```
-
 ## 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.
+- **`SessionStart` boot-context hook.** In some estates a `SessionStart` hook injects a live workState block 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`.
+- **Team modes.** `pa-init --mode=lead` and `--mode=member` exit with "not implemented". The SIMPLE-mode local library is single-operator by design.
 - **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` and `rcf-lite-engineer` from the engineering types pack. Other tier-ladder roles (`web-developer`, `rcf-engineer`) and estate-specific extensions like `site-cloner`, `seo-*`, `infographic-designer`, `linkedin-writer` are not shipped.
+- **HQ-specialised roles.** The bundled role set is the core seven plus `product-engineer` and `rcf-lite-engineer` from the engineering types pack. Other tier-ladder roles and estate-specific extensions 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
+## Troubleshooting
 
-- **`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. The daemon unit is `com.<paName>.workspace` (launchd) / `<paName>-workspace.service` (systemd), derived from your `paName` in `operator/config/preferences.json`.
+- **`npx` cannot find `pa-init`.** Node 24 must be on your PATH; run `node -v` to confirm. On corporate networks a proxy may block the tarball download; a `pnpm setup` may also be needed if pnpm itself is not on PATH.
+- **`pa status` reports a version older than `npm view @stravica-ai/digital-operator-pa version`.** Rare. `pa-init` pins the exact version and writes a `pnpm-workspace.yaml` with `minimumReleaseAgeExclude` inside the instance so pnpm's release-age gate cannot filter it out. If it still slips, run `pnpm install` inside the instance again to reconcile.
+- **Do not put the instance under a directory that already contains a `pnpm-workspace.yaml`.** pnpm treats the instance as a workspace member, `pnpm install` silently no-ops, and `node_modules/.bin/pa` never appears. `$HOME/<pa-name>-instance` is safe.
+- **Port 4200 already in use.** `pa workspace start --port N` picks a different port. `pa status` reads the resolved port from `operator/config/preferences.json` so keep the two in step across restarts.
 - **`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.
+- **`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. The daemon unit is `com.<paName>.workspace` (launchd) / `<paName>-workspace.service` (systemd).
 - **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.
 
+## Why the single command works
+
+`npx` fetches the tarball from npm, where there is no release-age gate. `pa-init` then writes the instance with an exact-pinned dependency plus a `pnpm-workspace.yaml` that carries `minimumReleaseAgeExclude: ["@stravica-ai/digital-operator-pa"]`, so the frozen `pnpm install` it runs next also lands on the exact version. Together they close the pnpm release-age hole that made the old bootstrap directory necessary in 0.1.41 / 0.1.42.
+
 ## Where things live
 
 | What | Where |
@@ -187,8 +100,10 @@ pnpm exec secrets set JIRA_DEFAULT_PROJECT PROJ    # narrow `jira mine` to PROJ
 | 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`) |
+| Work items | `work/w-YYYY-MM-DD-<author>-NNN.json` |
 | Projects | `projects/{id}/project.json` |
 | Session environment | `.session/environment.json` |
+| Onboarding state | `.session/onboarding.json` |
 | Claude Code settings | `.claude/settings.json` |
 | Coordinator-hook overlay | `.claude/coordinator-overlay.json` |
+| Slash commands | `.claude/commands/` (`onboard.md`, `research.md`) |

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

@@ -1,4 +1,4 @@
-The PA is a personal assistant that runs inside Claude Code on your laptop to handle work, keep knowledge and delegate tasks.
+The PA is a Digital Operator that runs inside Claude Code on your laptop: it runs work, keeps its own knowledge and delegates tasks, and learns your judgement as you correct it.
 
 ## What it does for you day to day
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stravica-ai/digital-operator-pa",
-  "version": "0.1.44",
+  "version": "0.1.46",
   "description": "Digital Operator PA — single-bundled public package surface (bins + library) for the platform.",
   "type": "module",
   "main": "./index.mjs",