shraga 0.0.3 → 0.1.1

package/defaults/scripts/backfill-slack-usernames.ts

@@ -0,0 +1,82 @@
+#!/usr/bin/env bun
+/**
+ * One-shot backfill: resolve missing userName on DM slack sessions.
+ * Reads slack-sessions.json to find DM channels, calls Slack API to get the user.
+ * Run: bun run scripts/backfill-slack-usernames.ts
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { dataPath } from '../src/server/paths.ts';
+
+const SLACK_BOT_TOKEN = process.env.SLACK_BOT_TOKEN || '';
+if (!SLACK_BOT_TOKEN) { console.error('SLACK_BOT_TOKEN required'); process.exit(1); }
+
+async function slackGet(method: string, params: Record<string, string>): Promise<any> {
+  const url = new URL(`https://slack.com/api/${method}`);
+  for (const [k, v] of Object.entries(params)) url.searchParams.set(k, v);
+  const res = await fetch(url, { headers: { Authorization: `Bearer ${SLACK_BOT_TOKEN}` } });
+  return res.json();
+}
+
+async function getUserName(userId: string): Promise<string | null> {
+  const data = await slackGet('users.info', { user: userId });
+  return data.user?.profile?.display_name || data.user?.real_name || data.user?.name || null;
+}
+
+const sessionsPath = dataPath('sessions.json');
+const slackMappingPath = dataPath('slack-sessions.json');
+
+const sessions = JSON.parse(readFileSync(sessionsPath, 'utf-8'));
+const slackMapping: Record<string, { sessionId: string; channel: string }> = JSON.parse(readFileSync(slackMappingPath, 'utf-8'));
+
+const dmChannelToSession = new Map<string, any>();
+for (const s of sessions) {
+  if (s.slackContext?.type === 'dm' && !s.slackContext.userName) {
+    for (const [, v] of Object.entries(slackMapping)) {
+      const entry = v as { sessionId: string; channel: string };
+      if (entry.sessionId === s.sessionId && entry.channel.startsWith('D')) {
+        dmChannelToSession.set(entry.channel, s);
+        break;
+      }
+    }
+  }
+}
+
+// Also find slack- sessions with no slackContext at all (legacy)
+for (const s of sessions) {
+  if (s.sessionId.startsWith('slack-') && !s.slackContext) {
+    for (const [, v] of Object.entries(slackMapping)) {
+      const entry = v as { sessionId: string; channel: string };
+      if (entry.sessionId === s.sessionId) {
+        if (entry.channel.startsWith('D')) {
+          s.slackContext = { type: 'dm' };
+          dmChannelToSession.set(entry.channel, s);
+        } else {
+          s.slackContext = { type: 'channel' };
+        }
+        break;
+      }
+    }
+  }
+}
+
+console.log(`Found ${dmChannelToSession.size} DM sessions to backfill`);
+
+const botAuth = await slackGet('auth.test', {});
+const botUserId = botAuth.user_id;
+
+for (const [channel, session] of dmChannelToSession) {
+  const history = await slackGet('conversations.history', { channel, limit: '5' });
+  if (!history.ok) { console.log(`  skip ${channel}: ${history.error}`); continue; }
+
+  const userMsg = (history.messages || []).find((m: any) => m.user && m.user !== botUserId && !m.bot_id);
+  if (!userMsg) { console.log(`  skip ${channel}: no user message found`); continue; }
+
+  const name = await getUserName(userMsg.user);
+  if (name) {
+    session.slackContext.userName = name;
+    console.log(`  ${session.sessionId.slice(0, 20)}... → ${name}`);
+  }
+}
+
+writeFileSync(sessionsPath, JSON.stringify(sessions, null, 2));
+console.log('Done. sessions.json updated.');

package/defaults/scripts/notifier-throttle.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+// Generic alert throttle — dedups repeated alerts for the same key within a window.
+// Use from any prompt/job/bash task that wants to avoid alert floods (event-trigger
+// schedules can instead use the built-in `trigger.throttle`, which suppresses BEFORE
+// an agent is spawned — see defaults/skills/scheduler.md).
+// Prints exactly one line: `DECISION=alert` or `DECISION=suppress`.
+// Usage: bun run data/scripts/notifier-throttle.ts --job "<name>" --error "<error>" [--window-hours 6]
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+function arg(name: string): string | undefined {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? process.argv[i + 1] : undefined;
+}
+
+const job = (arg('job') || 'unknown').trim();
+const error = (arg('error') || '').trim();
+const windowMs = Number(arg('window-hours') || 6) * 3600_000;
+const now = Date.now();
+
+// Signature: collapse whitespace, drop digits (timestamps/ids vary run-to-run),
+// lowercase, cap length — so "token expired on <date A>" == "<date B>".
+const sig = error.toLowerCase().replace(/\d+/g, '#').replace(/\s+/g, ' ').trim().slice(0, 120);
+const key = `${job}::${sig}`;
+
+const STATE = join(process.env.DATA_DIR || join(process.cwd(), 'data'), 'state', 'notifier-throttle.json');
+let state: Record<string, number> = {};
+try { if (existsSync(STATE)) state = JSON.parse(readFileSync(STATE, 'utf8')); }
+catch (e) { console.error('[notifier-throttle] read failed, starting fresh:', (e as Error).message); }
+
+// Self-maintaining prune: drop entries older than the window.
+for (const k of Object.keys(state)) if (now - state[k] > windowMs) delete state[k];
+
+const last = state[key];
+const suppress = last !== undefined && now - last < windowMs;
+
+if (!suppress) {
+  state[key] = now;
+  try { mkdirSync(dirname(STATE), { recursive: true }); writeFileSync(STATE, JSON.stringify(state, null, 2)); }
+  catch (e) { console.error('[notifier-throttle] write failed:', (e as Error).message); }
+}
+
+console.log(`DECISION=${suppress ? 'suppress' : 'alert'}`);
+process.exit(0);

package/defaults/scripts/summarize-conversations.ts

@@ -0,0 +1,5 @@
+import { summarizeConversations } from '../src/server/conversation-summarizer.ts';
+
+const force = process.argv.includes('--force');
+const result = await summarizeConversations({ force });
+console.log(`Done: ${result.summarized} summarized, ${result.skipped} skipped, ${result.errors} errors`);

package/defaults/shraga.config.ts

@@ -0,0 +1,29 @@
+/**
+ * Shraga deployment config — org-specific, lives in data/shraga.config.ts (gitignored).
+ *
+ * Global MCP servers are declared here — they apply to all users (read-only in UI).
+ * Users can add their own MCPs via the UI (stored per-user in mcps/{uid}.json).
+ *
+ * Two entry styles:
+ *   - Shorthand (vendor dir): { env: ['KEY1'] } → auto-resolves vendor/{name}/src/mcp/cli.ts
+ *   - Full: { command: 'bunx', args: ['@stripe/mcp'], env: { STRIPE_KEY: '' } }
+ *
+ * Env values resolve from process.env at startup (via .env or system env).
+ */
+import { defineConfig } from '../src/server/shraga-config.ts';
+
+// Agent settings (model, engine, thinking, effort, etc.) live in agent-config.json — UI-editable and the single source of truth.
+export default defineConfig({
+  mcps: {
+    // Shorthand — vendor dir convention (vendor/mcp-example/src/mcp/cli.ts):
+    // 'mcp-example': {
+    //   env: ['EXAMPLE_API_KEY', 'EXAMPLE_MODE'],
+    // },
+
+    // Full — explicit command/args:
+    // 'mixpanel': {
+    //   command: 'bunx',
+    //   args: ['mcp-remote', 'https://mcp.mixpanel.com/mcp', '--allow-http'],
+    // },
+  },
+});

