@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/knowledge/operator-interface/session-boot-and-end.md

@@ -0,0 +1,56 @@
+<!--
+  scaffold: session-boot-and-end.md
+  bucket: operator-interface (Bucket 1)
+  what belongs here: the SOP for session boot and session end.
+    - The order of files to read on boot (CLAUDE.md startup routine references this).
+    - The state-adapted briefing pattern (light / busy / post-gap).
+    - The session-end checklist (mandatory-not-optional).
+    - Operator-side overlays specific to how this operator boots and ends sessions.
+-->
+
+# Session boot and end SOP
+
+## Session boot
+
+### Files to read (in order)
+
+1. Run `pnpm exec pa environment` before responding. Read `.session/environment.json`.
+2. Operator profile.
+3. Operator preferences.
+4. PA autonomy envelope.
+5. Learned rules (Librarian-maintained).
+6. Next-session notes.
+7. Spawn-log tail (last few dispatches).
+
+### Briefing the operator on boot
+
+Greet naturally. Quick status: X projects active, Y work items in-flight, Z on operator, W on you. Surface blocked / overdue. Note unprocessed observations if any. Name next-session action items if any.
+
+**Adapt to state:**
+
+- **Light session** (few items, nothing urgent). Brief status, ask what the operator wants to focus on.
+- **Busy session** (many items, blocked work). Lead with what needs attention, suggest priorities.
+- **Returning after a gap** (stale next-session notes). Recap what was happening, ask if priorities have changed.
+
+**Do not:**
+- Say just "Ready." — passive and unhelpful.
+- Over-brief every detail — summarise; let the operator drill into specifics.
+- List every work item — surface the ones that matter.
+
+<!-- OPERATOR: add operator-specific boot steps here (extra config to read, services to launch, domain-state to check). -->
+
+## Session end
+
+Mandatory checklist — every session must leave a clean trail:
+
+1. Stage all observations to `agents/<paName>/staging/`.
+2. Update journal at `agents/<paName>/journal.md`.
+3. Update work items — statuses reflect current state.
+4. Update spawn-log — outcomes recorded for every dispatch that returned.
+5. Update workspace / next-session notes so the next session boots into an accurate state.
+6. Distillation health check (per operator's distillation cadence).
+7. Commit and push to git.
+
+This is not optional. Never let user-facing artefacts (workspace, work items, next-session) go stale.
+
+<!-- OPERATOR: add operator-specific session-end steps here (a heartbeat write, a metrics sync, a domain-specific sign-off). -->

package/dist/engineering-pa-core/knowledge/platform-tooling/README.md

@@ -0,0 +1,37 @@
+# platform-tooling — bucket knowledge scaffold
+
+**Bucket:** 7 of 7. Referenced from CLAUDE.md.template Bucket 7.
+
+## What this bucket carries
+
+Use the estate's own tooling first. Consistent, dogfooded, learnable. Tool-discovery discipline, environment awareness (`pa environment`), platform CLI reference, workspace server, scheduling, MCP servers, working-directory resolution, proactive tool proposal.
+
+## Scope — core vs operator overlay
+
+**In core.** Universal tooling mechanism: tool-discovery-every-session pattern, `pa environment` CLI (verbs + cache + performance constraint), `pa` / `desk` CLI references, workspace server (`pa workspace`), scheduling primitives (`schedules/<id>.json`), MCP server catalogue (discover via `--help`), working-directory resolution, proactive-tool-proposal pattern.
+
+**In operator overlay** (`operator/knowledge/platform-tooling/`). Operator extensions listed under `operator/extensions/tools/`, operator-specific workspace port, operator's default scheduling target host, MCP servers the operator relies on.
+
+## Canonical entries in this scaffold
+
+| File | Purpose |
+|---|---|
+| `tool-discovery-discipline.md` | Every-session-boot rediscover-surface pattern. `pa --help`, `desk --help`, `ls operator/extensions/tools/`. |
+| `environment-awareness.md` | `.session/environment.json` semantics + `pa environment` CLI + performance constraint + boot-instruction design choice. |
+| `pa-cli-reference.md` | The `pa` bin verb overview. Points at `pa --help` as source of truth. |
+| `desk-cli-reference.md` | The `desk` bin — read-only. Points at `desk --help`. |
+| `workspace-server.md` | Workspace server operations. |
+| `scheduling-and-launchd.md` | `schedules/<id>.json` conventions; target host is an operator-configured field. |
+| `working-directory-vs-project-root.md` | cwd vs project root; how to resolve. |
+| `mcp-servers-catalogue.md` | Available MCP servers, use-when-fits guidance. |
+
+## How operators adopt this
+
+Copy the shape into `operator/knowledge/platform-tooling/`. Populate operator extensions list, workspace port, scheduling default host, and MCP-dependency notes in the marked hooks.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 — the rule list that references this deeper doc.
+- `packages/core/docs/workspace-operations.md` — workspace reference.
+- `packages/core/docs/working-directory.md` — cwd vs project root.
+- `packages/core/docs/scheduling.md` — scheduling primitives.

package/dist/engineering-pa-core/knowledge/platform-tooling/desk-cli-reference.md

@@ -0,0 +1,52 @@
+<!--
+  scaffold: desk-cli-reference.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: `desk` bin reference. Read-only complement to `pa work` / `pa project`.
+-->
+
+# `desk` CLI — read-only reference
+
+The `desk` bin is a read-only overview surface for work items and projects. Never edit through desk — writes go through `pa work` and `pa project`.
+
+## Verbs
+
+| Verb | Purpose |
+|---|---|
+| `desk overview` | Summary of all projects and in-flight work. |
+| `desk today` | What is active and needs attention today. |
+| `desk work` | List active work items. Filters: `--mine`, `--theirs`, `--status`, `--project`, `--category`. |
+| `desk projects` | List active projects. `--all` includes done/archived. `--all-teams` / `--team <identity>` control team scoping. |
+
+Run `desk --help` for the current authoritative list.
+
+## Team scoping
+
+`desk projects`, `desk overview`, and `desk today` scope projects to the
+local team-identity set (`executor`, falling back to `assignee`, matched
+against `teamIdentities` — string[], mixed agent + role names — else
+`[paName]`; `paName` is always a member) when
+`operator/config/preferences.json` sets `"scopeProjectsToTeam": true`.
+Unset — the historical default — everything shows, unchanged. Projects
+missing both fields always show (fail open). `--all-teams` bypasses
+scoping; `--team <identity>` narrows to one identity.
+Full rationale: `packages/core/knowledge/work-management/desk-cli.md`.
+
+## When to reach for `desk`
+
+- **Session boot briefing.** `desk overview` is the summary source.
+- **State check.** `desk work --status in-progress` before dispatching new work.
+- **Operator ask "what's in flight".** `desk work` or `desk overview` depending on granularity.
+
+## When NOT to reach for `desk`
+
+- **Reading actual JSON.** Use `Read` on the file.
+- **Writing state.** Use `pa work` / `pa project`.
+
+## Cache behaviour
+
+None. `desk` reads from disk on every invocation.
+
+## Related
+
+- `pa-cli-reference.md` — write-side complement.
+- `packages/core/knowledge/work-management/desk-cli.md` — the discipline this bin supports.

package/dist/engineering-pa-core/knowledge/platform-tooling/environment-awareness.md

@@ -0,0 +1,91 @@
+<!--
+  scaffold: environment-awareness.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: `.session/environment.json` semantics + `pa environment` CLI.
+    - Three verbs (default cache-read, refresh, extended).
+    - Cache write shape.
+    - Performance constraint (<2s cache-read, <5s refresh).
+    - Design choice: on-boot INSTRUCTION rendered into CLAUDE.md, NOT a platform hook.
+-->
+
+# Environment awareness
+
+## The mechanism
+
+`pa environment` populates `.session/environment.json` — a slow-changing snapshot of the current environment (OS, tools, network reachability, workspace state, working directory). The PA reads this on session boot to factor environment into decisions (dispatch target, tool availability, network access, mounted volumes).
+
+## Verbs
+
+| Verb | Purpose |
+|---|---|
+| `pa environment` (default) | Read cache; auto-refresh if missing or stale; print human-readable summary. |
+| `pa environment refresh` | Force rebuild. Re-probe environment, write new cache, print summary. |
+| `pa environment extended` | RESERVED verb. Core errors with a clear message pointing at the operator overlay extension. If the operator has installed the extension, core dispatches to it. |
+
+Global flags:
+
+- `--format json` — machine-readable output.
+- `--quiet` — suppress human summary; the file write is the payload.
+- `--skip-network` — skip network probes (fallback for slow CI or offline dev).
+
+## Cache write shape
+
+`.session/environment.json`. All fields camelCase.
+
+- `capturedAt` — ISO datetime.
+- `capturedBy` — `"pa environment@<version>"`.
+- `platform` — `{ os, arch, kernel, shell }`.
+- `runtimes` — `{ node, pnpm, git }` — each `{ version, path }`.
+- `platformCli` — introspected from `pnpm exec pa --help` parse + package.json bin list.
+- `customTools` — array of `{ name, path }` for each subdir under `operator/extensions/tools/`.
+- `network` — `{ dns: { target, resolved, elapsedMs }, http: { target, statusCode, elapsedMs } }`. Failures record `error` field; file still writes.
+- `workspace` — `{ port, running, url }`.
+- `workingDirectory` — `{ cwd, projectRoot, resolvedVia }`.
+
+Operator-extended verb populates additional top-level fields (`devices`, `scheduledTasks`, `mcpAuthState`, `vpn`, `routeQuality`).
+
+## Performance constraint (hard)
+
+- **Cache-read path: <2s** on a warm cache.
+- **Refresh path: <5s** for a full probe on a healthy machine.
+
+Rationale: runs at every session boot. Slower and the operator waits.
+
+Implementation guidance:
+- Cache-read: single `fs.readFile` + JSON parse + stdout format. Well under 200ms.
+- Full refresh: parallelise probes. `Promise.all` DNS + HTTP + workspace port + version probes.
+- Timeout every network probe at 3s. Failed probe records `error` and continues.
+
+## Session-boot invocation — INSTRUCTION, not hook
+
+**Design choice:** session-boot invocation is an on-boot INSTRUCTION rendered into the CLAUDE.md template's Startup routine, NOT a platform hook.
+
+Reasoning:
+- Hooks add mandatory Claude Code startup latency; latency compounds across sessions.
+- An on-boot CLI invocation resolves synchronously before the first user response, gives the same context freshness, and stays inside the `pa` command surface.
+- The autonomy-envelope session-boot integration (see `packages/core/docs/autonomy-envelope-tracker.md`) is different — it INJECTS context via `additionalContext`; `pa environment` writes a file the PA reads. Different mechanisms; both correct for their purpose.
+
+**Template rendering.** CLAUDE.md.template's Startup routine section carries:
+
+```
+On session boot, run `pnpm exec pa environment` before responding. Read
+`.session/environment.json` for current environment state. Refresh only if
+the environment may have shifted since last cache (machine switch, network
+change, service uncertainty).
+```
+
+## Cache staleness threshold
+
+Default: 60 minutes. Configurable via `operator/config/preferences.json:environment.cacheStalenessMinutes`. Rationale: short enough to catch machine switches and network state changes on same-day sessions; long enough that returning mid-day doesn't cost a probe roundtrip.
+
+## Extension-loader contract for `pa environment extended`
+
+Core looks for `operator/extensions/tools/environment-extended/` in the project root. Expects an `index.mjs` exporting `default async function extended({ core, cwd })` that returns extended fields dict.
+
+Absent or misshapen → exit 2 with operator-facing error message. Present → dynamic `import()`; errors from the extension surfaced verbatim.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rule 2 + Startup routine.
+- `packages/cli/src/environment/` — CLI implementation.
+- `packages/core/docs/autonomy-envelope-tracker.md` — the autonomy-envelope companion mechanism.

package/dist/engineering-pa-core/knowledge/platform-tooling/mcp-servers-catalogue.md

@@ -0,0 +1,52 @@
+<!--
+  scaffold: mcp-servers-catalogue.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: available MCP servers + use-when-fits guidance.
+    - Discover current inventory via the harness's Available agent types + deferred tool list.
+    - MCP inherits into subagents (see dispatch-envelope.md).
+    - Shared session state — Playwright, OAuth-gated tools serialise.
+-->
+
+# MCP servers — catalogue
+
+## Discovery
+
+The current MCP server inventory changes as the operator's estate evolves. **Discover via the harness's `Available agent types` + deferred-tool list**, not from memory. `ToolSearch` loads schemas for specific tools before invocation.
+
+Common categories:
+
+- **Read/write knowledge tools** — rcf-tools for RCF-enabled projects.
+- **Browser automation** — Playwright.
+- **OAuth-gated services** — Gmail, Google Drive, Google Calendar, Atlassian, Canva.
+
+## Use when the task fits
+
+- Playwright when the task is web-driven AND a headless-Node approach won't do.
+- Gmail / Calendar / Drive when the task genuinely needs the operator's authenticated context.
+- rcf-tools when the operator's project is RCF-enabled.
+
+## Don't force
+
+- Don't reach for Playwright when a Node HTTP client would work.
+- Don't reach for Google Drive when a `Read` of an operator-repo file would work.
+- Don't reach for an MCP tool because it's "cool" — reach for it when it's the right shape.
+
+## Shared session state — critical constraint
+
+**From `dispatch-envelope.md § MCP Tool Availability`:**
+
+- Playwright browser sessions are parent-scoped, not per-subagent. Two parallel Playwright workers WILL clobber each other's tabs.
+- OAuth-gated tool auth is inherited from parent — child does not re-authenticate, but the parent's auth state is what the child uses.
+
+**Serialisation rule.** Only one agent at a time should drive a session-stateful MCP tool. Brief the shared-state hazard explicitly in any dispatch that uses one.
+
+## Subagent-type restrictions
+
+Only `general-purpose` and `claude` subagent types inherit the full MCP inventory. `Explore`, `Plan`, `claude-code-guide`, `statusline-setup` all have restricted inventories that exclude MCP tools.
+
+If a dispatched worker needs an MCP tool, it MUST be dispatched as `general-purpose` or `claude`.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rule 7.
+- `dispatch-envelope.md § MCP Tool Availability` — the full findings.

package/dist/engineering-pa-core/knowledge/platform-tooling/pa-cli-reference.md

@@ -0,0 +1,55 @@
+<!--
+  scaffold: pa-cli-reference.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: top-level `pa` bin overview. Point at `pa --help` as source of truth.
+-->
+
+# `pa` CLI — top-level reference
+
+The `pa` bin is the operator-facing top-level CLI. Every verb here is a subcommand routed by the top-level dispatcher.
+
+## Verbs (subject to change — `pa --help` is source of truth)
+
+| Verb | Purpose |
+|---|---|
+| `pa session` | Start a PA session (chdir to agent dir, exec `claude`). |
+| `pa status` | Probe operator content, installed package, workspace reachability, then desk overview. |
+| `pa workspace <verb>` | Workspace server lifecycle (start / stop / status / restart / open). |
+| `pa project <verb>` | Project state writes (create / status / doc add/rm/status / list). |
+| `pa work <verb>` | Work-item state writes (create / status / list). |
+| `pa knowledge <verb>` | Query the operator's knowledge graph (related / search / domain / orphans / path). |
+| `pa autonomy <verb>` | Autonomy envelope get / set / list / init. |
+| `pa environment [verb]` | Environment cache read / refresh / extended. |
+| `pa lint <verb>` | Lint operator text against voice rules. |
+| `pa gsc <verb>` | Google Search Console automation. |
+| `pa staging-alias <verb>` | Canonical staging.<site> alias for CF Workers sites. |
+| `pa migrate-inspect [options]` | Host inspection for migration planning. |
+| `pa launch --agent=<n> --task=<id>` | Boot a scoped agent instance bound to an identity and task. |
+
+Run `pa --help` for the current authoritative list. Verbs land as the operating model evolves; the docs here rot fast.
+
+## Exit codes
+
+Tooling standard § 6:
+
+- `0` ok
+- `1` usage error
+- `2` operational failure
+- `3` transport / IO failure
+
+## When to reach for a specific verb
+
+- **Session start** — `pa session`.
+- **Status check on session boot** — `pa status` (then part of the greeting).
+- **Managing work** — `pa work` (write) + `desk work` (read).
+- **Managing projects** — `pa project` (write) + `desk projects` (read).
+- **Looking up knowledge** — `pa knowledge`.
+- **Managing autonomy state** — `pa autonomy`.
+- **Environment refresh** — `pa environment refresh` (only when the env may have shifted; default `pa environment` reads cache).
+
+## Related
+
+- `desk-cli-reference.md` — read-only complement.
+- `packages/cli/src/pa/cli.mjs` — source of truth for the verb dispatcher.
+- `packages/core/docs/autonomy-envelope-tracker.md` — the `pa autonomy` mechanism.
+- `environment-awareness.md` — the `pa environment` mechanism.

package/dist/engineering-pa-core/knowledge/platform-tooling/scheduling-and-launchd.md

@@ -0,0 +1,56 @@
+<!--
+  scaffold: scheduling-and-launchd.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: `schedules/<id>.json` conventions.
+    - Target-host is an operator-configured field. Core describes mechanism; operator names host.
+-->
+
+# Scheduling
+
+## Location and shape
+
+Scheduled tasks live at `schedules/<id>.json`. JSON manifest per task.
+
+## The mechanism
+
+The core scheduler primitives handle:
+
+- `schedules/<id>.json` manifest parsing.
+- cron-style triggers.
+- Task dispatch via the platform's task-runner (launchd on macOS, systemd on Linux).
+
+Verbs (via `scheduler` bin):
+
+- `scheduler install` — install a scheduled task.
+- `scheduler verify` — check it's registered.
+- `scheduler list` — list installed schedules.
+- `scheduler remove` — remove.
+
+Full reference: `packages/core/docs/scheduling.md`.
+
+## Target host
+
+**Core describes the MECHANISM; operator names the default HOST.** Target host is an operator-configured field in the schedule manifest.
+
+Manifest shape (subset):
+
+```json
+{
+  "id": "distill-4-hourly",
+  "cron": "0 */4 * * *",
+  "targetHost": "<operator-named-host>",
+  "command": "pnpm exec distill"
+}
+```
+
+<!-- OPERATOR: name your default scheduling target host here. Core does NOT prescribe a host name — it's operator-specific. -->
+
+## Why the split
+
+Host names are operator-specific by definition — every operator's machine estate is different. Core prescribing a specific host name would restrict every future operator adopting the platform.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rule 6.
+- `packages/core/docs/scheduling.md`.
+- `packages/core/schema/schedule.json` — canonical manifest schema.

package/dist/engineering-pa-core/knowledge/platform-tooling/tool-discovery-discipline.md

@@ -0,0 +1,49 @@
+<!--
+  scaffold: tool-discovery-discipline.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: the discover-tools-every-session pattern.
+    - Named lists here would rot.
+    - Sources of discovery: pa --help, desk --help, ls operator/extensions/tools/.
+    - Reach for external tools only when nothing local fits.
+-->
+
+# Tool discovery discipline
+
+## The rule
+
+**Discover the current tool surface every session.** Don't rely on memory. Local tools evolve; a named list in this doc would rot.
+
+## Sources of discovery
+
+Three canonical sources:
+
+1. **`pnpm exec pa --help`** — platform-shipped CLI surface. Every verb the PA can use directly.
+2. **`pnpm exec desk --help`** — read-only task management surface.
+3. **`ls operator/extensions/tools/`** — custom operator-side tools. Each subdir has its own bin + README.
+
+For MCP tools, discover via the harness's `Available agent types` and deferred-tool inventory — `ToolSearch` loads schemas for specific tools.
+
+## When to reach for external tools
+
+**Local first.** External tools only when nothing local fits. Reasoning: local tools are dogfooded, consistent, learnable across sessions, and evolve with the operator's needs. External tools are one-off dependencies.
+
+**External is fine when:**
+
+- No local tool covers the surface (e.g. a specific third-party service the operator hasn't wrapped).
+- The one-off use doesn't justify building a local tool.
+- The external tool is the acknowledged standard (e.g. `gh` for GitHub — no need to reinvent).
+
+**External is wrong when:**
+
+- A local tool covers the surface but the PA reached for external out of habit.
+- The one-off use is actually a recurring pattern that should have been a local tool.
+
+## Proactive tool proposal — the follow-on
+
+Bucket 7 rule 9: when a task pattern repeats or manual execution is error-prone, propose a tool to the operator. On approval, dispatch tool-developer at next convenient point. This is estate improvement work you own; don't wait for the operator to suggest.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rules 1, 9.
+- `pa-cli-reference.md`, `desk-cli-reference.md` — canonical CLI references.
+- `packages/core/docs/standards/tooling.md` — the tooling standard.

package/dist/engineering-pa-core/knowledge/platform-tooling/working-directory-vs-project-root.md

@@ -0,0 +1,43 @@
+<!--
+  scaffold: working-directory-vs-project-root.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: cwd vs project root.
+    - cwd is agents/<paName>/; project root is 2 levels up.
+    - Resolve via `.session/environment.json:workingDirectory.projectRoot` or a `*_ROOT` env var.
+    - Never hard-code paths.
+-->
+
+# Working directory vs project root
+
+## The distinction
+
+The PA's shell **cwd** is its run folder — `agents/<paName>/`. The **project root** is two levels up — the operator repo's root.
+
+Every tool and command runs in the run folder by default. Anything that references the operator's estate (`operator/`, `work/`, `projects/`, `schedules/`) must resolve the project root first.
+
+## Resolution order
+
+Preferred (in order of reliability):
+
+1. **`.session/environment.json:workingDirectory.projectRoot`** — populated by `pa environment`. Deterministic; refreshed on session boot.
+2. **`$<PA_NAME>_ROOT` env var** — e.g. `$DAVE_ROOT`. Operator-set on machines where this is more convenient.
+3. **Walk upward from cwd** — search for a marker file (e.g. `agents/*/CLAUDE.md`, `.git/`) as a fallback.
+4. **`cd "$(pwd)/../.." && pwd`** — hard-coded relative walk. Only when everything else has failed.
+
+**Never hard-code an absolute path.** Absolute paths break the moment the PA runs on a different machine or the operator's repo moves.
+
+## Common failure modes
+
+- **Assuming cwd IS the project root.** cwd is `agents/<paName>/`; `work/w-...json` doesn't exist at that level.
+- **Hard-coding a `/Users/...` or `/home/...` path.** Breaks cross-machine.
+- **Relying on `process.cwd()` inside a subagent worktree.** Worktrees are at `.claude/worktrees/agent-<id>/`; cwd inside a worktree is not the operator repo root.
+
+## In bash calls
+
+Prefer absolute paths derived from a resolved project root, not relative paths that assume cwd. This makes commands portable across the worker's shell state.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rule 8.
+- `packages/core/docs/working-directory.md` — canonical detail.
+- `environment-awareness.md` — `.session/environment.json:workingDirectory` field.

package/dist/engineering-pa-core/knowledge/platform-tooling/workspace-server.md

@@ -0,0 +1,51 @@
+<!--
+  scaffold: workspace-server.md
+  bucket: platform-tooling (Bucket 7)
+  what belongs here: workspace server operations.
+    - Default port (4200).
+    - viewer.html for long content.
+    - `pa workspace start / stop / status / restart / open`.
+    - Supervisor-aware lifecycle (launchd / systemd).
+    - Point at packages/core/docs/workspace-operations.md.
+-->
+
+# Workspace server
+
+## Purpose
+
+The workspace server hosts `viewer.html` — the PA's canonical surface for long-form content, structured data, tables, and reports. Direct the operator to `http://localhost:<port>/viewer.html?file=path/to/file.md` instead of pasting long output into chat.
+
+## Verbs
+
+| Verb | Purpose |
+|---|---|
+| `pa workspace start [--port N] [--no-open]` | Start the workspace server. |
+| `pa workspace stop` | Stop the server (refuses if supervised — see below). |
+| `pa workspace status` | Show server status (supervisor-aware). |
+| `pa workspace restart [--port N] [--no-open]` | Restart. Supervisor-aware — launchctl kickstart / systemctl restart. |
+| `pa workspace open` | Open the workspace URL in a browser. |
+
+## Default port
+
+`4200`. Configurable via `operator/config/preferences.json:workspacePort`.
+
+<!-- OPERATOR: name your workspace port here if it's not 4200. -->
+
+## Supervisor-aware lifecycle
+
+When the workspace is supervised by launchd (`~/Library/LaunchAgents/com.dave.workspace.plist`) or systemd (`~/.config/systemd/user/dave-workspace.service`), `stop` is refused and `restart` delegates to the supervisor. This is the in-place version-pickup path after `pnpm update @stravica-ai/digital-operator-pa`.
+
+## When to use the workspace
+
+- **Long-form content** — anything more than a few paragraphs.
+- **Structured data / tables** — anything that renders better in HTML than in a chat line-wrap.
+- **Reports** — session reports, dispatch outcomes, project progress trackers.
+
+## Full operations reference
+
+`packages/core/docs/workspace-operations.md`.
+
+## Related
+
+- CLAUDE.md.template Bucket 7 rule 5.
+- `packages/core/docs/workspace-operations.md`.

package/dist/engineering-pa-core/knowledge/scaffold/domains.json

@@ -0,0 +1,5 @@
+{
+  "version": "1.0",
+  "domains": [],
+  "note": "Domains are populated as you add knowledge. Each domain has: id, name, path, description, fileCount, lastUpdated."
+}

package/dist/engineering-pa-core/knowledge/work-management/README.md

@@ -0,0 +1,33 @@
+# work-management — bucket knowledge scaffold
+
+**Bucket:** 2 of 7. Referenced from CLAUDE.md.template Bucket 2.
+
+## What this bucket carries
+
+How the PA tracks work so the operator sees what's in flight without asking. Work items, projects, spawn-log, progress trackers, the desk read-side overview.
+
+## Scope — core vs operator overlay
+
+**In core.** Universal work-tracking mechanism: work-item schema, project schema, status/category/priority conventions, opening-before-work discipline, updating-at-material-change discipline, progress.md pattern, spawn-log-at-dispatch-time discipline, camelCase JSON discipline, desk CLI reference.
+
+**In operator overlay** (`operator/knowledge/work-management/`). Operator-specific extensions: content-scheduling tools bolted on top of `pa work`, operator-specific priority mappings, special work-item categories the operator uses, cross-project rollup patterns.
+
+## Canonical entries in this scaffold
+
+| File | Purpose |
+|---|---|
+| `work-items.md` | Schema reference, status/category/priority, opening-before-work rule, updating discipline. |
+| `projects.md` | Schema reference, project lifecycle, project-vs-work-item choice, `pa project doc` interface. |
+| `progress-md.md` | Progress-tracker discipline — newest top, references not duplicates, concurrent-work has a home. |
+| `desk-cli.md` | Read-only overview surface. Structure of `desk overview`, `desk today`, `desk work`, `desk projects`. |
+| `spawn-log.md` | Spawn-log discipline — updated at dispatch time, not at session end. |
+
+## How operators adopt this
+
+Copy the shape into `operator/knowledge/work-management/`. Populate operator-side extensions in the marked hooks; do not modify the core conventions.
+
+## Related
+
+- CLAUDE.md.template Bucket 2 — the rule list that references this deeper doc.
+- `@stravica-ai/engineering-pa-core/schema/work-item.json` and `project.json` — canonical schemas.
+- `pa work --help`, `pa project --help`, `desk --help` — CLI reference.