@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/docs/tools/memory-sync.md

@@ -0,0 +1,98 @@
+# memory-sync
+
+**Identity:** `ai.stravica.ops.memory-sync`
+
+Bidirectional mirror between Claude Code's per-project memory cache and the repo-tracked `operator/memory/` store. Installed as SessionStart / SessionEnd hooks so every session boots with the latest memories and every session persists any newly-saved ones back to git.
+
+## Status
+
+Implemented:
+
+- `pull` — mirror `<repo>/operator/memory/` into `~/.claude/projects/<sanitised>/memory/`
+- `push` — mirror the local cache back into `<repo>/operator/memory/`
+- Worktree detection — commands no-op when run from a worktree (primary checkout is the sync authority)
+
+Deferred: dry-run mode, selective filters, conflict flagging.
+
+## Install / invoke
+
+Invoked via the `memory-sync` shim:
+
+```
+node <repo>/core/tools/memory-sync/bin/memory-sync <verb>
+```
+
+Hooks in `.claude/settings.json` call this directly. No PATH install is required because the hook already knows the absolute path through `$CLAUDE_PROJECT_DIR`.
+
+## Commands
+
+```
+memory-sync pull          Mirror repo memory dir -> local Claude Code cache
+memory-sync push          Mirror local Claude Code cache -> repo memory dir
+memory-sync -h, --help    Show usage
+```
+
+Both verbs walk up from the current working directory to find the git repo root (a directory containing `.git`). When invoked inside a git worktree (`.git` is a regular file, not a directory) the command logs a skip notice and exits `0` — the primary checkout is the source of truth for memory sync.
+
+Mirroring is "source wins, full": every file in the source tree overwrites its counterpart in the destination, and every file in the destination that does not exist in the source is deleted. Empty directories left over after deletion are pruned.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | OK (including skipped-inside-worktree) |
+| `1` | Usage error (bad verb, extra arguments, missing verb) |
+| `2` | Source dir missing (not in a repo, repo memory dir missing on pull, cache missing on pull/push) |
+| `3` | IO failure (copy / delete / mkdir failed) |
+
+The ladder matches the tooling standard (see [`core/knowledge/standards/tooling.md`](../../knowledge/standards/tooling.md) §6) with `2` overloaded to cover the shell-era semantics "the thing you asked to sync is not where it should be" for wire compatibility with the previous `sync.sh` behaviour.
+
+## Operational discipline rules
+
+- **Run only from the primary checkout.** Worktrees are explicitly skipped. If a session inside a worktree silently synced, it could race with the primary checkout and overwrite fresh memories with stale ones.
+- **Source wins, unconditionally.** There is no merge. Whichever direction you run, the source side is authoritative and the destination is made to match. Conflict resolution lives outside this tool (use git on the repo side).
+- **The `mirror.mjs` module is the sole filesystem chokepoint.** Every byte written or deleted on behalf of the tool passes through it. Commands may not open their own copy loops.
+
+## Project layout
+
+```
+core/tools/memory-sync/
+  bin/memory-sync         # node shebang shim — one line
+  package.json            # name, version, type: module, zero dependencies
+  README.md               # this file
+  src/
+    cli.mjs               # verb routing, exit-code translation
+    cli-support.mjs       # ExitError + log() used by cli + commands
+    repo.mjs              # findRepoRoot, cacheDirFor — pure helpers
+    mirror.mjs            # THE chokepoint — all FS mutation lives here
+    commands/
+      pull.mjs            # repo -> cache
+      push.mjs            # cache -> repo
+  test/
+    cli.test.mjs          # end-to-end over a temp repo tree
+    repo.test.mjs         # repo discovery + cache path sanitisation
+    mirror.test.mjs       # chokepoint behaviour against fixtures
+```
+
+## Tests
+
+```
+node --test core/tools/memory-sync/test/*.test.mjs
+```
+
+All tests use `mkdtemp()` under `os.tmpdir()` and clean up afterwards. No test touches the real cache, the real repo's `operator/memory/` tree, or the real `$HOME`. The CLI tests override `HOME` around the call so `os.homedir()` resolves to a fixture-scoped path.
+
+## The tooling standard
+
+This tool follows [`core/knowledge/standards/tooling.md`](../../knowledge/standards/tooling.md). In particular:
+
+- §2 Node-only — no shell implementation remains.
+- §3 Zero npm dependencies — only `node:*` imports.
+- §4 Layout — bin / src / commands / test as described.
+- §6 Exit codes — `0/1/2/3` ladder.
+- §7 Chokepoint pattern — `mirror.mjs` is the single FS-mutation seam.
+- §11 camelCase JSON — no JSON on the wire yet; the rule still holds when it appears.
+
+## Changelog
+
+- **1.0.0** — Rewritten from `sync.sh` to Node. Behaviour preserved (pull/push verbs, exit-code ladder, worktree skip, source-wins mirror semantics). Drops the rsync dependency.

