shraga 0.0.3 → 0.1.2

package/defaults/skills/scheduler.md

@@ -0,0 +1,192 @@
+---
+description: Create/manage scheduled jobs (cron/interval/once) and event-triggered automations via the internal API — incl. the event bus, built-in event sources (schedule.finished), per-trigger throttling, and the failure-notifier builtin.
+triggers:
+  - schedule a job
+  - cron job
+  - recurring task
+  - event trigger
+  - react to an event
+  - event-based job
+  - emit an event
+  - event bus
+  - schedule.finished
+  - notify on failure
+  - failure notifier
+  - throttle
+  - how do i schedule
+---
+
+You can manage scheduled jobs and event-triggered automations via the internal REST API. Requests are authenticated as the current user (your uid/email are injected into env automatically).
+
+## Auth Header
+
+All requests need: `-H "x-internal-token: $INTERNAL_API_TOKEN"`
+
+This authenticates you as the current session user — you'll have the same permissions they have (can only edit/delete your own schedules, system schedules are read-only).
+
+Base URL: `http://localhost:$PORT`
+
+## Endpoints
+
+### List all schedules
+```bash
+curl -s -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/schedules | jq .
+```
+Returns `{ schedules: [...], runningIds: [...] }`.
+
+### Get one schedule
+```bash
+curl -s -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/schedules/{id} | jq .
+```
+
+### Create a schedule
+```bash
+curl -s -X POST -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  http://localhost:$PORT/api/schedules \
+  -d '{
+    "name": "My task",
+    "enabled": true,
+    "trigger": { "kind": "cron", "expr": "0 9 * * 1-5", "tz": "Asia/Jerusalem" },
+    "task": { "kind": "prompt", "prompt": "Do the thing" }
+  }' | jq .
+```
+
+### Create an event-triggered schedule
+
+Instead of a time, an `event` trigger fires when a matching external event arrives (a webhook, a signal from another system, an internal watcher). The event payload is injected into the run.
+
+```bash
+curl -s -X POST -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  http://localhost:$PORT/api/schedules \
+  -d '{
+    "name": "Handle paid invoice",
+    "enabled": true,
+    "trigger": { "kind": "event", "source": "stripe", "match": { "type": "invoice.paid" } },
+    "task": { "kind": "prompt", "prompt": "An invoice was paid — thank the customer and log it." }
+  }' | jq .
+```
+
+- `source` (required) routes the event. `match` (optional) is an AND-filter of payload **dot-paths** → expected values (case-insensitive, e.g. `{"data.amount": "42"}`). No `match` → fires on any event with that source.
+- The event reaches the agent: for `prompt` tasks it's appended as a framed `Event data` JSON block; for `job` tasks it's passed as the `SHRAGA_EVENT` env var (never into the command string). `bash` tasks run their command as-is (no payload injected) — use a `prompt` or `job` task when the run needs the event data.
+- "Run now" works on event schedules too (fires without event data — handy for testing).
+
+### Create a one-time future schedule
+```bash
+curl -s -X POST -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  http://localhost:$PORT/api/schedules \
+  -d '{
+    "name": "Send weekly report",
+    "enabled": true,
+    "trigger": { "kind": "once", "at": 1748000000000 },
+    "task": { "kind": "prompt", "prompt": "Compile and send the weekly report" }
+  }' | jq .
+```
+Compute `at` as epoch milliseconds (e.g. `Date.now() + 3600000` for 1 hour from now). Must be in the future. Once-schedules auto-delete after completing.
+
+### Update a schedule
+```bash
+curl -s -X PUT -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  http://localhost:$PORT/api/schedules/{id} \
+  -d '{ "name": "New name", "trigger": { "kind": "cron", "expr": "0 8 * * *", "tz": "UTC" } }' | jq .
+```
+Partial update — only include fields to change. System schedules cannot be edited.
+
+### Delete a schedule
+```bash
+curl -s -X DELETE -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/schedules/{id} | jq .
+```
+System schedules cannot be deleted.
+
+### Enable/disable a schedule
+```bash
+curl -s -X POST -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  http://localhost:$PORT/api/schedules/{id}/toggle \
+  -d '{ "enabled": true }' | jq .
+```
+
+### Run a schedule now
+```bash
+curl -s -X POST -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  http://localhost:$PORT/api/schedules/{id}/run \
+  -d '{ "override": "optional override prompt" }' | jq .
+```
+
+### Cancel a running schedule
+```bash
+curl -s -X POST -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/schedules/{id}/cancel | jq .
+```
+
+### Get run history for a schedule
+```bash
+curl -s -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/schedules/{id}/runs | jq .
+```
+
+## Schedule Shape
+
+```typescript
+Trigger:
+  { kind: "once", at: <epoch_ms> }
+  { kind: "interval", everyMs: <ms> }       // min 1000
+  { kind: "cron", expr: "<cron>", tz: "<IANA_tz>" }
+  { kind: "event", source: "<name>", match?: { "<dot.path>": "<value>" } }
+
+Task:
+  { kind: "prompt", prompt: "<text>" }
+  { kind: "bash", command: "<cmd>" }
+
+Schedule: { id, name, enabled, trigger, task, scope, createdBy, nextRun?, lastRun?, runCount }
+```
+
+## Emitting events (to fire event-triggered schedules)
+
+Any caller that can present shraga auth can push an event onto the bus:
+
+```bash
+curl -s -X POST -H "Content-Type: application/json" -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  -H "X-Event-Id: optional-dedupe-key" \
+  http://localhost:$PORT/api/events/stripe \
+  -d '{ "type": "invoice.paid", "data": { "amount": 42 } }' | jq .
+```
+
+The `:source` path segment is the event source; the JSON body is the payload. `X-Event-Id` (optional) dedupes retried deliveries for ~5 min.
+
+For **vendor webhooks** that can't send shraga auth (Stripe, GitHub, …), add a data-side extension (`data/extensions/<name>.ext.ts`) that verifies the vendor's own signature, then calls `ctx.emitEvent(source, payload, { id })`. See `defaults/extensions/README.md` and the `stripe-webhook.ext.ts` example.
+
+## Built-in event sources
+
+The system emits these onto the bus automatically — use them as the `source` of an event trigger to react to the agent's own lifecycle:
+
+- **`schedule.finished`** — fired when any time/manual schedule run completes. Payload: `{ scheduleId, name, status, sessionId, error? }`. `status` is `ok` | `error` | `aborted`. Chain automations off it, e.g.:
+  ```json
+  { "trigger": { "kind": "event", "source": "schedule.finished", "match": { "status": "error" } },
+    "task": { "kind": "prompt", "prompt": "A scheduled run failed — investigate and post a summary." } }
+  ```
+  Runs that were *themselves* event-triggered do NOT emit `schedule.finished` — this prevents feedback loops, so you can't chain `schedule.finished` → event run → `schedule.finished` infinitely.
+
+## Throttling event triggers
+
+Event triggers accept an optional `throttle` that suppresses duplicate fires **before** a run is spawned:
+
+```json
+{ "trigger": { "kind": "event", "source": "schedule.finished", "match": { "status": "error" },
+               "throttle": { "byFields": ["name", "error"], "windowSec": 21600 } } }
+```
+
+The dedup key is built from the named payload fields (dot-paths), string-normalized (lowercased, digits→`#`, whitespace-collapsed) so values differing only by timestamps/ids collapse together. A fire is dropped if an identical key fired within `windowSec`. State lives in `data/state/trigger-throttle.json` and self-prunes. Empty `byFields` throttles on the source alone. For throttling inside a `job`/`bash` task (no trigger), use the `data/scripts/notifier-throttle.ts` helper instead.
+
+## Failure notification (built-in)
+
+`builtin-failure-notifier` is a shipped, **disabled-by-default** schedule that reacts to `schedule.finished` / `status:error`, triages the error (credential-expiry / rate-limit / data-issue / generic), and DMs the deployment owner — throttled to one alert per job+error per 6h. To use it:
+
+1. Enable it (toggle the schedule).
+2. Optionally set `SHRAGA_ALERT_SLACK_EMAIL` (the legacy `UNCLAW_ALERT_SLACK_EMAIL` is still honoured) (else it falls back to the first `data/whitelist.json` entry).
+3. Optionally edit its `task.prompt` to add deployment specifics (recipients, runbook links, severity rules, base URL) — your edits to a builtin's prompt and `enabled` flag survive upgrades; only `name`/`scope`/`createdBy` reconcile from code.
+
+## Notes
+
+- Event triggers never fire on a timer — they have no `nextRun` and wait for the bus. Per-trigger fires serialize (queue cap 5).
+- System schedules (`scope: "system"`) are read-only — you can toggle them but not edit/delete.
+- User schedules are scoped to their creator.
+- Schedules only execute on the instance where `DATA_SYNC_SCHEDULER_ACTIVE=true`.
+- `once` schedules auto-delete after completing — they don't linger in the list.
+- Always list schedules first to show the user what exists before making changes.

