@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-core/docs/blueprints/ideas/knowledge-domain-patterns.md

@@ -0,0 +1,15 @@
+# Knowledge Domain Patterns
+
+Common domain structures that work well for different types of knowledge. These patterns can be used as templates when setting up new knowledge domains.
+
+**Recipes/Cooking**: ingredient index, technique notes, meal plans, shopping list generation. The PA can cross-reference ingredients across recipes and suggest substitutions based on what is available.
+
+**Project Notes**: per-project directories with decision logs, meeting notes, architecture documents, and TODO lists. The PA indexes decisions and can recall why something was decided months later.
+
+**Meeting Notes**: timestamped entries with attendees, action items, and key decisions. The PA extracts action items and creates work items automatically.
+
+**Reading Notes**: book/article summaries with key takeaways, quotes, and connections to other reading. The PA can surface relevant past reading when you encounter related topics.
+
+**Health/Fitness**: workout logs, measurements, meal tracking. Time-series data that the PA can analyse for trends and suggest adjustments.
+
+Each pattern would include a sample directory structure, example documents, and suggested distillation rules for the librarian.

package/dist/engineering-pa-core/docs/blueprints/ideas/office-integration.md

@@ -0,0 +1,11 @@
+# Office Integration
+
+Connect your PA to calendar, email, and document services so it can manage scheduling, draft communications, and access shared documents.
+
+**Calendar**: read upcoming events, create new events, check availability, suggest meeting times. The PA could proactively prepare briefing notes before meetings by pulling relevant knowledge.
+
+**Email**: draft replies, summarise inbox, flag important messages, create work items from email threads. Requires careful access controls -- the PA should draft but not send without confirmation.
+
+**Documents**: read and summarise Google Docs, Notion pages, or SharePoint documents. Pull content into the knowledge system for indexing. Create new documents from templates.
+
+Implementation would use MCP servers for each service (Google Calendar MCP, Gmail MCP, etc.) combined with custom logic in the PA's role definition for when and how to use each integration. The key challenge is permission boundaries -- the PA needs enough access to be useful but not so much that a hallucination sends an embarrassing email.

package/dist/engineering-pa-core/docs/blueprints/ideas/team-scaling.md

@@ -0,0 +1,9 @@
+# Team Scaling
+
+Run multiple PA instances for a team, each with their own identity and knowledge domain but sharing common team knowledge.
+
+The architecture would involve a shared git repository with team-level knowledge (standards, processes, shared decisions) and per-person branches or directories for individual knowledge. Each PA instance runs independently but can reference team knowledge when needed.
+
+Challenges to solve: merge conflicts when multiple PAs commit simultaneously, knowledge deduplication across team members, consistent tool configurations, and shared vs private observation boundaries. A "team lead" PA pattern could coordinate across instances, similar to a task group orchestrator but persistent.
+
+Use cases: engineering teams where each developer has their own PA but the team shares coding standards, architecture decisions, and project context. The team lead PA could run standups by collecting status from each individual PA.

package/dist/engineering-pa-core/docs/blueprints/ideas/work-personal-separation.md

@@ -0,0 +1,9 @@
+# Work/Personal Separation
+
+Separate work and personal knowledge domains so they can be managed, backed up, and accessed independently.
+
+The core idea is to define domain boundaries in the knowledge configuration -- a `work` domain and a `personal` domain, each with their own directory trees, distillation rules, and access controls. Your PA would route observations to the correct domain based on context clues (project names, time of day, explicit tags).
+
+This matters when you want to back up personal notes without including work IP, or share work knowledge with a team without exposing personal data. It also helps the PA avoid cross-contaminating contexts -- your meal planning knowledge should not surface during code review sessions.
+
+Open questions: how to handle items that span both domains, whether to use separate git branches or separate directories, and how distillation should merge or keep separate.

package/dist/engineering-pa-core/docs/blueprints/scheduled-distillation/blueprint.md