package/defaults/skills/add-skill.md

@@ -0,0 +1,14 @@
+To add a new skill, create a Markdown file in the **absolute path** `<shraga folder>/data/skills/`:
+
+1. **File**: Create `<shraga folder>/data/skills/<skill-name>.md` using kebab-case naming (e.g. `code-review.md`, `write-tests.md`)
+   - ⚠️ Do NOT use workspace-relative paths like `data/skills/` — they won't be picked up by the app
+   - ⚠️ Do NOT use `.claude/skills/<name>/SKILL.md` — that structure is ignored
+2. **Content**: Write a concise system-prompt-style instruction that tells the agent *how* to perform the skill. Keep it short — ideally under 15 lines
+3. **Structure tips**:
+   - Start with a one-line summary of what the skill does
+   - Use bullet points or numbered steps for the procedure
+   - Include guidelines, constraints, or best practices the agent should follow
+   - End with any follow-up actions (e.g. "explain what you did")
+4. **Tone**: Write as direct instructions to the agent ("Do X", "Follow Y"), not as documentation for a human reader
+
+Reference existing skills in `<shraga folder>/data/skills/` for examples of the expected format and level of detail.

package/defaults/skills/artifacts.md

@@ -0,0 +1,116 @@
+# Artifacts — HTML Creative Builder
+
+You can create and iterate on visual HTML artifacts (ad creatives, banners, cards, etc.) that render live in the user's browser.
+
+## How It Works
+
+Write a self-contained HTML file using the `Write` tool. Include an artifact metadata comment as the **first line**:
+
+```html
+<!-- artifact: {"title": "Summer Sale Banner", "dimensions": [1080, 1080]} -->
+```
+
+The system detects this comment, registers the artifact, and shows it in a live preview panel.
+
+## To Update an Existing Artifact
+
+**Full rewrite** — use `Write` with the artifact `id` in the metadata:
+
+```html
+<!-- artifact: {"title": "Summer Sale Banner", "dimensions": [1080, 1080], "id": "art_xxx"} -->
+```
+
+**Incremental edit** — use the `Edit` tool on the same file path. The system re-reads the file after edit and refreshes the preview. The `<!-- artifact: ... -->` comment must remain in the file. This is the preferred approach for small changes (tweaking colors, text, spacing).
+
+The artifact ID is returned to you after creation. Always include it when doing a full rewrite.
+
+## Visual Feedback
+
+After creating or updating an artifact, export a screenshot to verify the visual result:
+
+```bash
+curl -s -o /tmp/artifact-preview.png -X POST \
+  "http://localhost:${PORT}/api/artifacts/${SHRAGA_SESSION_ID}/${ARTIFACT_ID}/export" \
+  -H 'Content-Type: application/json' \
+  -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  -d '{"dimensions": [1080, 1080]}'
+```
+
+- `$PORT`, `$SHRAGA_SESSION_ID`, and `$INTERNAL_API_TOKEN` are already in your environment.
+- Replace `$ARTIFACT_ID` with the actual artifact ID (e.g. `art_mpmgeqrw_o7tn8r`).
+- The `x-internal-token` header is **required** — without it you get `{"error":"Missing token"}`.
+
+Then read `/tmp/artifact-preview.png` to see the rendered output. This gives you visual context to self-correct layout issues, color contrast, etc.
+
+**Always screenshot after creation** to verify the result before telling the user it's ready.
+
+## Rules
+
+1. **Self-contained HTML** — everything in one file. No external dependencies except CDN links.
+2. **Always include Tailwind** — add this in `<head>`:
+   ```html
+   <script src="https://cdn.tailwindcss.com"></script>
+   ```
+3. **Set exact dimensions** — the HTML `<body>` should match the artifact dimensions. Use:
+   ```html
+   <body class="m-0 p-0 overflow-hidden" style="width: {W}px; height: {H}px;">
+   ```
+4. **Use web fonts from Google Fonts CDN** when needed.
+5. **Images**: use placeholder services (picsum.photos, placehold.co) or inline SVG/data URIs. Never reference local files.
+6. **File path**: keep it consistent for the same artifact so `Edit` works. Default to the user's folder: `{WORKSPACE_DIR}/users/{SHRAGA_USER_UID}/artifacts/{title-slug}.html`. To make an artifact visible to all users, use the shared root: `{WORKSPACE_DIR}/artifacts/{title-slug}.html` — only do this when explicitly asked.
+
+## Dimension Presets
+
+| Preset | Dimensions | Use Case |
+|--------|-----------|----------|
+| fb-feed | 1080×1080 | Facebook/Instagram feed post |
+| fb-story | 1080×1920 | Facebook/Instagram story |
+| fb-landscape | 1200×628 | Facebook link ad |
+| ig-square | 1080×1080 | Instagram square post |
+| ig-landscape | 1080×566 | Instagram landscape |
+| banner-leaderboard | 728×90 | Website banner |
+| banner-medium | 300×250 | Medium rectangle |
+
+## Template
+
+```html
+<!-- artifact: {"title": "My Creative", "dimensions": [1080, 1080]} -->
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <script src="https://cdn.tailwindcss.com"></script>
+  <style>
+    @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600;700&display=swap');
+    body { font-family: 'Inter', sans-serif; }
+  </style>
+</head>
+<body class="m-0 p-0 overflow-hidden" style="width: 1080px; height: 1080px;">
+  <!-- Your creative content here -->
+</body>
+</html>
+```
+
+## Export
+
+Artifacts can be exported to PNG via `POST /api/artifacts/$SHRAGA_SESSION_ID/$ARTIFACT_ID/export` (with `x-internal-token: $INTERNAL_API_TOKEN` header). The export uses Puppeteer server-side at the exact dimensions specified.
+
+## Iteration Flow
+
+1. Create the initial artifact with `Write`
+2. Screenshot it to verify the visual result
+3. Wait for user feedback
+4. Apply changes with `Edit` (preferred) or `Write` (full rewrite)
+5. Screenshot again to verify
+6. Repeat until approved
+7. Export to PNG when ready
+
+## Tips for Ad Creatives
+
+- Use bold, high-contrast text — it must be readable at small sizes
+- Keep copy short: headline (5-7 words max), subtext (1 line)
+- Strong CTA button with contrasting color
+- Use brand colors if provided
+- Leave breathing room — don't fill every pixel
+- Test with both light and dark backgrounds
+- For FB ads: text overlay should be <20% of image area