package/defaults/skills/self-aware.md

@@ -0,0 +1,136 @@
+You ARE shraga — a multi-user Claude Code web UI. You can read, modify, and manage your own source code and other repos.
+
+## Identity
+
+- **Project**: `shraga` (npm package name)
+- **GitHub**: `<org>/shraga` (set via `GITHUB_REPO_URL` env)
+- **GitHub identity**: bot account via `GITHUB_TOKEN`
+- **Prod host**: from `DEPLOY_HOST` / `DEPLOY_DOMAIN` env
+- **Prod path**: from `APP_DIR` env (default `/opt/shraga`)
+- **Prod user**: from `DEPLOY_USER` env
+- **Service**: from `APP_NAME` env (systemd, runs `bun run src/server/index.ts`)
+- **Deploy**: operator-provided (the deployment supplies its own release tooling — not shipped here)
+
+## Git workspaces (`data/git/`)
+
+The base clone at `data/git/<org>/<repo>/` is a **shared object store** — concurrent sessions reuse it, so editing or committing in it directly leaks one session's work into another's PR (the contamination this fixes). **The one hard rule: never edit or commit in the shared base tree.** The default that buys that for free is a per-session worktree keyed by `$SHRAGA_SESSION_ID` — isolation tracks concurrency, not dogma, so wherever sessions can overlap it's effectively always-on.
+
+### Clone or pull a repo (base object store)
+```bash
+REPO_DIR="$(pwd)/data/git/<org>/<repo>"
+if [ -d "$REPO_DIR/.git" ]; then
+  git -C "$REPO_DIR" fetch --prune
+else
+  mkdir -p "$(dirname "$REPO_DIR")"
+  git clone "https://x-access-token:$GITHUB_TOKEN@github.com/<org>/<repo>.git" "$REPO_DIR"
+fi
+```
+Only ever `fetch` into the base — never `checkout`/`commit`/edit there.
+
+### DEFAULT git flow — fetch fresh, worktree, isolate, PR back to base
+The base branch is per-repo and not always `main` — confirm the repo's actual base branch before branching (a deployment may document per-repo conventions in its own skill). The whole flow is four commands:
+```bash
+BASE_BRANCH=main  # confirm the repo's real base branch first — not every repo uses main
+REPO_DIR="$(pwd)/data/git/<org>/<repo>"
+git -C "$REPO_DIR" fetch origin "$BASE_BRANCH"             # always branch off the freshest base
+WT="$REPO_DIR/.wt/$SHRAGA_SESSION_ID"                      # session-keyed worktree under the base (never commit it)
+git -C "$REPO_DIR" worktree add "$WT" -b <feature-branch> "origin/$BASE_BRANCH" \
+  || (sleep 1 && git -C "$REPO_DIR" worktree add "$WT" -b <feature-branch> "origin/$BASE_BRANCH")  # retry once on ref-lock race
+# ALL reads/edits/commits/push happen inside $WT — never in $REPO_DIR
+git -C "$WT" worktree remove . --force                    # when done
+```
+Then read/edit/test/commit/push inside `$WT`, and open the PR via `mcp-github` **targeting the same base branch**.
+
+**Continuing an existing branch** (iterate on an open PR, follow-up commits) — check it out into the worktree instead of `-b`: `git -C "$REPO_DIR" fetch origin <branch> && git -C "$REPO_DIR" worktree add "$WT" <branch>`. Same isolation; you're just resuming a branch rather than cutting a new one.
+
+Per-session path means concurrent sessions never share a working tree; worktrees share the base object DB so disk cost is near-zero (`git worktree prune` clears any orphan). The retry covers the only shared-state risk: two `worktree add` racing on a ref lock.
+
+### Self-patching (your own code)
+Your own source is `<org>/shraga` in the git workspace (resolve `<org>` from `GITHUB_REPO_URL`). Use the **same isolated worktree flow as above** — never edit the base clone `$REPO_DIR` directly, and never edit `$APP_DIR` (the live instance).
+1. Fetch `<org>/shraga` base + `worktree add` into `$WT` (the DEFAULT flow above)
+2. Make changes inside `$WT`, run `bun run build` there to verify
+3. Push branch + create PR via `mcp-github` (audit trail / human review)
+4. **Apply to live** — checkpoint, copy, rebuild, restart. `$APP_DIR` is NOT a clone of origin;
+   it's a local-only git repo used purely as a rollback layer. You deliver code by copying the
+   built tree in (rsync), exactly like the deployment's own release tooling does — not by `git checkout`:
+```bash
+SRC="$(pwd)/data/git/<org>/shraga/.wt/$SHRAGA_SESSION_ID" # the worktree you built in, NOT the base clone
+bash "$APP_DIR/tools/checkpoint.sh" pre-apply              # local rollback point (snapshots .env/.tmp too)
+rsync -a --delete \
+  --exclude .git --exclude node_modules --exclude data --exclude vendor \
+  --exclude dist --exclude .tmp --exclude .env --exclude '.env.*' \
+  --exclude secrets --exclude .gitignore --exclude .github \
+  "$SRC/" "$APP_DIR/"
+cd "$APP_DIR" && bun install && bun run build
+sudo systemctl restart "$APP_NAME"
+```
+The restart will end the current session — deploy-restart-recovery handles reconnection.
+The PR stays open for human review.
+
+> **Never hand-restart yourself.** Use ONLY the single service-manager restart above — `sudo systemctl restart "$APP_NAME"`, or on launchd hosts `launchctl kickstart -k gui/$(id -u)/<label>`. NEVER `kill` the server PID and never start a second `bun run` instance from within your turn. SIGTERM triggers a graceful drain that waits up to 90s for active streams to finish — but *your own in-flight turn IS an active stream*, so the drain blocks on itself; combined with manual PID-killing, the old process wedges (socket closed, never rebinds) and the service manager won't auto-recover it (the wrapper still looks "running"). That self-downs the whole instance. If a mid-turn restart is unavoidable, prefer `tools/flip-restart.ts` (zero-downtime self-apply) or hand it to the user. A `tools/health-watchdog.sh` (where deployed) force-bounces a wedged port within ~2 min as a backstop — don't rely on it to mask a bad restart.
+
+**Revert if the apply broke something:**
+```bash
+cd "$APP_DIR"
+git reset --hard HEAD~1     # back to the pre-apply checkpoint (restores src + .env)
+bun install && bun run build && sudo systemctl restart "$APP_NAME"
+```
+List checkpoints with `git -C "$APP_DIR" log --oneline`; reset to any of them.
+
+## Key paths (in source)
+
+- `src/server/` — Express + WebSocket server, Claude agent SDK integration
+- `src/client/` — React 19 + Vite frontend
+- `src/server/claude.ts` — agent SDK session management
+- `src/server/mcp.ts` — MCP server injection and config
+- `src/server/skills.ts` — skill loading and injection
+- `defaults/` — canonical source for runtime-seeded dirs (see Architecture skill § "Defaults → Runtime Seeding Pattern")
+- `vendor/` — vendored MCP servers (mcp-firebase, mcp-github, mcp-slack, etc.)
+- `data/` — runtime data, git-tracked behavioral config via data-sync (skills, mcps, workspace, schedules, contacts, agent-config, whitelist)
+
+## Where one-off / custom code goes (NOT main `src/`)
+
+`src/` is the shared, generic shraga codebase — it ships to every deployment and the public repo. Ephemeral or deployment-specific code must NOT land there. Tell-tale signs you're about to pollute `src/`: a hardcoded deployment URL, a route not gated like its siblings, or code that solves a one-time setup need rather than a product capability.
+
+- **Runnable tool / one-off / reusable** → a Bun script under `scripts/` (seeded from `defaults/scripts/`). It can import the full server stack (`streamChat`, `getMcpConfig`, vendor MCP clients) — see `scripts/agent-once.ts`. **Reusable across deployments → `defaults/scripts/` (shared source). Specific to this deployment → the data subgit's `scripts/`** (e.g. `data/scripts/`), never `defaults/`. CLI scripts must end with `main().then(() => process.exit(0))`.
+- **Needs a public route on THIS instance's own URL** (an OAuth/manifest callback, a webhook receiver, or a public share/redirect page that must resolve on your deploy domain — a separate `Bun.serve` listener wouldn't be reachable behind the single tunneled port) → a **server extension**: drop a `*.ext.ts` exporting `default register(app, ctx)` into `data/extensions/`. The loader (`src/server/extensions.ts`) mounts it at boot **before** the SPA catch-all, and **hot-loads new files with no restart**. It lives in the data subgit (durable, synced) with zero `src/` edits. `ctx` provides `{ dataPath, requireAuth, log, app, emitEvent }` (`emitEvent` publishes onto the event bus — the way a verified vendor webhook becomes an agent run; see "Automation" below). See `data/extensions/README.md`, the shipped `selftest.ext.ts`, and the `stripe-webhook.ext.ts` event-bridge example. Still prefer a stored non-interactive key (fine-grained PAT, API key) over an OAuth dance whenever one exists.
+  > **Two gotchas — each silently returns the SPA:** (1) a route registered after `app.get('*')` is swallowed by the catch-all → HTML; the loader mounts extensions before it, so never add routes to `index.ts` after the catch-all. (2) a browser-navigated / externally-redirected route can't carry an `Authorization: Bearer` header, so `requireAuth` 401s → SPA fallthrough; make those routes public + a one-time `state`/signed nonce, and reserve `requireAuth` for routes the SPA calls via `fetch`.
+- **Other one-off HTTP needs** (a throwaway listener, or a tool surface) → a standalone `Bun.serve` script, or a proper MCP server (`/create-mcp`). Do NOT wire a route directly into `src/server/index.ts`.
+- **Visual artifact** (creative, card, mockup) → an HTML file with an `<!-- artifact: … -->` comment (see the `artifacts` skill).
+- **True throwaway** → `.tmp/artifacts/` (gitignored) on the machine.
+
+## Data Sync (`src/server/data-sync.ts`)
+
+Your behavioral config (skills, MCPs, schedules, contacts, workspace, agent-config, whitelist) is git-tracked in a dedicated repo (configured via `DATA_SYNC_REPO` env). This keeps all environments aligned.
+
+- **Auto-sync**: On startup, `dataSync.init()` pulls latest from the remote repo
+- **Write tracking**: Any file you modify in `data/` (skills, config, contacts) is auto-committed and pushed within 2s with an LLM-generated descriptive commit message
+- **Conflict resolution**: If remote changed the same file, Claude resolves conflicts holistically via API
+- **Pull on demand**: `POST /api/data-sync/webhook` triggers a pull (GitHub webhook fires on every push)
+- **Change history**: `data/git-log.json` (gitignored, reconstructed) contains recent commit log — read it to understand what changed and when. Also available via `GET /api/data-sync/log`
+- **Recovery**: If data seems stale or missing, trigger a pull by restarting the service or calling the webhook
+- **Integrity audit**: `bun run src/server/integrity-audit.ts [git-ref]` compares current data/ against a baseline commit. Detects missing files, truncated content, degraded JSON (fewer entries in schedules/contacts/skills-defaults/api-keys), and invalid JSON. Runs automatically after every data-sync init — check logs for `[data-sync] ⚠️ DATA INTEGRITY`. Use manually when investigating suspected data loss.
+
+### Scheduler gating
+Schedules sync across all envs but only **execute** where `DATA_SYNC_SCHEDULER_ACTIVE=true` (prod). Inactive envs load and serve schedules with their real `enabled` flags — they just never fire them (no timers armed). Manual "run now" still works anywhere. Event triggers respect the same gate (`fireEvent` no-ops unless active) so a webhook can't double-fire across blue-green.
+
+## Automation: how you get triggered
+
+Two layers cause you to run — know both, and which to reach for:
+
+**Schedules (`schedules.json`)** — a schedule is `trigger` + `task` (`prompt`/`bash`/`job`). One execution path, two trigger families:
+- **Time**: `cron` / `interval` / `once`.
+- **Event** (`{ kind:'event', source, match? }`) — fires when a matching event hits the event bus. `match` is an AND-filter of payload dot-paths → values. The event is injected into the run: a framed JSON block for `prompt` tasks, the `SHRAGA_EVENT` env var for `job` tasks.
+- Events arrive via `POST /api/events/:source` (auth-gated) or `ctx.emitEvent(source, payload, {id})` from a data extension — the latter is how a **vendor webhook** (verify its signature in the extension first) becomes an agent run. Bus + dispatcher: `src/server/events/`; fire path: `scheduler/engine.ts` `fireEvent()`. Full how-to (create / match / emit): the **scheduler** skill.
+- **Built-in lifecycle source**: the system auto-emits `schedule.finished` (`{ scheduleId, name, status, sessionId, error? }`) when a time/manual run completes — react to your own runs (e.g. `match: { status: "error" }` → notify). Event-triggered runs don't emit it (loop guard). More internal sources can be added with one `emitEvent()` at the milestone.
+
+**SDK hooks (`src/server/hooks.ts`)** — Claude Code's own hook mechanism, wired into your `query()`. These are *synchronous, in-turn interceptors* (currently a `PreToolUse` hook that forces long scripts to background) that can deny/modify a tool call before it runs. Different layer from the event bus: a hook guards/modifies a tool call *during your turn*; an event trigger reacts *after something happened*, in a (possibly new) session. Add a hook for a fast in-turn guard; add an event trigger for a cross-session reaction.
+
+## Rules
+
+- Always develop in `data/git/`, never edit live source directly — apply via checkpoint + rsync + rebuild (see Self-patching)
+- Prefer creating PRs over pushing directly to `main` — let the human review
+- After editing `defaults/skills/`, the change takes effect on next server restart (seed sync)
+- Keep files under 250 lines; split into modules
+- Use existing patterns — check similar code before inventing new approaches
+- CLI scripts (`data/scripts/*.ts`) must use `main().then(() => process.exit(0)).catch(...)` — Bun's fetch keep-alive pool holds the event loop open indefinitely without explicit exit