@@ -0,0 +1,129 @@
+# Scheduled Distillation
+
+Set up automated knowledge distillation that runs on a schedule, triggering the librarian role to sweep staging areas and promote observations into structured knowledge.
+
+
+## What it does
+
+The distillation process reads unprocessed observations from agent staging directories, evaluates them for value, and promotes useful content into the knowledge system. Running this on a schedule ensures knowledge stays current without manual intervention.
+
+
+## Prerequisites
+
+- A working Dave installation with at least one agent that produces staging observations
+- The `core/tools/distill/` scripts must be present and executable
+- The Dave scheduler (`core/tools/scheduler/`) -- handles backend detection and installation
+
+
+## Setup using the scheduler
+
+The recommended approach uses Dave's built-in scheduling system, which auto-detects your OS and available backends (launchd on macOS, systemd on Linux, cron, or Windows schtasks).
+
+### 1. Create the schedule definition
+
+Create `schedules/distillation-sweep.json`:
+
+```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",
+  "environment": {
+    "DAVE_ROOT": "${DAVE_ROOT}"
+  }
+}
+```
+
+On macOS/launchd, the installer auto-injects `PATH` (captured from the
+install-time shell), `HOME`, and `DAVE_ROOT` into the generated plist,
+so Homebrew-installed tools (`node`, `claude`, `git`) work out of the
+box. Any key you list under `environment` overrides the auto-injected
+default. On cron/systemd/schtasks, only the keys you declare are set —
+no auto-defaults — because those backends do not have launchd's
+minimal-environment footgun. Values support `${DAVE_ROOT}`, `${HOME}`,
+and `${USER}` substitution at install time.
+
+Adjust the `schedule` field (cron syntax) as needed:
+- `0 3 * * *` -- daily at 3am
+- `0 */6 * * *` -- every 6 hours
+- `0 * * * *` -- hourly (for active development)
+
+### 2. Detect available backends
+
+```bash
+node core/tools/scheduler/detect.mjs
+```
+
+This outputs a JSON report showing which scheduling facilities are available on your system.
+
+### 3. Install the schedule
+
+```bash
+node core/tools/scheduler/install.mjs schedules/distillation-sweep.json <backend>
+```
+
+Replace `<backend>` with one from the detect output (e.g. `launchd`, `cron`, `systemd`, `schtasks`).
+
+### 4. Verify installation
+
+```bash
+node core/tools/scheduler/list.mjs <backend>
+```
+
+### Using the /schedule command
+
+If you prefer, use the `/schedule` slash command in a PA session. It walks you through detection, creation, and installation interactively.
+
+### Removing the schedule
+
+```bash
+node core/tools/scheduler/remove.mjs distillation-sweep <backend>
+```
+
+
+## Manual setup (alternative)
+
+If you prefer not to use the scheduler abstraction, you can set up scheduling directly.
+
+### Wrapper script
+
+Create a shell script that the scheduler will invoke:
+
+```bash
+#!/usr/bin/env bash
+# distill-cron.sh -- wrapper for scheduled distillation
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$REPO_ROOT"
+
+# Run distillation
+node core/tools/distill/distill.mjs --auto 2>&1 | tee -a /tmp/dave-distill.log
+
+# Commit if there are changes
+if [ -n "$(git status --porcelain)" ]; then
+  git add -A
+  git commit -m "Distillation sweep $(date -u +%Y-%m-%dT%H-%M-%SZ)"
+fi
+```
+
+Save as `scripts/distill-cron.sh` and make it executable. Then add it to your OS scheduler manually (crontab, launchd plist, systemd timer, etc.).
+
+
+## Tuning
+
+- **Frequency**: Start with every 6 hours. Reduce to daily if staging volume is low, or increase to hourly during active development sprints.
+- **Log rotation**: Logs go to `/tmp/dave-{id}-*.log`. Set up logrotate or periodically truncate.
+- **Notification**: Add a notification step (e.g. webhook, email) after the git commit line if you want to be alerted when distillation produces changes.
+
+
+## Further reading
+
+- Scheduler system: `core/tools/scheduler/README.md`
+- Schedule JSON schema: `core/tools/desk/schema/schedule.json`
+- `/schedule` slash command: `core/commands/schedule.md`

package/dist/engineering-pa-core/docs/blueprints/tool-integration/blueprint.md