package/defaults/skills/code-review.md

@@ -0,0 +1,26 @@
+---
+description: Thorough code review of a file/diff/PR — correctness, security, performance, style; output as Issues/Suggestions/Nits.
+triggers:
+  - review this code
+  - code review
+  - review this diff
+  - review the PR
+  - review my changes
+  - check for bugs
+  - security review
+---
+
+You are performing a thorough code review. For each file or diff provided:
+
+1. Check for correctness, edge cases, and potential bugs
+2. Identify security issues (injections, auth bypasses, data exposure)
+3. Flag performance concerns (N+1 queries, unnecessary re-renders, blocking calls)
+4. Note style inconsistencies vs the surrounding codebase
+5. Suggest improvements — be specific, reference line numbers when possible
+
+Format your review as:
+- **Issues** (must fix): critical bugs or security problems
+- **Suggestions** (should fix): quality improvements
+- **Nits** (optional): minor style or naming tweaks
+
+Be concise. Skip praise. Focus on actionable feedback.

package/defaults/skills/communications.md

@@ -0,0 +1,54 @@
+# Communications Awareness
+
+You maintain a communications log to avoid duplicate or redundant **proactive** outreach. Scheduled reports and user-requested messages are always fine to send — dedup only applies to agent-initiated messages.
+
+## Communications Log
+
+File: `data/comms-log.jsonl` — append-only JSONL, one entry per outbound message.
+
+### Before sending a PROACTIVE message
+
+Dedup applies only when **you** decide to reach out (not when fulfilling a user request or running a scheduled job).
+
+1. **Read the comms log** — `Read data/comms-log.jsonl` (tail last 50-100 lines if large). If the file exceeds 500 lines, only read the last 100.
+2. **Check for recent similar outreach** — same recipient + similar topic within the last 24h = skip or significantly alter the message
+3. **For Slack** — the mcp-slack skill already requires reading channel history before posting (rule #6). That check + this log together cover both same-session and cross-session duplicates.
+
+### What counts as a duplicate (proactive only)
+
+- Same recipient + same topic/intent within 24h → **skip entirely**
+- Same recipient + related topic within 24h → **reference the prior message** instead of repeating context
+- Same channel + same information within 48h → **skip or reply in thread** to the original
+
+### After sending a message
+
+Append one line to `data/comms-log.jsonl`:
+
+```json
+{"ts":"2026-05-20T10:30:00Z","channel":"#general","channelId":"C123","recipient":"@alice","via":"slack","trigger":"proactive","summary":"Asked about Q1 report status"}
+```
+
+Fields:
+- **ts** — ISO timestamp
+- **channel** — human-readable channel/thread name
+- **channelId** — Slack channel ID (or email address for email, or E.164 phone number for phone/sms)
+- **recipient** — who the message is directed at (can be "channel" for broadcast)
+- **via** — `slack` | `slack-dm` | `email` | `phone` | `sms` (phone/sms via mcp-twilio)
+- **trigger** — `proactive` (agent-initiated), `scheduled` (cron/scheduled job), or `requested` (user asked for it). **Dedup only applies to `proactive`.**
+- **summary** — one-line summary of what was communicated (not the full message)
+
+### Housekeeping
+
+The log is append-only and can grow. When it exceeds ~500 lines, trim entries older than 7 days — recent history is what matters for dedup.
+
+### Rules (proactive messages)
+
+- **Never send the same information twice** to the same person/channel within 24h
+- **Never nag** — if you've already asked someone for something and they haven't responded, don't ask again the same day
+- **Consolidate** — if you have multiple things to tell the same person, batch them into one message
+- **Phone calls and SMS are real-world interruptions** — only place a proactive call/SMS (mcp-twilio) when explicitly asked or for a genuine, time-sensitive reason. Never cold-call or text someone you weren't told to contact, and never dial multiple people without being asked.
+
+### General
+
+- **Always log** — append to the comms log after every outbound message, regardless of trigger type
+- **Be self-aware** — read the log at the start of any task that involves communication to understand your recent activity

package/defaults/skills/context-audit.md

@@ -0,0 +1,87 @@
+---
+name: context-audit
+description: "Investigate agent context path issues — trace what's hot-loaded vs cold-loaded, find knowledge gaps, test fixes via API replay. Use when an agent session shows wrong behavior due to missing context."
+argument-hint: "[session URL or description of the failure]"
+---
+
+# Context Audit
+
+Diagnose *why* the agent didn't know something it should have, and fix the right layer.
+
+## When to Use
+
+- Agent gave a wrong/confused answer despite the knowledge existing somewhere
+- A skill or rule was ignored — need to determine if it was even loaded
+- After adding new knowledge, to verify it reaches the agent at the right time
+- Reviewing a prod session for context path failures
+
+## Shraga Context Architecture
+
+### Hot Path (always injected, every prompt)
+- `data/skills/{name}.md` where name is in `skills-defaults.json` — personality, identity, self-aware, pr-review
+- `<current_user>` block (uid, email, display name)
+- `<known_contacts>` from `data/contacts.json`
+- Workspace tree listing + `data/workspace/context.md` (full, uncapped)
+- User's `data/workspace/users/{uid}/user-context.md` (capped ~3000 chars)
+- MCP skill hint lines (name + resource URI, one line each)
+- Trigger-matched skills (via `matchTriggeredSkillNames` — prompt text matched against `triggers:` frontmatter; sticky per session — once matched, re-injected on every later turn via `SessionMeta.triggeredSkills`)
+- Skill index block (names + descriptions of all skills)
+
+### Cold Path (agent must explicitly Read or be triggered)
+- Non-default skills in `data/skills/` — loaded via trigger match, @mention, or manual Read
+- `data/workspace/knowledge/*.md` — domain deep-dives
+- Full MCP skill docs (`skill://name/workflow` resources)
+- Workspace files beyond context.md
+
+### Trigger Bridge (cold skill, hot injection)
+Skills with `triggers:` frontmatter get auto-injected when the user's prompt text matches any trigger string. This bridges hot/cold — the skill is cold by default but becomes hot when relevant.
+
+## Audit Process
+
+### 1. Reproduce the failure
+Read the session messages. Identify the exact moment the agent went wrong. Note:
+- What did the user ask?
+- What did the agent do instead?
+- What knowledge would have prevented the mistake?
+
+### 2. Trace the context path
+For the missing knowledge, determine:
+- **Does it exist anywhere?** (skill, workspace file, knowledge file, context.md)
+- **Is it hot or cold?** Check `skills-defaults.json`, trigger frontmatter, workspace injection
+- **If cold, should it have been triggered?** Check if user prompt text matches any trigger
+- **If triggered, did injection fire?** Check server logs for `[skills] Trigger matched:`
+
+### 3. Identify the gap type
+
+| Gap | Symptom | Fix Layer |
+|-----|---------|-----------|
+| Knowledge doesn't exist | Agent can't know it | Add to appropriate file (skill, context.md, knowledge/) |
+| Knowledge exists but is cold | Agent didn't load it | Add triggers to skill frontmatter, or move to hot path |
+| Knowledge is hot but ignored | Agent saw it, acted wrong | Strengthen wording, resolve contradictions, test with different models |
+| Wrong mental model | Agent misinterpreted the request | Add disambiguation rules to relevant skill |
+| Seed overwrites org data | Restart wipes customizations | Remove from `defaults/skills/` (org-only skills shouldn't have a defaults counterpart) |
+
+### 4. Apply fixes at the right layer
+- **Hot path** (personality.md, context.md): Generic behavioral rules, team/product basics
+- **Cold skill with triggers**: Domain-specific tool guidance (Slack, Firebase, Stripe)
+- **Knowledge files**: Deep reference material the agent loads on demand
+- **context.md pointers**: Keep context.md lean — point to cold files for details
+
+### 5. Verify via API replay
+Test the fix by replaying the failing prompt through `/api/chat`:
+```bash
+TOKEN=$(cat .tmp/.internal-token)
+curl -s http://localhost:3032/api/chat \
+  -H "Content-Type: application/json" \
+  -H "x-internal-token: $TOKEN" \
+  -d '{"prompt":"<the original failing prompt>","sessionId":"test-context-audit"}'
+```
+Check the response: did the agent now handle it correctly? If not, iterate.
+
+## Key Gotchas
+
+- **Seed overwrites**: `seedDefaults()` copies `defaults/skills/*.md` → `data/skills/` on every restart. Org-specific skills must NOT exist in `defaults/` or they'll be wiped.
+- **Token rotation**: Dev server `--watch` restarts regenerate `.tmp/.internal-token`. Re-read before each API call.
+- **Model sensitivity**: A fix that works on Opus may not work on Sonnet. Test on the prod model.
+- **Trigger matching is substring**: `" dm "` (with spaces) avoids false positives on words containing "dm". Design triggers carefully.
+- **Hot path budget**: Every hot-loaded skill consumes prompt tokens on every message. Keep hot content lean; use triggers for domain skills.

package/defaults/skills/debug.md

@@ -0,0 +1,10 @@
+You are debugging a problem. Follow this systematic approach:
+
+1. **Reproduce**: Confirm you understand the exact symptom and when it occurs
+2. **Hypothesize**: List the 2-3 most likely root causes, ranked by probability
+3. **Investigate**: Read relevant code, logs, and error messages before drawing conclusions
+4. **Isolate**: Narrow down to the smallest failing case
+5. **Fix**: Propose a targeted fix — don't refactor unrelated code
+6. **Verify**: Explain how to confirm the fix works
+
+Think out loud. Show your reasoning. If you need more information, ask specific questions rather than guessing.

package/defaults/skills/garden.md

@@ -0,0 +1,179 @@
+# Knowledge Gardening
+
+You are performing structural maintenance on the workspace knowledge base — deduplicating, restructuring, compressing, and cross-referencing. Think of this as defragmenting the team's shared memory: same information, better organized.
+
+**Budget: stay under 40 tool calls total.** Subagents handle the heavy reading.
+
+**Run garden BEFORE reconcile.** Garden cleans the house (dedup, compress, stale removal), then reconcile furnishes it (new content from conversations). Adding new content to a messy workspace compounds the mess.
+
+**Approval goes to owners.** Look up contacts tagged `owner` (i.e. `isOwner: true`) in `<known_contacts>` and send the report to their Slack DMs.
+
+## Phase 1: Snapshot & Checkpoint
+
+Create a git checkpoint so any changes can be reverted with `cd data && git revert HEAD`.
+
+```bash
+cd data && git add -A && git commit -m "garden: pre-checkpoint $(date +%Y-%m-%d)" --allow-empty
+```
+
+Read all workspace files to build your mental model:
+- `data/workspace/context.md`
+- `data/workspace/tasks.md`
+- `data/workspace/open-questions.md`
+- All `data/workspace/knowledge/*.md`
+- `ls data/workspace/users/` (just list, don't read all)
+
+Note file sizes. Files over 120 lines are split candidates.
+
+## Phase 2: Diagnose (parallel subagents)
+
+Spawn 3 Explore agents in parallel. Each gets a focused checklist and returns a short structured report.
+
+**Agent A — Duplication & cross-ref scan:**
+> Read data/workspace/context.md and every data/workspace/knowledge/*.md file. Report:
+> 1. Content that appears in BOTH context.md AND a knowledge file (quote both)
+> 2. Facts in knowledge/ files not indexed in context.md's knowledge table
+> 3. Cross-references that should exist between knowledge files but don't
+> Format: numbered list, each with file paths and quoted evidence.
+
+**Agent B — Staleness & hygiene:**
+> Today's date is {YYYY-MM-DD}. Read data/workspace/context.md, data/workspace/tasks.md, data/workspace/open-questions.md. Report:
+> 1. Dates older than 2 weeks from today (quote the line, note the date)
+> 2. Tasks marked done but still in active lists
+> 3. Questions marked resolved but still in Open section
+> 4. Sprint items that look completed but not moved to a "done" section
+> Format: numbered list with file:line references.
+
+**Agent C — Structure & coherence:**
+> Read data/workspace/context.md's knowledge table, then check each listed file exists under data/workspace/knowledge/. Read each knowledge file's first 10 lines. Report:
+> 1. Knowledge table entries pointing to files that don't exist
+> 2. Knowledge files that exist but aren't in the table
+> 3. Files over 120 lines (with line count)
+> 4. Files whose content has drifted from their stated purpose
+> Format: numbered list with file paths and line counts.
+
+## Phase 3: Synthesize & Propose
+
+Review all 3 agent reports. Pick the **best 2-3 actionable changes** (max 3, fewer is fine). Use this operations vocabulary:
+
+| Operation | What | Example |
+|-----------|------|---------|
+| **Dedup** | Same fact in context.md AND knowledge/ | Keep detail in knowledge/, replace context.md copy with pointer |
+| **Split** | File over 120 lines | Break into focused files, update index |
+| **Compress** | context.md section grew too detailed | Move to knowledge/ with pointer |
+| **Stale** | Outdated dates, resolved items still listed | Update or remove |
+| **Cross-ref** | Related files don't link to each other | Add "See also" pointers |
+| **Orphan** | Content in knowledge/ not in context.md index | Add to knowledge table |
+
+**Selection criteria** — pick changes that:
+- Reduce duplication (highest value)
+- Improve discoverability (orphans, missing cross-refs)
+- Remove noise (stale items)
+
+Skip anything speculative. Only propose what the evidence clearly supports.
+
+### Write the report
+
+```bash
+mkdir -p data/workspace/garden-reports
+```
+
+Write to `data/workspace/garden-reports/{YYYY-MM-DD}.md`:
+
+```markdown
+# Garden Report — {date}
+
+## Raw Agent Reports
+
+### Agent A — Duplication & Cross-ref
+{paste full agent A report verbatim}
+
+### Agent B — Staleness & Hygiene
+{paste full agent B report verbatim}
+
+### Agent C — Structure & Coherence
+{paste full agent C report verbatim}
+
+## Synthesis
+
+{2-3 sentences: what's the overall state? what patterns emerged across agents?}
+
+## Proposed Changes
+
+### 1. [{operation}] {title}
+**File(s):** {paths}
+**Evidence:** {which agent(s) flagged this, with their exact finding}
+**Current (verbatim):**
+> {exact quoted lines from the file — enough context to verify}
+
+**Proposed (verbatim):**
+> {exact replacement text — what the file will look like after}
+
+**Diff preview:**
+    - {removed lines}
+    + {added lines}
+**Why:** {rationale — why this change, why now, what improves}
+**Risk:** {what could go wrong — "none: purely additive" or "removes content: verify X is captured in Y first"}
+
+### 2. [{operation}] ...
+{same structure}
+
+### 3. [{operation}] ...
+{same structure}
+
+## Skipped Findings
+{list findings from agents that you chose NOT to act on, with 1-line reason why — so the reviewer can verify your judgment}
+```
+
+The full report is the audit trail. Raw agent reports let you verify the diagnosis. Diff previews let you verify the prescription. Skipped findings let you verify the triage.
+
+### Send Slack DM to owners
+
+Send a DM to each owner (from `<known_contacts>` with Slack IDs) using `post_slack_message`:
+
+```
+🌱 Knowledge Garden — {date}
+
+{N} raw findings → {N} proposed changes (max 3).
+Full audit trail: data/workspace/garden-reports/{date}.md
+
+1. [{operation}] {1-liner} — {file}
+   Risk: {none/low/medium}
+   Diff: -{removed summary} +{added summary}
+2. [{operation}] {1-liner} — {file}
+   Risk: {none/low/medium}
+   Diff: -{removed summary} +{added summary}
+3. [{operation}] {1-liner} — {file}
+   Risk: {none/low/medium}
+   Diff: -{removed summary} +{added summary}
+
+Skipped {N} lower-priority findings (see report).
+Reply with numbers to approve (e.g. "1,3") or "all".
+```
+
+**STOP here. Do not apply changes. Wait for user approval.**
+
+## Phase 4: Apply (only when user approves)
+
+When the user replies with numbers (e.g. "1,3") or "all":
+
+1. Load the report from `data/workspace/garden-reports/{date}.md`
+2. Apply only the approved changes using Edit tool
+3. Commit:
+
+```bash
+cd data && git add -A && git commit -m "garden: $(date +%Y-%m-%d) — <brief summary of applied changes>"
+```
+
+**Recovery:** `cd data && git revert HEAD`
+
+## Guidelines
+
+- **Propose, don't act** — never edit workspace files without explicit approval
+- **Max 3 changes** — gardening is incremental; run again tomorrow
+- **Preserve voice** — match existing tone of each file
+- **context.md is the hot index** — keep it under 100 lines of actual content; push detail to knowledge/
+- **knowledge/*.md files hold detail** — keep each under 120 lines; split if growing
+- **Don't touch user-scope** — `users/{id}/` is reconcile's domain
+- **Cite evidence** — every proposal references the agent finding that supports it
+- **Don't fabricate** — restructure existing content, don't invent new facts