package/defaults/skills/shraga-know.md

@@ -0,0 +1,333 @@
+---
+description: "Audit shraga agent knowledge health. Default: session-scoped (check what this session touched). Pass 'full' or 'all' for exhaustive audit across all knowledge layers."
+argument-hint: "[full|all|freshness|skills|users|reconcile]"
+---
+
+# Shraga Knowledge Audit
+
+Diagnose the health of the shraga agent's runtime knowledge layer.
+
+**Scope: agent runtime only.** Audit `data/` (workspace, skills, contacts, config) and `defaults/` (agents, skills, system prompt). NEVER inspect `.claude/`, `CLAUDE.md`, `memory/`, or any dev-level Claude Code config — those belong to the developer, not the agent.
+
+## Modes
+
+- **Default (no args / "this session")**: Session-scoped audit. Check only what was touched in the current conversation — edited files, synced skills, new/changed endpoints, docs. Fast and focused.
+- **`full` or `all`**: Exhaustive audit across all knowledge layers (sections 1-8 below).
+- **Named section** (e.g. `freshness`, `skills`, `users`, `reconcile`): Run only that section from the full audit.
+
+## Session-Scoped Audit (default)
+
+Review your conversation history to identify files you created, edited, or synced. Then check:
+
+### A. Defaults→Data Sync
+
+For every file in `defaults/skills/` or `defaults/agents/` that was edited this session, verify the `data/` copy matches:
+
+```bash
+# For each edited defaults/ file, check its data/ counterpart
+for f in {list of edited defaults/skills/*.md files}; do
+  name=$(basename "$f")
+  data="data/skills/$name"
+  if [ -f "$data" ]; then
+    if ! diff -q "$f" "$data" > /dev/null 2>&1; then
+      echo "DRIFT: $name"
+    fi
+  else
+    echo "MISSING in data/: $name"
+  fi
+done
+```
+
+If drifted, sync immediately: `cp defaults/skills/X.md data/skills/X.md`
+
+### B. Docs Consistency
+
+For every behavioral change (new params, changed defaults, new endpoints):
+- Check that `defaults/skills/platform.md` (or relevant skill) documents the change
+- Check that `CLAUDE.md` key endpoints section is still accurate if endpoints changed
+- Check that any skill referencing the changed code is updated
+
+### C. Related Skills Impact
+
+If the session changed agent-facing behavior:
+- Grep `defaults/skills/` and `data/skills/` for references to the changed function/endpoint/param
+- Flag any skill that references old behavior
+
+```bash
+# Example: check for references to changed endpoint behavior
+grep -rn "api/chat" defaults/skills/ data/skills/ 2>/dev/null
+```
+
+### D. Scope Placement
+
+For every knowledge file written or edited this session, verify it landed in the right layer. Apply the test from `workspace.md`: *"would this be true/useful for a different user?"*
+
+- **User-scope content** (`users/{id}/user-context.md`, `users/{id}/...`) that is actually a universal convention, shared project fact, or team-wide rule → flag: should **lift to team** (`context.md` / `knowledge/`).
+- **Team-scope content** (`context.md`, `knowledge/*.md`) that is about one specific person (their preferences, their personal projects, a correction only they gave) → flag: should **drop to user** (`users/{id}/`).
+
+A single lesson can legitimately live in both (e.g. a correction you gave that is also a universal rule). The flag is for content sitting in the *wrong* or *only* layer. When in doubt, surface it rather than silently pass.
+
+### E. Quick Health Checks
+
+Run only on files touched this session:
+
+```bash
+# Check edited skills have valid frontmatter
+for f in {list of edited skill files}; do
+  head -5 "$f" | grep -q "description:" || echo "MISSING description: $f"
+done
+```
+
+### Output Format (session)
+
+```
+## Session Audit — {date}
+
+### Files Changed
+- {list from conversation history}
+
+### Sync Status
+- {file}: {in sync | DRIFTED → fixed | not applicable}
+
+### Docs
+- {endpoint/behavior}: {documented | MISSING docs | STALE docs}
+
+### Scope Placement
+- {file/lesson}: {correct layer | should LIFT to team | should DROP to user}
+
+### Action Items
+1. {fix}
+```
+
+---
+
+## Full Audit (pass `full` or `all`)
+
+Run each check section below. Report findings as a table per section. Skip sections not relevant to the focus argument.
+
+### 1. Freshness Check
+
+Check last-modified dates on critical files. Flag anything older than the threshold.
+
+```bash
+# Core workspace files (threshold: 3 days)
+stat -f "%Sm %N" -t "%Y-%m-%d" data/workspace/context.md data/workspace/open-questions.md data/workspace/tasks/tasks.md 2>/dev/null
+
+# Knowledge files (threshold: 7 days)
+find data/workspace/knowledge -name "*.md" -exec stat -f "%Sm %N" -t "%Y-%m-%d" {} \; 2>/dev/null | sort
+
+# User contexts (threshold: 7 days)
+find data/workspace/users -name "user-context.md" -exec stat -f "%Sm %N" -t "%Y-%m-%d" {} \; 2>/dev/null | sort
+```
+
+Report: file, last modified, days stale, status (fresh/stale/critical).
+
+### 2. Knowledge Index Completeness
+
+Every file in `data/workspace/knowledge/*.md` should be referenced in `data/workspace/context.md`'s knowledge table. Check for:
+- **Unindexed files**: exist in knowledge/ but not mentioned in context.md
+- **Dead references**: mentioned in context.md but file doesn't exist
+- **Status markers**: check if any files still say "DRAFT" or "not yet implemented" in their first 5 lines
+
+```bash
+# List all knowledge files
+ls data/workspace/knowledge/*.md 2>/dev/null | xargs -I{} basename {}
+
+# Check context.md references
+grep -o 'knowledge/[a-z0-9_-]*\.md' data/workspace/context.md 2>/dev/null
+```
+
+### 3. User Context Completeness
+
+For each user in `data/contacts.json`, check their context file exists and has substance.
+
+```bash
+# Map contacts to user dirs
+bun -e "
+const c = JSON.parse(require('fs').readFileSync('data/contacts.json','utf-8'));
+const { statSync, existsSync, readFileSync } = require('fs');
+for (const u of c) {
+  const p = 'data/workspace/users/' + u.id + '/user-context.md';
+  const exists = existsSync(p);
+  const lines = exists ? readFileSync(p,'utf-8').split('\n').length : 0;
+  const size = exists ? statSync(p).size : 0;
+  const mod = exists ? new Date(statSync(p).mtimeMs).toISOString().slice(0,10) : '-';
+  console.log([u.name || u.id, exists?'yes':'NO', lines+'L', size+'B', mod].join(' | '));
+}
+"
+```
+
+Flag: missing files, files <10 lines (sparse), files >7 days stale.
+
+### 4. Reconcile Sync Gap
+
+Compare the latest reconcile report against source files to find proposed-but-unapplied changes.
+
+```bash
+# Find latest reconcile report
+ls -t data/workspace/reconcile-reports/*.md 2>/dev/null | head -1
+```
+
+Read the latest report. For each proposed change:
+- Check if the target file was modified AFTER the report date
+- If not modified → flag as "pending sync"
+- Count: applied vs pending vs unknown
+
+### 5. Skills Health
+
+```bash
+# All skills with line counts and frontmatter presence
+for f in data/skills/*.md; do
+  name=$(basename "$f" .md)
+  lines=$(wc -l < "$f")
+  has_desc=$(head -10 "$f" | grep -c "description:")
+  has_triggers=$(head -20 "$f" | grep -c "triggers")
+  echo "$name | ${lines}L | desc:$has_desc | trig:$has_triggers"
+done
+```
+
+Check:
+- **Large skills (>200 lines) without triggers**: should be trigger-loaded, not always-injected
+- **Missing descriptions**: limits discoverability in skill index
+- **Defaults.json sanity**: check for duplicates, missing files
+
+```bash
+# Check defaults for duplicates and missing files
+bun -e "
+const d = JSON.parse(require('fs').readFileSync('data/skills-defaults.json','utf-8'));
+const names = d.map(e => typeof e === 'string' ? e : e.name);
+const dupes = names.filter((n,i) => names.indexOf(n) !== i);
+if (dupes.length) console.log('DUPLICATES:', dupes);
+const { existsSync } = require('fs');
+for (const n of [...new Set(names)]) {
+  if (!existsSync('data/skills/' + n + '.md')) console.log('MISSING:', n);
+}
+console.log('Total defaults:', names.length, '| Unique:', new Set(names).size);
+"
+```
+
+### 6. Defaults→Data Sync
+
+Check that canonical `defaults/skills/` and `defaults/agents/` are in sync with their `data/` copies.
+
+```bash
+# Skills: compare defaults that also exist in data/
+for f in defaults/skills/*.md; do
+  name=$(basename "$f")
+  data="data/skills/$name"
+  if [ -f "$data" ]; then
+    if ! diff -q "$f" "$data" > /dev/null 2>&1; then
+      echo "DRIFT: $name (defaults differs from data)"
+    fi
+  fi
+done
+
+# Agents: verify all defaults/agents/ are loadable
+for f in defaults/agents/*.md; do
+  name=$(basename "$f" .md)
+  echo "agent: $name"
+done
+```
+
+Flag any drifted skills — usually means `defaults/` was edited but not synced to `data/`.
+
+### 7. Scope Placement Audit
+
+Scan knowledge content for layer misplacement. Apply the test: *"would this be true/useful for a different user?"* — yes → team, only-about-this-person → user.
+
+- **Team files** (`context.md`, `knowledge/*.md`): scan for person-specific content — one user's preferences, personal projects, or a correction only they gave. Flag → should drop to that user's area.
+- **User files** (`users/{id}/user-context.md`): scan for universal conventions, shared project facts, or team-wide rules masquerading as personal notes. Flag → should lift to team scope.
+
+```bash
+# Heuristic: flag named-person references in team-scope knowledge
+grep -rniE "(my |i prefer|personal project|don't |never )" data/workspace/knowledge/*.md data/workspace/context.md 2>/dev/null | head -20
+```
+
+Treat hits as candidates, not verdicts — judge each by the test above. A lesson may legitimately live in both layers (universal rule + personal correction).
+
+### 8. Hot Context Size Estimate
+
+Estimate the total bytes injected into every conversation (hot context).
+
+```bash
+bun -e "
+const { readFileSync, existsSync } = require('fs');
+const defaults = JSON.parse(readFileSync('data/skills-defaults.json','utf-8'));
+let total = 0;
+const items = [];
+for (const entry of defaults) {
+  const name = typeof entry === 'string' ? entry : entry.name;
+  const capped = typeof entry === 'object' && entry.capped;
+  const cap = typeof entry === 'object' && entry.cap || 600;
+  const p = 'data/skills/' + name + '.md';
+  if (!existsSync(p)) { items.push([name, 'MISSING', 0]); continue; }
+  const size = readFileSync(p,'utf-8').length;
+  const effective = capped ? Math.min(size, cap) : size;
+  total += effective;
+  items.push([name, capped ? 'capped@'+cap : 'full', effective]);
+}
+for (const [n,mode,s] of items) console.log(n + ' | ' + mode + ' | ' + s + ' chars');
+console.log('---');
+console.log('Total hot skills: ~' + (total/1024).toFixed(1) + ' KB');
+// Add system prompt estimate
+const sp = existsSync('defaults/system-prompt.md') ? readFileSync('defaults/system-prompt.md','utf-8').length : 0;
+console.log('System prompt: ~' + (sp/1024).toFixed(1) + ' KB');
+console.log('Estimated hot total: ~' + ((total+sp+2000)/1024).toFixed(1) + ' KB (skills+prompt+roster+index)');
+"
+```
+
+Warn if hot total exceeds 15 KB.
+
+### Output Format (full)
+
+```
+## Knowledge Audit — {date}
+
+### Freshness
+| File | Modified | Days | Status |
+| ... | ... | ... | ... |
+
+### Index Coverage
+- Indexed: {N}/{total} knowledge files
+- Unindexed: {list}
+- Dead refs: {list}
+- Draft files: {list}
+
+### User Contexts
+| User | Exists | Lines | Size | Modified | Status |
+| ... | ... | ... | ... | ... | ... |
+
+### Reconcile Sync
+- Latest report: {date}
+- Proposed: {N} changes
+- Applied: {N} | Pending: {N}
+
+### Skills Health
+- Total: {N} | With description: {N} | With triggers: {N}
+- Large without triggers: {list}
+- Defaults duplicates: {list}
+
+### Defaults→Data Sync
+- Drifted: {list or "all in sync"}
+- Agents: {list}
+
+### Scope Placement
+- Misplaced (team→user): {list or "none"}
+- Misplaced (user→team): {list or "none"}
+
+### Hot Context
+- Total injected: ~{N} KB
+- Status: {OK | WARNING: exceeds 15KB}
+
+### Action Items
+1. {prioritized fix}
+2. {prioritized fix}
+...
+```
+
+## Pitfalls
+
+- `stat` flags differ on macOS vs Linux — the commands above use macOS format (`-f "%Sm"`). On Linux use `stat -c "%y %n"`.
+- Don't read full knowledge files for freshness — `stat` is enough.
+- Reconcile sync detection is heuristic (file mtime vs report date) — not a guaranteed "applied" check.
+- Some skills intentionally have no triggers (manual-only like `/reconcile`). Don't flag those.