@@ -0,0 +1,110 @@
+# Tool Integration
+
+Connect external tools and APIs to your PA via MCP (Model Context Protocol) servers. This gives your PA the ability to interact with services like GitHub, Slack, Google Drive, Jira, and more.
+
+
+## What it does
+
+MCP servers expose external tool capabilities to Claude Code. Once configured, your PA can use these tools naturally during conversations -- creating GitHub issues, sending Slack messages, reading Google Drive documents, etc.
+
+
+## Prerequisites
+
+- Node.js 18+ or the runtime required by the specific MCP server
+- An account and API credentials for the service you want to integrate
+- Claude Code installed and running
+
+
+## Steps
+
+### 1. Choose an MCP server
+
+Popular MCP servers and where to find them:
+
+| Service | Package | Source |
+|---------|---------|--------|
+| GitHub | `@modelcontextprotocol/server-github` | npmjs.com |
+| Slack | `@modelcontextprotocol/server-slack` | npmjs.com |
+| Google Drive | `@anthropic-ai/google-drive-mcp` | Anthropic |
+| Jira | `@anthropic-ai/jira-mcp` | Anthropic |
+| Filesystem | `@modelcontextprotocol/server-filesystem` | npmjs.com |
+| PostgreSQL | `@modelcontextprotocol/server-postgres` | npmjs.com |
+
+For a full list, see the [MCP server directory](https://github.com/modelcontextprotocol/servers).
+
+### 2. Install the MCP server
+
+```bash
+npm install -g @modelcontextprotocol/server-github
+```
+
+Or install locally in your project:
+
+```bash
+npm install @modelcontextprotocol/server-github
+```
+
+### 3. Configure in Claude Code settings
+
+Add the MCP server to your Claude Code configuration. Edit `.claude/settings.json` in your project root (or `~/.claude/settings.json` for global config):
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Store the actual token in your secrets vault:
+
+```bash
+node core/tools/secrets/bin/secrets set GITHUB_TOKEN ghp_your_token_here
+```
+
+### 4. Verify the integration
+
+Start a new Claude Code session and ask your PA to use the tool:
+
+- GitHub: "List my open pull requests"
+- Slack: "Send a message to #general"
+- Google Drive: "Find documents about project X"
+
+If the PA reports the tool is unavailable, check:
+- The MCP server is installed correctly
+- Environment variables are set
+- The settings.json path is correct
+
+
+## Adding multiple integrations
+
+Repeat steps 1-4 for each service. Each gets its own entry in the `mcpServers` block:
+
+```json
+{
+  "mcpServers": {
+    "github": { "..." : "..." },
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-slack"],
+      "env": {
+        "SLACK_BOT_TOKEN": "${SLACK_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+
+## Security notes
+
+- Store all API tokens in the secrets vault, not in plaintext config files
+- Use the minimum required permissions when creating API tokens
+- Rotate tokens periodically using the secrets vault rotate function
+- Review which tools your PA has access to -- more tools means a larger action surface

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

@@ -0,0 +1,159 @@
+# /init -- Environment Discovery
+
+Discover the current environment and write a session snapshot to `.session/environment.json`. This gives you situational awareness of the machine, network, available tools, running services, and current work state.
+
+Run this command on first boot if `.session/environment.json` does not exist or is older than 1 hour.
+
+## Behaviour
+
+Execute all discovery steps below using shell commands, then assemble the results into a single JSON object and write it to `.session/environment.json` at the project root.
+
+**Important:** The `.session/` directory should already exist (created by `dave.sh`). If it does not, create it with `mkdir -p .session`.
+
+### 1. Machine identity
+
+```bash
+hostname
+uname -s
+uname -m
+
+# Resolve project root: trust $DAVE_ROOT if exported, otherwise walk two parents up from cwd.
+# cwd when /init runs is the PA run folder (<project-root>/agents/<paName>/).
+if [ -n "$DAVE_ROOT" ]; then
+  echo "$DAVE_ROOT"
+else
+  cd "$(pwd)/../.." && pwd
+fi
+```
+
+Capture as:
+```json
+{
+  "hostname": "<hostname output>",
+  "os": "<uname -s output>",
+  "arch": "<uname -m output>",
+  "daveRoot": "<resolved project root — absolute path>"
+}
+```
+
+### 2. Network
+
+```bash
+# Local IP (portable across macOS and Linux)
+if command -v ip >/dev/null 2>&1; then
+  ip route get 1.1.1.1 2>/dev/null | awk '{for(i=1;i<=NF;i++) if ($i=="src") print $(i+1)}'
+else
+  ipconfig getifaddr en0 2>/dev/null || echo "unknown"
+fi
+
+# Internet connectivity
+curl -sf --max-time 3 https://httpbin.org/status/200 >/dev/null 2>&1 && echo "true" || echo "false"
+```
+
+Capture as:
+```json
+{
+  "localIp": "<detected IP or 'unknown'>",
+  "internet": true
+}
+```
+
+### 3. Available tools
+
+Check each tool's availability and version. Use `command -v <tool>` to test presence, then capture the version string.
+
+| Tool | Version command |
+|---|---|
+| git | `git --version` |
+| node | `node --version` |
+| python | `python3 --version` |
+| docker | `docker --version` |
+| claude | `claude --version` |
+
+Capture as:
+```json
+{
+  "git": "2.x.x" or false,
+  "node": "v22.x.x" or false,
+  "python": "3.x.x" or false,
+  "docker": "27.x.x" or false,
+  "claude": "1.x.x" or false
+}
+```
+
+Use `false` (boolean) if the tool is not installed. Use the version string if it is.
+
+### 4. Services
+
+Check if the workspace server is running by testing the configured port:
+
+```bash
+# Read port from preferences or default to 4200
+curl -sf --max-time 2 http://127.0.0.1:${PORT:-4200}/health >/dev/null 2>&1 || \
+curl -sf --max-time 2 http://127.0.0.1:${PORT:-4200}/ >/dev/null 2>&1
+```
+
+Capture as:
+```json
+{
+  "workspace": {
+    "url": "http://127.0.0.1:<port>",
+    "running": true
+  }
+}
+```
+
+### 5. Work state
+
+Run the HQ CLI overview and read next-session notes:
+
+```bash
+# Overview
+node core/tools/desk/bin/desk overview 2>/dev/null || echo "(desk overview not available)"
+
+# Next-session notes -- read the PA's own file
+# The PA name comes from operator/config/preferences.json
+cat agents/<paName>/next-session.md 2>/dev/null || echo ""
+```
+
+Read the PA name from `operator/config/preferences.json` (the `paName` field).
+
+Capture as:
+```json
+{
+  "overview": "<desk overview stdout>",
+  "nextSession": "<contents of next-session.md or null>",
+  "capturedAt": "<ISO8601>"
+}
+```
+
+Use `null` (not the string "null") if next-session.md does not exist.
+
+### 6. Assemble and write
+
+Combine all sections into the final JSON structure:
+
+```json
+{
+  "capturedAt": "<ISO8601 timestamp>",
+  "machine": { "hostname": "...", "os": "...", "arch": "...", "daveRoot": "..." },
+  "network": { "localIp": "...", "internet": true },
+  "tools": { "git": "...", "node": "...", "python": "...", "docker": false, "claude": "..." },
+  "services": { "workspace": { "url": "...", "running": true } },
+  "workState": {
+    "overview": "...",
+    "nextSession": "..." or null,
+    "capturedAt": "<ISO8601>"
+  }
+}
+```
+
+Write this to `.session/environment.json` at the project root. Use camelCase for all property names. Ensure the output is valid JSON (no trailing commas, proper quoting).
+
+### 7. Report
+
+After writing, give a brief one-line summary of what was discovered. Example:
+
+> Environment captured: macbook-pro / macOS arm64, internet up, 4/5 tools available, workspace running on :4200.
+
+Do not dump the full JSON back to the user.

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

@@ -0,0 +1,98 @@
+# /schedule -- Manage recurring scheduled tasks
+
+Manage Dave's scheduled tasks: list, create, enable, disable, and remove recurring jobs that run via OS-native scheduling facilities.
+
+## Behaviour
+
+### First use / no backend configured
+
+If `.dave/config.json` does not have a `scheduler.backend` key, run detection first:
+
+```bash
+node core/tools/scheduler/detect.mjs
+```
+
+Present the available backends to the user with the recommendation noted. Ask which backend to use. Store the choice in `.dave/config.json`:
+
+```json
+{
+  "scheduler": {
+    "backend": "<chosen>",
+    "detectedAt": "<ISO timestamp>",
+    "available": ["<list>"]
+  }
+}
+```
+
+### List schedules
+
+Show all installed Dave schedules for the configured backend:
+
+```bash
+node core/tools/scheduler/list.mjs <backend>
+```
+
+Also list any schedule JSON files in `schedules/` that are not yet installed (enabled but no matching backend entry).
+
+### Create a new schedule
+
+1. Ask the user for: id, name, cron expression, command, and description
+2. Write the schedule JSON to `schedules/<id>.json`
+3. Run install:
+
+```bash
+node core/tools/scheduler/install.mjs schedules/<id>.json <backend>
+```
+
+4. Confirm installation
+
+### Enable / disable a schedule
+
+To disable: set `enabled: false` in the schedule JSON and run remove.mjs for the backend.
+
+To enable: set `enabled: true` and run install.mjs.
+
+### Remove a schedule
+
+```bash
+node core/tools/scheduler/remove.mjs <id> <backend> --delete-file
+```
+
+### Run a schedule now (manual trigger)
+
+Execute the command from the schedule JSON directly:
+
+```bash
+cd <workingDirectory> && <command>
+```
+
+## Schedule format
+
+See `core/tools/desk/schema/schedule.json` for the full JSON schema. Quick reference:
+
+| Field | Required | Example |
+|---|---|---|
+| `id` | Yes | `distillation-sweep` |
+| `name` | No | `Daily Distillation Sweep` |
+| `schedule` | Yes | `0 3 * * *` (cron syntax) |
+| `command` | Yes | `bash core/tools/distill/run.sh` |
+| `workingDirectory` | No | `${DAVE_ROOT}` |
+| `enabled` | No | `true` |
+| `description` | No | `Run distillation daily at 3am` |
+
+## Common schedules
+
+| Task | Suggested cron | Command |
+|---|---|---|
+| Distillation sweep | `0 3 * * *` | `bash core/tools/distill/run.sh` |
+| Knowledge reindex | `0 */6 * * *` | `node core/knowledge/retrieval/index-builder.mjs` |
+| Health check | `*/30 * * * *` | `node core/tools/scheduler/detect.mjs` |
+
+## Backend reference
+
+| Backend | OS | How it works |
+|---|---|---|
+| launchd | macOS | Plist in `~/Library/LaunchAgents/com.dave.{id}.plist` |
+| cron | macOS/Linux | Crontab entries tagged with `# dave-{id}` |
+| systemd | Linux | User timer + service in `~/.config/systemd/user/dave-{id}.{timer,service}` |
+| schtasks | Windows | Windows Task Scheduler entries named `dave-{id}` |

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

@@ -0,0 +1,67 @@
+# /upgrade -- Pull the latest platform release
+
+You are running the upgrade command. Follow these steps exactly.
+
+In v2 the platform is distributed as the npm package `@stravica-ai/digital-operator-pa`. There is no fork-and-merge step; updates happen via `pnpm update`.
+
+## Step 1: Check current version
+
+Run:
+
+```bash
+pnpm list @stravica-ai/digital-operator-pa --depth=0
+```
+
+Note the currently-installed version. If the package is missing from the lockfile, surface the error and stop — the operator's repo is not initialised against the platform.
+
+## Step 2: Check for a newer release
+
+Run:
+
+```bash
+pnpm outdated @stravica-ai/digital-operator-pa
+```
+
+If there is no newer version available, tell the operator they are already up to date and stop.
+
+If a newer version is available, show the operator the version delta and the published release notes URL (the package's repository field points to the canonical changelog).
+
+## Step 3: Ask for confirmation
+
+Tell the operator what will happen: `pnpm update @stravica-ai/digital-operator-pa` will update the package and refresh the lockfile. Remind them that operator content (`operator/`, `work/`, `projects/`, `agents/`, `schedules/`, `.vault/`) is never touched by `pnpm update` — only `node_modules/` and `pnpm-lock.yaml` change.
+
+**Wait for the operator to confirm before proceeding.** Do not update without explicit confirmation.
+
+## Step 4: Update
+
+Run:
+
+```bash
+pnpm update @stravica-ai/digital-operator-pa
+```
+
+Then:
+
+```bash
+pa status
+```
+
+The status command verifies the new version boots cleanly against the operator's existing content. If `pa status` reports problems, surface them and stop — do not declare the upgrade successful.
+
+If `pa status` is healthy, report success and show a summary of what changed (release notes link is the primary reference).
+
+## Step 5: Commit the lockfile
+
+The lockfile change is the operator-visible record of which platform version is in use.
+
+```bash
+git add pnpm-lock.yaml package.json
+git commit -m "chore: upgrade @stravica-ai/digital-operator-pa to vX.Y.Z"
+```
+
+## Important notes
+
+- Operator content is never touched by the upgrade. If a release ships breaking changes that need operator-side adjustment, the release notes will list them and you'll surface them to the operator after Step 4.
+- This command only updates and verifies. It does not push.
+- If `pnpm update` fails (lockfile conflicts, registry auth, network), report the error verbatim. Do not retry blindly.
+- Major-version bumps are reviewed manually — for a major bump, route to the system-architect rather than running this command.