package/dist/engineering-pa-core/docs/tools/scheduler.md

@@ -0,0 +1,243 @@
+# Task Scheduler
+
+Cross-platform scheduling abstraction for Dave. Lets the PA manage recurring tasks (distillation sweeps, health checks, sync jobs) using OS-native facilities without knowing the backend details.
+
+
+## How it works
+
+1. **detect.mjs** identifies the OS and available scheduling backends
+2. You write a schedule definition as JSON (see format below)
+3. **install.mjs** translates cron syntax to the native format and installs it
+4. **verify.mjs** spawns the schedule's command once under the installed env, as a smoke test
+5. **list.mjs** shows all Dave-managed schedules for the active backend
+6. **remove.mjs** cleans up a schedule from the backend
+7. **index.mjs** re-exports all functions for programmatic use by other tools
+
+All tools are Node.js ESM modules (`.mjs`). Each works as both a CLI tool (`node detect.mjs`) and as an importable module (`import { detect } from './detect.mjs'`). Zero external dependencies -- only `node:` built-in modules.
+
+All schedule definitions use **cron syntax** as the universal format. The install script handles translation to launchd plists, systemd timers, or Windows schtasks.
+
+
+## Supported backends
+
+| Backend | OS | Prefix | Notes |
+|---|---|---|---|
+| launchd | macOS | `com.dave.{id}` | Recommended on macOS. Plist in `~/Library/LaunchAgents/` |
+| cron | macOS, Linux | `dave-{id}` | Widely available fallback |
+| systemd | Linux | `dave-{id}` | Recommended on Linux. User-level timer + service units |
+| schtasks | Windows | `dave-{id}` | Windows Task Scheduler via `schtasks.exe` (native cmd/PowerShell) |
+| docker | Any | — | Detected but not directly managed (use for container-based setups) |
+
+
+## Schedule definition format
+
+Schedule files live in `schedules/` at the repo root. Each is a JSON file:
+
+```json
+{
+  "id": "distillation-sweep",
+  "name": "Daily Distillation Sweep",
+  "schedule": "0 3 * * *",
+  "command": "bash core/tools/distill/run.sh",
+  "workingDirectory": "${DAVE_ROOT}",
+  "enabled": true,
+  "backend": null,
+  "description": "Run the librarian distillation sweep daily at 3am"
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `id` | Yes | Unique identifier. Used in backend naming (`com.dave.{id}`, `dave-{id}`) |
+| `name` | No | Human-readable name |
+| `schedule` | Yes | Cron expression: `minute hour day-of-month month day-of-week` |
+| `command` | Yes | Shell command to execute |
+| `workingDirectory` | No | Working directory. Supports `${DAVE_ROOT}` variable. Defaults to repo root |
+| `enabled` | No | Set to `false` to skip installation. Defaults to `true` |
+| `backend` | No | Override backend for this schedule. `null` uses the deployment default |
+| `host` | No | Device id or hostname this schedule is pinned to run on. Enforced at `install` and `launch` time — see "Host enforcement" below. Omitting it is a warning-only pass, never a refusal. |
+| `description` | No | Human-readable description |
+| `environment` | No | Map of env vars to set for the scheduled process. **Read the warning below before using.** |
+
+The JSON schema is at `packages/core/schema/schedule.json`.
+
+
+## Host enforcement
+
+A schedule's `host` field is matched against the current machine's
+hostname — exact match, then short-name-before-first-dot (so
+`smarthome01` matches `smarthome01.local`). Two enforcement points:
+
+- **`scheduler install`** refuses (exit 2) to install a schedule whose
+  `host` doesn't match the installing machine. `--force-host` overrides
+  the refusal (still prints a warning, and records it in the result's
+  `warnings` array) — for deliberate cross-provisioning.
+- **`launch`** refuses (exit 2) to RUN a task whose schedule declares a
+  foreign host. Since `launch` is invoked non-interactively (by cron/
+  launchd/systemd, not by an operator typing a flag), the override is an
+  env var instead: `DAVE_FORCE_HOST=1`. `--dry-run` is exempt from the
+  hard refusal (it never executes anything) but still prints a warning on
+  a mismatch.
+
+A schedule with no `host` field at all is a warning-only pass in both
+places — host data backfill onto existing schedule files is estate-side,
+not something either tool does automatically.
+
+## Name-collision check
+
+`scheduler install` refuses (exit 2) when another `.json` file in the
+same schedules directory declares the same `id` as the one being
+installed. Two different files sharing an id would otherwise silently
+clobber each other's installed backend entry (same cron tag, same
+launchd label) — whichever installs last wins, and the loser's
+association vanishes with no error anywhere. Malformed sibling files are
+skipped (not this check's job to validate every other file in the
+directory), not treated as a collision or a fatal error.
+
+## Common pitfalls
+
+### Do not set `environment.PATH`, `environment.HOME`, or `environment.DAVE_ROOT` unless you know what you're doing
+
+The launchd installer auto-injects these three variables (`withLaunchdDefaults`) precisely because launchd's default agent env is minimal (`/usr/bin:/bin:/usr/sbin:/sbin`, no `HOME`) and that minimal env silently breaks anything installed via Homebrew. If you set an explicit `environment.PATH` in your schedule, **your value wins** — and on Apple Silicon Macs that almost always means `/opt/homebrew/bin` is missing, and tools like `sops`, `gh`, `jq` become invisible to the scheduled job.
+
+The failure mode is silent: launchd records exit code 78 (`EX_CONFIG`), the StandardErrorPath log is 0 bytes, and the job repeats the same failure every cycle without surfacing.
+
+**Rule of thumb:** the `environment` block is for *operator-meaningful* variables (`API_KEY`, `LOG_LEVEL`, `MY_FEATURE_FLAG`). Leave `PATH`, `HOME`, and `DAVE_ROOT` to the installer. If you genuinely need a custom `PATH`, *extend* the installer's default rather than replacing it — start your value with `${PATH}:/your/extra/bin`.
+
+### cron's real environment is minimal — nvm/pnpm/Homebrew are invisible unless the schedule sources them
+
+Proven live (w-2026-07-15-003, verified with `env -i`): cron's crond process provides a small fixed environment (`SHELL`, a narrow system `PATH` — `/usr/bin:/bin` — `HOME`, `LOGNAME`/`USER`), NOT a login shell's env. A schedule whose `command` relies on `pnpm`/`node` being on PATH via nvm silently fails to spawn once actually installed, even if it "worked" when tested from an interactive terminal.
+
+The generated cron line handles this for you automatically: `scheduler install` detects `$HOME/.nvm/nvm.sh` on the target AT INSTALL TIME and, if present, wraps the command in `bash -c ". $HOME/.nvm/nvm.sh && cd <workDir> && <command> >> /tmp/<agent>-<id>.log 2>&1"`. If no nvm install is found, the preamble is simply omitted — nothing to do for schedules that only need system binaries. `environment.*` values are emitted as `export VAR='val';` statements ahead of the command (not a bare `VAR='val' cd ...` prefix, which in POSIX shell only scopes to the `cd` builtin and never actually reaches the command after `&&` — a real, silent bug the old generator had).
+
+`scheduler verify` now runs this EXACT generated line (not a bare `sched.command`), under cron's actual minimal environment — never the verifying shell's `process.env`. This is deliberate: the old verify path inherited the operator's full login-shell env, which reliably masked this whole bug class. If `verify` reports `ok` today, that's an honest signal the schedule will actually fire under real cron.
+
+### Verify your schedule before walking away
+
+After installing a schedule, run `verify.mjs` to confirm the command actually launches under the installed env. The verify deliberately uses the same env-derivation logic as the installer, so it catches the env-mismatch class of bugs (narrow PATH, missing HOME, etc.) before the job's first scheduled fire — instead of finding out two weeks later from a stale audit log.
+
+```bash
+node core/tools/scheduler/verify.mjs schedules/my-task.json launchd
+```
+
+
+## Usage
+
+### Detect available backends
+
+```bash
+node core/tools/scheduler/detect.mjs
+```
+
+Output:
+```json
+{
+  "os": "darwin",
+  "available": [
+    {"backend": "launchd", "recommended": true, "notes": "Native macOS, survives reboots"},
+    {"backend": "cron", "recommended": false, "notes": "Available but launchd preferred on macOS"}
+  ]
+}
+```
+
+### Install a schedule
+
+```bash
+node core/tools/scheduler/install.mjs schedules/distillation-sweep.json launchd
+```
+
+### Verify a schedule
+
+After installing, run the schedule's command once under the same environment the installer would use. This catches silent-failure bugs caused by env mismatches (e.g. a narrow `environment.PATH` that masks Homebrew binaries on Apple Silicon).
+
+```bash
+node core/tools/scheduler/verify.mjs schedules/my-task.json launchd
+```
+
+If the backend is omitted, verify auto-detects (the same way `detect.mjs` does). Default timeout is 30 seconds; override with `--timeout`:
+
+```bash
+node core/tools/scheduler/verify.mjs schedules/long-job.json launchd --timeout 60
+```
+
+Exit codes: `0` ok, `1` usage error, `2` command exited non-zero, `3` spawn failure (binary not found), `4` timeout.
+
+### List installed schedules
+
+```bash
+node core/tools/scheduler/list.mjs launchd
+```
+
+Pass no argument to auto-detect the backend:
+
+```bash
+node core/tools/scheduler/list.mjs
+```
+
+#### Listing schedules across hosts
+
+`list.mjs <backend>` only sees what the named backend has installed **on the current host**. It reads the running user's crontab, the local `~/Library/LaunchAgents/` directory, the local systemd user units, or the local `schtasks.exe` namespace — there is no remote query. Running `list.mjs cron` on a launchd-recommended macOS workstation returns `(none)` even when a cron job is actively firing on a Linux host elsewhere; that's expected, not a bug. To inspect schedules installed on another machine, run `list.mjs` there directly (`ssh <host> 'cd <repo> && node core/tools/scheduler/list.mjs <backend>'` is a fine pattern). The `/schedule` slash command and the schedules workspace page surface the *intent* (the JSON definitions in `schedules/`); for the *actual installed state*, you must query each host.
+
+### Remove a schedule
+
+```bash
+node core/tools/scheduler/remove.mjs distillation-sweep launchd
+```
+
+Add `--delete-file` to also remove the JSON definition:
+
+```bash
+node core/tools/scheduler/remove.mjs distillation-sweep launchd --delete-file
+```
+
+### Programmatic usage
+
+```js
+import { detect, install, list, remove, verify } from './core/tools/scheduler/index.mjs';
+
+const backends = detect();
+console.log(backends);
+
+install('schedules/my-task.json', 'launchd');
+const v = await verify('schedules/my-task.json', { backend: 'launchd', timeoutMs: 30000 });
+if (v.result !== 'ok') console.error('schedule does not start cleanly:', v);
+
+console.log(list('launchd'));
+remove('my-task', 'launchd', { deleteFile: true });
+```
+
+
+## Integration with /init
+
+During environment discovery, the PA should run `detect.mjs` and store the result in `.dave/config.json` under the `scheduler` key:
+
+```json
+{
+  "scheduler": {
+    "backend": "launchd",
+    "detectedAt": "2026-04-13T12:00:00Z",
+    "available": ["launchd", "cron"]
+  }
+}
+```
+
+The `/schedule` slash command reads this config and uses the stored backend as the default.
+
+
+## Security notes
+
+- All tools are intentionally simple and auditable -- users should read them before granting scheduler access
+- Scheduled tasks run as the current user with that user's permissions
+- No elevated/root permissions are requested
+- Log files are written to `/tmp/` by default (configurable per schedule)
+- The tools never auto-install without explicit invocation
+
+
+## Tests
+
+```bash
+node --test packages/core/test/scheduler/*.test.mjs
+node --test packages/cli/test/scheduler/*.test.mjs packages/cli/test/launch/*.test.mjs
+```
+
+The install tests cover the pure plist/cron/systemd/schtasks builders, `withLaunchdDefaults`, the env-complete cron generator (`buildCronCommand`/`buildCronLine` — nvm preamble, log redirect, `export`-based env propagation), `validateWorkDir` (unresolved-variable / node_modules-trap / nonexistent-dir refusals), `evaluateHostGate`, and `checkNameCollision`. The verify tests cover the env-derivation logic (including cron's new minimal-env honesty), the spawn outcomes (success / non-zero / spawn-failure / timeout), the generated-cron-line execution path, and a regression case for issue #68 (an explicit narrow PATH masking a binary that's available at the parent shell's PATH). `host.test.mjs` covers hostname normalisation/matching in isolation. The CLI-level suites (`packages/cli/test/scheduler/cli-bin.test.mjs`, `packages/cli/test/launch/cli.test.mjs`) exercise host refusal, `--force-host`/`DAVE_FORCE_HOST=1` overrides, and name-collision refusal through the real bins.

package/dist/engineering-pa-core/docs/tools/slice.md

@@ -0,0 +1,150 @@
+# slice
+
+`ai.stravica.ops.slice` — operator profile slice generator.
+
+Produces a compact "boot slice" of the operator's profile -- a short markdown
+document that loads into the PA's context at every session start, in place of
+the full ~18 KB `operator/profile/profile.md`. The full profile remains the
+source of truth; the slice is a fresh snapshot, regenerated periodically (a
+daily cron is the intended cadence — wired separately by the scheduler).
+
+Architecturally the slice replaces a chronic over-load on boot: the canonical
+profile, accumulated rules, and per-domain context can amount to 80--120 KB
+of context every session start, before the operator's first message. The
+slice trades freshness (stale by up to 24h is fine) for cheapness (~1--2 KB
+on boot).
+
+## Status
+
+Implemented: `generate`, `generate --dry-run`, `--help`.
+
+Bundled templates:
+
+- `dave-boot` — the original use case. Six-section operator-boot card aimed
+  at single-operator PA instances like Dave.
+
+Custom templates are loaded with `--template <path>`.
+
+## Install / invoke
+
+Called via the bin shim:
+
+```
+slice generate dave-boot \
+  --profile /path/to/operator/profile/profile.md \
+  --output  /path/to/operator/profile/slices/dave-boot.md
+```
+
+Optional inputs:
+
+- `--learned-rules <path>` — `learned-rules.md` (~50 KB), drives the
+  "load-bearing rules" section.
+- `--observations <dir>`   — a directory of recent observation `.md` files;
+  the generator filters to mtime within the last 21 days (mtimes older than
+  that are dropped). Files prefixed `_` (e.g. `_archive.md`) are always
+  skipped.
+
+## Commands
+
+### `slice generate <name>`
+
+1. Load inputs (`profile.md` is required; `learned-rules.md` and
+   observations dir are optional).
+2. Load the bundled prompt template at
+   `src/slice/prompts/<name>.md` (or `--template <path>` if supplied) and
+   substitute the assembled inputs into the `{{INPUTS}}` placeholder.
+3. Invoke `claude --print --permission-mode bypassPermissions
+   --no-session-persistence --name slice-<ts>` with the assembled prompt as
+   the positional argument. The prompt is handed via `child_process.spawn`
+   with `shell: false` — no shell interpolation, the inputs are safe even if
+   they contain shell metacharacters.
+4. Validate the response against the required-headers contract (six
+   sections: Operator basics, Mission framing, Active projects, Active
+   relationships, Load-bearing rules right now, State of play). A response
+   missing any required header is treated as a generator failure (exit 2)
+   and no file is written.
+5. Validate the size against the 2 KB soft budget. Over-budget responses
+   produce a stderr warning but are written anyway — better to ship a 3 KB
+   slice than skip a regeneration.
+6. Write the response to the configured `--output` path. Parent directories
+   are created if missing.
+
+#### Flags
+
+- `--profile <path>`         Path to `profile.md` (required).
+- `--learned-rules <path>`   Optional.
+- `--observations <dir>`     Optional.
+- `--output <path>`          Where to write the slice (required).
+- `--template <path>`        Override the bundled template path.
+- `--runs-log <path>`        Append one JSON audit line per invocation to
+                             this file. Default-off. See **Audit log** below.
+- `--dry-run`                Build the prompt and report; skip the claude
+                             call and the file write.
+- `-h`, `--help`             Show usage.
+
+### Exit codes
+
+- `0`  ok — slice generated, validated, written.
+- `1`  usage error (missing/extra flags, missing slice name or template).
+- `2`  operational failure (missing input file, missing template,
+        validation failure on the generator's response).
+- `3`  claude transport failure (claude binary exited non-zero).
+
+### Audit log (`--runs-log`)
+
+When `--runs-log <path>` is passed, each invocation appends one JSON line to
+the file in the canonical shape consumed by the `tasks` health monitor:
+
+```json
+{"ts":"2026-05-21T03:00:01Z","status":"ok","exitCode":0,"durationSec":42,"dryRun":false,"outputBytes":1843}
+```
+
+Status vocabulary (closed):
+
+- `ok` — slice generated, validated, written.
+- `noop-dry-run` — `--dry-run` path; no claude call, no file write.
+- `fail-claude` — claude exited non-zero (transport failure, exit 3).
+- `fail-validation` — claude returned content missing required headers (exit 2).
+- `fail-prereq` — input loading failed (missing profile / observations / template, exit 2).
+- `fail-write` — writing the slice output file failed (permissions, ENOSPC, etc., exit 2).
+- `fail-usage` — early arg-validation failed (missing required option, exit 1).
+- `fail-unexpected` — any other thrown exception (defensive catch-all so
+  cron failures never disappear silently).
+
+`reason` is omitted on `ok` / `noop-dry-run`. `outputBytes` is `null` on
+paths that didn't produce a file. Every non-help invocation appends
+exactly one audit line — including the throw paths above — so the
+freshness monitor can distinguish "tool exploded" from "tool was never
+invoked".
+
+When `slice` runs on a schedule (e.g. `30 3 * * *` for nightly slice
+regeneration), the `--runs-log` path becomes the freshness signal for the
+task — point it at a per-task `runs.jsonl` (one task per file; the
+monitor uses `tail -n 1`). The default is **off** so human hand-invocations
+don't pollute the freshness signal of the scheduled run.
+
+Audit writes are best-effort: a failed audit append (missing dir, ENOSPC,
+etc.) is logged to stderr but does NOT change the process exit code. A
+lost audit line is preferable to misclassifying a successful slice
+regeneration as a transport failure.
+
+## Output contract
+
+A single markdown file at the `--output` path. Plain markdown, no
+front-matter, no JSON envelope. The PA's boot rule reads it the same way it
+reads the full profile.
+
+Soft target: under 2 KB / ~30 lines. Hard requirement: the six section
+headers must be present.
+
+## Design notes
+
+- The Claude invocation is funnelled through the same chokepoint runner
+  used by `distill` (`packages/core/src/distill/runner.mjs`). One place
+  in core/src spawns external processes.
+- The prompt template is an `.md` file with a `{{INPUTS}}` placeholder, not
+  a hardcoded string, so an operator can drop in a custom slice template
+  (e.g. `--template ./my-slice.md`) without forking the package.
+- No git, no commit, no push — `slice` is a pure file writer. The per-host
+  `sync` tool picks up any changes the slice produced on its next tick.
+- Tests use a fake runner; no real claude calls in CI.

package/dist/engineering-pa-core/docs/upstream-issue-filing.md

@@ -0,0 +1,88 @@
+# Upstream Issue Filing
+
+In v2 the platform ships as the `@stravica-ai/digital-operator-pa` npm package and is developed in the `Stravica/engineering-pa-dev` repository. When you find a bug or gap in the platform, file a GitHub issue against `Stravica/engineering-pa-dev` so the fix lands in one place and reaches every operator via the next package release.
+
+This document is the lookup-on-demand reference for that workflow. The CLAUDE.md core rule "Platform code is read-only; never edit `node_modules/`" establishes the discipline; this doc is the procedure.
+
+
+## When to file an issue
+
+- A bug in any platform-supplied module (wrong behaviour, broken invariant, regression).
+- A platform enhancement request (new capability, better ergonomics, missing flag).
+- Platform docs are wrong, unclear, or out of date.
+- A platform tool violates the tooling standard at `@stravica-ai/engineering-pa-core/docs/standards/tooling.md`.
+
+
+## When NOT to file
+
+- Bugs in your operator content (`operator/`, `work/`, `projects/`, `agents/`) — those are local to your repo. Fix them directly.
+- Operator-specific workflow questions — those do not generalise to other operators.
+- Anything you can fix locally by adjusting your `operator/extensions/` without touching the package.
+- Questions that are really requests for the operator's judgement.
+
+
+## How to file
+
+Use `gh issue create` against `Stravica/engineering-pa-dev`. Compose the body in a structured way:
+
+```
+gh issue create \
+  --repo Stravica/engineering-pa-dev \
+  --title "<short title, <=160 chars>" \
+  --body "$(cat <<'EOF'
+## Type
+bug | enhancement | docs | question
+
+## Summary
+What, and why.
+
+## Reproducer
+(Required for bug.)
+Steps to reproduce against a clean operator instance.
+
+## Environment
+- Package version: <pnpm list @stravica-ai/digital-operator-pa --depth=0>
+- Node version: <node --version>
+- OS family: <linux | macos | windows>
+
+## Proposed solution
+(Optional.)
+
+## Work-item ref
+(Optional — local work-item ID for trace-back only; we don't read the file.)
+EOF
+)"
+```
+
+Check for duplicates first:
+
+```
+gh issue list --repo Stravica/engineering-pa-dev --search "<keywords>"
+```
+
+
+## Never include in an upstream issue
+
+Upstream issues are public during dev and stay public after the repo flips to `Stravica/engineering-pa`. The following categories of content must not appear in any field you submit:
+
+- Secrets of any kind (API keys, tokens, passwords).
+- Anything read from `.vault/` or any `.env` file.
+- Contents of `operator/profile/` — that is the operator's private profile.
+- Contents of `operator/memory/` — that is your learned-memory store.
+- Contents of `.session/environment.json` — hostname, paths, network posture.
+- Machine hostnames. OS family (`linux` / `macos` / `windows`) is the right granularity.
+- Work-item bodies from your `work/` directory. A `workItemRef` string is fine for trace-back; the body is not.
+
+If your issue legitimately needs to reference a denied root, move the relevant data out of that root first.
+
+
+## Authentication
+
+`gh` must be authenticated with `repo:issue:write` on `Stravica/engineering-pa-dev`:
+
+```
+gh auth login
+gh auth status
+```
+
+If `gh` is missing or unauthenticated, surface that fact and stop.

package/dist/engineering-pa-core/docs/working-directory.md

@@ -0,0 +1,29 @@
+# Working Directory vs Operator Repo Root
+
+Your shell `cwd` when launched is your agent run folder: `agents/<paName>/`. The **operator repo root** is two directory levels up from that cwd. These are different places and the distinction matters.
+
+
+## Never hard-code the operator repo root
+
+The absolute path depends on where the operator's repo was cloned on the current machine — it differs per operator and per device. Always derive it dynamically:
+
+- Env var (preferred): `$DAVE_ROOT` or `$PA_REPO_ROOT` is exported by the platform launcher for processes it runs.
+- Session manifest: `machine.daveRoot` in `.session/environment.json` (populated by `pa-init` and the platform launcher).
+- Shell derivation: `OP_ROOT="$(cd "$(pwd)/../.." && pwd)"` from the run folder.
+
+Platform tools that need the operator repo root accept it via:
+
+1. An explicit caller argument (always wins).
+2. `DAVE_REPO_ROOT` or `PA_REPO_ROOT` environment variable.
+3. A `.git`-walk upwards from `process.cwd()`.
+
+That fallback chain is consistent across `desk`, `distill`, `memory-sync`, `sync`, and the workspace server.
+
+
+## Rules
+
+- Work items (`work/`), projects (`projects/`), knowledge (`operator/knowledge/`), schedules (`schedules/`), and session data (`.session/`) all live at the **operator repo root**, not your cwd.
+- Reference them either as absolute paths built from `$DAVE_ROOT`, or as `<repo-root>/...` in prose — never as `./tools/...` or `./.session/...`. A bare relative path will silently resolve inside `agents/<paName>/` and either fail or write to the wrong place.
+- When running shell commands, use absolute paths built from `$DAVE_ROOT`. If you must `cd` to the repo root, do `cd "$DAVE_ROOT" && ...`.
+- Do NOT create a `.session/` directory inside your agent run folder. The canonical session file is `<repo-root>/.session/environment.json`.
+- Platform code lives in `node_modules/@stravica-ai/digital-operator-pa/` (and its internal packages). Don't try to address it by relative path — use the package's published CLI shims (`node_modules/.bin/<name>`) or import its modules by package path.

package/dist/engineering-pa-core/docs/workspace-operations.md

@@ -0,0 +1,46 @@
+# Workspace Operations
+
+The workspace server provides a web interface for content that does not fit well in the CLI. Managed via `ws.mjs` — always use the CLI, never raw process commands.
+
+
+## When to use the workspace
+
+- Long-form content (reports, documentation, analysis)
+- Structured data (tables, comparisons)
+- Content that benefits from formatting (HTML, styled text)
+- Dashboards and status overviews
+
+
+## Managing the workspace server
+
+```
+node core/tools/workspace/ws.mjs start [--port N] [--no-open]   # Start as background daemon
+node core/tools/workspace/ws.mjs stop                            # Stop the server
+node core/tools/workspace/ws.mjs restart [--port N] [--no-open]  # Stop then start
+node core/tools/workspace/ws.mjs status                          # Show status (PID, port, uptime)
+node core/tools/workspace/ws.mjs open                            # Open browser to server URL
+```
+
+Port resolution order: default 4200 -> `operator/config/preferences.json` key `workspacePort` -> `--port` CLI flag.
+
+Do NOT use `lsof`, `kill`, or raw process management to manage the workspace server. `ws.mjs` handles all of this cross-platform.
+
+Content served by the workspace is read fresh on every request, so file edits are picked up on browser refresh (Cmd+R / Ctrl+R). Live-reload / SSE has been temporarily removed pending a workspace rebuild — refresh the browser manually to see changes. You only need to restart the server when `server.mjs` or `api.mjs` themselves are modified.
+
+
+## Available pages
+
+- `/home.html` — dashboard overview
+- `/projects.html` — project cards with detail drill-down
+- `/project-detail.html` — single project view with work items
+- `/tasks.html` — work item management
+- `/knowledge.html` — knowledge browser
+- `/secrets.html` — secrets management UI
+- `/schedules.html` — scheduled/recurring tasks
+- `/viewer.html?file=path/to/file.md` — generic content viewer (renders markdown to HTML)
+- `/onboarding.html` — first-run setup (normally used once)
+
+
+## Extending the workspace
+
+Custom pages go in `operator/extensions/workspace/`. The server serves files from both `core/tools/workspace/app/` and the extensions directory.