shraga 0.0.3 → 0.1.2

package/defaults/skills/github-contributor.md

@@ -0,0 +1,35 @@
+# GitHub Contributor
+
+You can act as an autonomous contributor on GitHub repos. Issues and PRs arrive as conversation turns (via the GitHub webhook); your final reply text is posted back as a comment on the thread.
+
+## Trust tiers (resolved from GitHub, shown in the prompt)
+
+- **autonomous** — author is a repo collaborator (write+). You may implement, verify, merge, and self-apply.
+- **gated** — author has a previously merged PR but isn't a collaborator. Implement, verify, open the PR — then STOP and request owner approval (Slack) before any merge.
+- **default** — unknown author. The platform queues these for human triage; you won't see them until a human engages.
+
+Hard rules regardless of tier:
+- Foreign PRs (code you didn't write) are never merged below collaborator trust.
+- Changes touching auth, deploy tooling, secrets handling, or trust logic always require owner approval, even from trusted authors.
+
+## Workflow for an issue
+
+1. Investigate in a clone/worktree of the repo — never in the live app dir.
+2. Implement on a branch; push; open a PR with `gh` (your `GITHUB_TOKEN` identity). Commit only with your configured git identity (inherited from global gitconfig) — if a clone has none, copy it from the global config; NEVER invent a name/email (unregistered emails break commit attribution and CI/deploy author checks).
+3. Verify before proposing a merge: `bun run tools/shadow-verify.ts --pr <N>` — builds, typechecks, tests, and boots the branch as an isolated passive instance (throwaway data dir, no secrets). Include the YAML verdict in your PR/issue comment.
+4. Keep the issue thread updated; be concise and factual in comments.
+
+## Self-apply (autonomous tier only)
+
+After merging, apply to the running instance with zero downtime:
+
+```
+bun run tools/flip-restart.ts --restart-cmd "<service restart command>"
+```
+
+This holds traffic on a passive old-code twin during the restart and auto-falls-back to old code if the new code is unhealthy (exit 3 — report it and leave traffic as-is; recovery steps are in the script output).
+
+## Notes
+
+- `tools/shadow-verify.ts <branch>` also works for branches; `--keep` leaves the instance up for inspection; `--env <file>` injects an env file (never for foreign code).
+- One session per issue/PR thread — comments on the same thread continue your session.

package/defaults/skills/identity.md

@@ -0,0 +1,30 @@
+## Contact Registry
+
+A built-in contact registry at `data/contacts.json` automatically tracks everyone you interact with across all channels.
+
+### How it works
+
+- **Operators** (whitelisted team members) are seeded at startup from `data/whitelist.json` with `isOperator: true`
+- **Owners** are a subset of operators flagged with `isOwner: true` — the primary authority over the knowledge base (e.g. garden approvals route to owners only)
+- **External contacts** are auto-created on first encounter (Slack message, inbound email, etc.)
+- **Cross-channel merge**: when a Slack user's profile email matches an existing email-only contact, they merge into one record
+- The `<current_user>` block in every prompt identifies who is speaking
+- The `<known_contacts>` block lists all known people — operators and contacts — so you can recognize anyone mentioned in conversations
+- Slack @mentions are resolved to `@Name (operator)` or `@Name` — the role tag tells you who is internal
+
+### Contact record
+
+Each contact has: `emails[]`, `slackIds[]`, `name`, `isOperator`, `isOwner` (optional), `firstSeen`, `lastSeen`.
+
+### Identity awareness
+
+When you encounter a person mentioned in a message or thread:
+- Check `<known_contacts>` first — if they're listed, you already know them and their role
+- Read `data/contacts.json` for full details (email, Slack IDs, history) when you need to take action involving them
+- Use workspace files (e.g. `data/context.md`) for deeper context like responsibilities, communication preferences, or team dynamics
+
+### What NOT to do
+
+- Do NOT create manual identity files — `data/contacts.json` is the sole source of truth
+- Do NOT scan the Slack workspace to build a user list — contacts are created on-demand
+- Do NOT use MCP tools to look up team member emails — they're already in the registry

package/defaults/skills/mcp-server.md

@@ -0,0 +1,62 @@
+# MCP Server & API Keys
+
+Shraga exposes an embedded MCP endpoint at `POST /mcp` so external Claude clients (Claude Desktop, Claude Cloud, other MCP consumers) can access workspace, skills, sessions, schedules, and run prompts remotely.
+
+## API Keys
+
+Keys use the `uck_` prefix and are stored in `data/api-keys.json`.
+
+**REST endpoints** (require Firebase auth or internal token):
+- `POST /api/api-keys` — create a key. Body: `{ "label": "my-key" }`. Returns full key (only shown once).
+- `GET /api/api-keys` — list keys (key values masked).
+- `DELETE /api/api-keys/:id` — delete a key (owner or server owner only).
+
+**Generating a key via curl** (from an agent session):
+```bash
+curl -X POST "$SHRAGA_BASE_URL/api/api-keys" \
+  -H "Content-Type: application/json" \
+  -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  -d '{"label":"claude-desktop"}'
+```
+
+## Connecting Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (uses stdio bridge — Claude Desktop doesn't support HTTP URL transport):
+```json
+{
+  "mcpServers": {
+    "shraga": {
+      "command": "bun",
+      "args": ["run", "/path/to/shraga/src/mcp-stdio-bridge.ts"],
+      "env": {
+        "MCP_URL": "https://your-host",
+        "MCP_API_KEY": "uck_..."
+      }
+    }
+  }
+}
+```
+
+## Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_sessions` | List conversations with pagination |
+| `get_sessions_messages` | Read conversation history |
+| `get_workspace` | List workspace file tree |
+| `get_workspace_file` | Read a workspace file |
+| `put_workspace_file` | Write/update a workspace file |
+| `get_workspace_search` | Search file contents for text (case-insensitive) |
+| `get_skills` | List agent skills with metadata |
+| `get_skills_read` | Read full skill content |
+| `put_skills_write` | Create/update a skill |
+| `get_schedules` | List scheduled jobs |
+| `post_schedules_run` | Trigger a schedule run |
+| `post_chat` | Talk to the agent — conversational, multi-turn via sessionId |
+| `get_config` | Read agent configuration |
+
+## Source
+
+- `src/server/mcp-server.ts` — tool definitions + Express bridge
+- `src/server/api-keys.ts` — API key CRUD
+- `.claude/skills/mcp-shraga/SKILL.md` — MCP skill resource

package/defaults/skills/mcps-sync.md

@@ -0,0 +1,105 @@
+---
+description: Sync MCP server repos — clone new, push+pull existing, register in config, report missing env vars. Run periodically to keep MCP servers up to date.
+triggers:
+  - sync mcps
+  - mcps sync
+  - setup mcps
+  - provision mcps
+  - install mcp servers
+  - update mcp repos
+---
+
+# MCP Sync
+
+Sync all `mcp-*` repos from GitHub, register in shraga config, report missing env vars.
+Run this periodically to keep MCP servers up to date.
+
+## Steps
+
+### 1. Discover repos from GitHub
+
+```bash
+gh repo list <your-org-or-user> --limit 100 --json name,sshUrl -q '.[] | select(.name | startswith("mcp-"))'
+```
+
+Include all `mcp-*` repos — the `mcp-` prefix is the convention this skill keys on. If your MCP
+servers live elsewhere (a different org, or one repo per server under a monorepo), adjust the query
+to match; everything downstream only needs a name and a clone URL.
+
+### 2. For each repo: clone, push, or pull
+
+Target directory: wherever you keep the checkouts (e.g. `~/Projects/`). Keep it consistent — the
+config paths registered in step 3 point at it.
+
+**If not cloned yet:**
+```bash
+git clone <sshUrl> <target>/<name>
+bun install --cwd <target>/<name>
+```
+
+**If already cloned:**
+```bash
+# Push any committed local changes first
+git -C <target>/<name> push 2>/dev/null || true
+# Then pull latest
+git -C <target>/<name> pull --ff-only
+```
+
+If pull fails due to divergence, report it and skip (don't force).
+
+### 3. Symlink into vendor/
+
+For each repo, ensure `vendor/<name>` symlinks to the cloned repo:
+```bash
+# Check if symlink exists and points correctly
+readlink vendor/<name>
+# Create/update if needed
+ln -sf <target>/<name> vendor/<name>
+```
+
+### 4. Register new MCPs in shraga.config.ts
+
+Read `data/shraga.config.ts`. For each repo not already in the `mcps` block:
+
+1. Detect required env vars from `.env.example`:
+   ```bash
+   grep -E '^[A-Z_]+=.' <repo>/.env.example | cut -d= -f1
+   ```
+
+2. Detect CLI entry point (most use `src/mcp/cli.ts`, `mcp-firebase` uses `src/cli.ts`)
+
+3. Add shorthand entry:
+   ```typescript
+   'mcp-name': {
+     env: ['VAR1', 'VAR2'],
+   },
+   ```
+
+**Never overwrite existing entries.** Only add new ones.
+
+### 5. Report status
+
+Print a summary table:
+
+```
+MCP Sync Results:
+  mcp-slack      up to date
+  mcp-firebase   pulled 3 commits
+  mcp-pdf        cloned (NEW)
+  mcp-cursor     pushed 1, pulled 2
+
+Missing env vars (add to .env):
+  mcp-stripe     STRIPE_SECRET_KEY
+  mcp-gmail      GOOGLE_SERVICE_ACCOUNT, GMAIL_USER_EMAIL
+
+All configured: mcp-slack, mcp-firebase, mcp-google-drive
+```
+
+## Rules
+
+- Never write secrets or API key values — only report env var **names**
+- Use SSH URLs for cloning (check remote format: `github.com-personal` or `github.com`)
+- Don't modify existing entries in shraga.config.ts
+- Don't force-push or force-pull — report conflicts
+- After adding new MCPs, remind user to restart shraga
+- Check `.env` in the shraga project root for existing env var values

package/defaults/skills/plan.md

@@ -0,0 +1,9 @@
+Before writing any code, produce a concise implementation plan:
+
+1. **Goal**: One sentence summary of what we're building
+2. **Approach**: The chosen strategy and why (mention alternatives considered)
+3. **Steps**: Numbered list of concrete implementation steps
+4. **Files affected**: Which files will be created or modified
+5. **Risks / open questions**: Anything that could go wrong or needs clarification
+
+Keep the plan short — it should fit on one screen. Once the plan is agreed upon, proceed with implementation.

package/defaults/skills/platform.md

@@ -0,0 +1,177 @@
+---
+description: Shraga platform features — directives, config, thinking/reasoning, sessions, internal API, MCP
+triggers:
+  - directive
+  - how do i switch model
+  - how do i enable thinking
+  - reasoning
+  - effort
+  - config panel
+  - platform feature
+  - internal api
+  - mcp tools
+  - deferred tools
+  - ToolSearch
+  - new conversation
+  - spawn conversation
+---
+
+# Shraga Platform Features
+
+Reference for user-facing capabilities. Use this when users ask "how do I…" about the platform itself.
+
+## Directives
+
+Users can prefix any message with `[directives]` to override settings. Parsed server-side before the prompt reaches you. Directives stick to the session: once set, they apply to all later turns of that conversation (a new directive overrides the stored one).
+
+**Syntax:** `[directive1, directive2, ...] rest of the message`
+
+### Positional directives
+
+| Position | What | Examples |
+|----------|------|----------|
+| 1st | Model alias | `fable`, `opus`, `sonnet`, `haiku`, `fable-5`, `opus-4-8`, `opus-4-7` |
+| 2nd | Max turns (integer) | `5`, `20`, `100` |
+
+### Named directives
+
+| Directive | Values | Effect |
+|-----------|--------|--------|
+| `think` / `adaptive` | — | Enable adaptive thinking for this message |
+| `nothink` | — | Disable thinking for this message |
+| `thinking:VALUE` | `adaptive`, `enabled`, `disabled` | Set thinking mode explicitly |
+| `effort:VALUE` | `low`, `medium`, `high`, `max` | Set reasoning effort level |
+| `model:VALUE` | Any alias | Override model |
+| `turns:VALUE` | Integer | Override max turns |
+
+### Examples
+
+- `[opus] review this PR` — use Opus for this message
+- `[opus, 5] quick answer` — Opus, max 5 turns
+- `[think] explain the tradeoffs` — enable thinking
+- `[opus, think, effort:max] deep analysis` — Opus + thinking + max effort
+- `[nothink] just do it` — disable thinking
+- `[haiku, 3] one-liner summary` — Haiku, 3 turns
+
+## Config Panel (sliders icon)
+
+Persistent settings that apply to all messages until changed:
+
+| Setting | Options | Default |
+|---------|---------|---------|
+| Model | Fable 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6, Haiku 4.5 | Sonnet 4.6 |
+| Permission Mode | Accept Edits, Plan, Bypass All | Accept Edits |
+| Max Turns | 1–200 | 50 |
+| Thinking | Adaptive, Enabled, Disabled | Off |
+| Effort | Low, Medium, High, Max | Default |
+| Allowed Tools | Comma-separated list | All |
+| Skill Discovery | On/Off | On |
+| System Prompt | Free text appended to system prompt | Empty |
+
+Directives override config and persist for the session. On a session's first turn, the resolved engine/model/turns/thinking are pinned to the session — reopening it from history resumes the exact same shape even if config defaults change later.
+
+## Thinking / Reasoning
+
+When enabled (via config or `[think]` directive), the model produces extended reasoning before responding. Thinking blocks appear as collapsible violet panels in the chat UI, hidden by default behind the details toggle (eye icon).
+
+- **Adaptive** — model decides when to think (recommended)
+- **Enabled** — always produce thinking
+- **Disabled** — never produce thinking
+
+**Effort** controls reasoning depth: `low` (fast) → `max` (thorough). Can be set independently of thinking.
+
+## Artifacts
+
+HTML files with an `<!-- artifact: {...} -->` comment are rendered in a side panel. See the `artifacts` skill for details.
+
+## Machine Stats
+
+The sidebar footer (next to the version) shows a live CPU/memory sparkline of the **host machine** — a 10-minute trend so issues (swap thrash, runaway builds) are visible at a glance. A single server-side sampler (`src/server/stats.ts`) samples the host every 5s and broadcasts each point over WS; clients seed from `GET /api/stats` (cached ring buffer) and never poll the box themselves. Colors: green <75%, amber ≥75%, red ≥90%.
+
+## Sessions
+
+- Each conversation is a session with a unique ID
+- Sessions persist as JSONL in `data/conversations/`
+- Share via URL: `?session=SESSION_ID`
+
+### Starting a New Conversation
+
+You can spawn a new independent conversation from within a running session:
+
+```bash
+curl -X POST http://localhost:$PORT/api/chat \
+  -H "x-internal-token: $INTERNAL_API_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"prompt": "your task here"}'
+```
+
+Omit `sessionId` to create a fresh conversation. The new session runs with full agent capabilities (tools, MCP, skills).
+
+**Default (async)**: returns `{ sessionId, status: "accepted" }` immediately; the agent runs in the background. Add `"callbackUrl": "..."` to get POSTed the result when done.
+
+**Sync mode**: add `"sync": true` to wait for the full response: `{ sessionId, text, blocks }`.
+
+## Internal API Auth
+
+A random `INTERNAL_API_TOKEN` is generated on startup and set in your environment. Use it to call any authenticated endpoint from within a session:
+
+```bash
+curl -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/...
+```
+
+The request authenticates as the current session user automatically.
+
+## MCP Tools
+
+MCP servers are configured per-deployment in `data/mcps/*.json`. All MCP tools are available to you, but most are **deferred** — you must call **ToolSearch** to load their schemas before invoking them. ToolSearch is always available.
+
+Startup logs show `[claude] MCP: name:status` for each server. If a tool call fails with `InputValidationError`, you likely forgot to ToolSearch it first.
+
+## Contextual Triggers
+
+Skills can trigger based on conversation context, not just message keywords. The platform injects context tags before matching:
+
+| Tag | Source | Example |
+|-----|--------|---------|
+| `source:slack` | All Slack messages | |
+| `source:web` | Web UI messages | |
+| `source:api` | API endpoint messages | |
+| `channel:#name` | Slack channel name | `channel:#support` |
+| `dm:true` | Slack DMs | |
+| `thread:ts` | Slack thread timestamp | `thread:1780293395.005369` |
+| `user:email` | User's email | `user:alice@co.com` |
+
+Triggers use simple substring matching — any trigger string that appears in the context+message input will activate the skill.
+
+Example skill with contextual trigger:
+```yaml
+---
+description: Support channel guidelines
+triggers:
+  - "channel:#support"
+---
+Be empathetic. Acknowledge the issue before troubleshooting...
+```
+
+You can combine contextual and keyword triggers in the same skill. You can also create contextual skills on behalf of users — write a skill file in `data/skills/` with the appropriate trigger.
+
+## Ephemeral Skills (TTL)
+
+Skills can have an expiration time via the `expires` frontmatter field (ISO 8601). After expiry, the skill stops triggering, is hidden from the skill index, and is purged on server restart.
+
+```yaml
+---
+description: Temporary pricing empathy for #sales
+triggers:
+  - "channel:#sales"
+expires: 2026-06-02T18:00:00Z
+---
+When discussing pricing, be empathetic about budget constraints...
+```
+
+Use cases:
+- Temporary tone/behavior for a specific channel or thread topic
+- Time-limited campaign responses
+- Short-lived instructions that shouldn't persist
+
+To create an ephemeral skill: write a skill file with `expires` set to the desired ISO 8601 datetime. Compute from natural language (e.g. "for the next 2 hours" → now + 2h).

package/defaults/skills/reconcile.md

@@ -0,0 +1,239 @@
+# Knowledge Reconciliation
+
+You are performing a workspace knowledge reconciliation — auditing what the team knows, learning from recent conversations, and keeping the knowledge base clean and current. Think of this like how the human mind works during sleep: rearranging information, strengthening important connections, discarding noise.
+
+**Budget: stay under 40 tool calls total.** Prioritize breadth over depth — skim, don't deep-read.
+
+**Run garden BEFORE reconcile.** If both are scheduled, garden cleans the structure first, then reconcile adds new content into a clean workspace.
+
+## Phase 1: Scan Conversation Summaries
+
+The summarizer job writes `.summary.md` files next to each conversation JSONL. Start there — they're short, dense, and optimized for recall.
+
+```bash
+ls -lt data/conversations/*.summary.md 2>/dev/null | head -20
+```
+
+Read the most recent summaries (up to 10). These are your primary source for what happened recently. If a summary mentions something interesting that needs more context, peek at user and assistant text only (filter out tool calls):
+
+```bash
+tail -200 data/conversations/{sessionId}.jsonl | jq -s '.[] | select(.role == "user" or .role == "assistant") | .blocks[]? | select(.type == "text") | .text' | head -20
+```
+
+But prefer summaries — only dive into full JSONL when the summary isn't enough. Skip tool_use and tool_result blocks entirely.
+
+## Phase 2: Extract User Learnings
+
+For each conversation summary, extract learnings about **every person involved** — not just the `user:` in the header. A conversation between Alice and the agent might teach you about Bob's communication style, Carol's debugging approach, or Dave's priorities. Learnings about a person can come from:
+- **Direct conversations** — the person is the `user:` (e.g. Bob DMing the agent on Slack)
+- **Indirect mentions** — someone else discusses them, their work, their style, or corrects the agent's behavior toward them
+- **Observed interactions** — Slack threads, escalations, cross-team exchanges referenced in the conversation
+
+Think like a colleague building a mental model of everyone on the team, not just whoever you're currently talking to.
+
+### What to look for
+
+**Corrections & steering (highest priority):**
+Scan for moments where the user redirected the agent: "no, do X instead", "don't do that", "that's wrong", "use Y not Z". These become hard rules in the user's Corrections section. Be specific — "use YAML not JSON for reports" not "prefers structured formats."
+
+**Decision patterns:**
+How did they approach problems? What did they investigate first? What did they prioritize? What tools/data sources did they reach for? Example: "Alice pulled metrics from Google Sheets, not the analytics dashboard" → learns information diet + source of truth.
+
+**Expertise signals:**
+What domain knowledge did they demonstrate? What did they teach the agent? What level of detail did they operate at?
+
+**Taste & style:**
+How much detail do they want in responses? What quality bar do they hold? How do they communicate — terse or detailed? Did they push for polish or accept "good enough"?
+
+**Current focus:**
+What are they actively working on? What keeps coming up across conversations?
+
+### Map ALL mentioned people to directories
+
+Use `data/contacts.json` to map names/emails to contact IDs. The contact `id` is the user directory name under `data/workspace/users/{id}/`.
+
+```bash
+cat data/contacts.json | jq -r '.[] | "\(.emails[0] // "no-email") → \(.id) (\(.name))"'
+```
+
+Build a list of **every team member** mentioned across all summaries — not just session owners. Then read each relevant user's current `user-context.md` to avoid duplicating what's already captured. Propose updates for every person you learned something new about.
+
+### Categorize into sections
+
+Organize proposed updates into the user-context categories: Who they are, How they operate, Corrections, Their taste, What they're working on. Not every conversation yields every category — only propose what you actually observed.
+
+**Important:** User-learning extraction is always fresh — even if a previous reconcile report exists for today with team-scope proposals. Do NOT skip user extraction just because prior proposals exist. Prior reports may not have done user extraction at all. Always scan summaries for learnings about every mentioned person and propose user-scope updates regardless of prior passes.
+
+## Phase 2.5: Skill Reflection (from traces)
+
+The summarizer writes `.trace.yaml` files with structured session data (tools used, corrections, edge cases, novel patterns). Use these for skill-level analysis.
+
+**Budget: max 8 tool calls for this phase.**
+
+List recent traces:
+
+```bash
+find data/conversations -name "*.trace.yaml" -mtime -1 -exec ls -lt {} + 2>/dev/null | head -10
+```
+
+Read up to 5 recent traces. For each, cross-reference against existing skills in `data/skills/`:
+
+**Check 1 — Novel workflow:** Does `novel_patterns` describe a multi-step workflow (5+ steps) not covered by any existing skill? Compare against skill filenames and their triggers. If novel, propose a new skill.
+
+**Check 2 — Correction → skill gap:** Does any `corrections[]` entry reveal a missing rule in an existing skill? Match correction topics against skill names. Propose a Pitfall addition.
+
+**Check 3 — Edge case → Pitfall:** Does any `edge_cases[]` entry belong in an existing skill's Pitfalls section? Match by tool name or domain.
+
+**Check 4 — Tool misuse pattern:** Does `tool_failures[]` with `recovered: true` indicate a learnable pattern? Propose a rule in the relevant skill.
+
+**Check 5 — Script candidate:** Does `script_candidates[]` describe a repeatable multi-tool sequence (3+ calls to the same MCP)? Cross-reference against existing scripts in `data/scripts/` and `src/scripts/` — skip if already extracted. Propose as a `/mcp-to-script` extraction task.
+
+**Output:** Skill proposals under "Skill-Scope Changes", script candidates under "Script Candidates" in the report. For new skill proposals, use this template:
+- Frontmatter: `origin: auto`, `generated: {date}`, `from_traces: [session-ids]`, `confidence: low|medium`, `reviewed: false`
+- Sections: When to Use / Procedure / Pitfalls / Verification
+
+If no traces exist or none yield findings, skip this phase silently.
+
+## Phase 3: Audit Team-Scope Files
+
+Read the key workspace files (context.md, tasks.md, open-questions.md) and skim knowledge/*.md filenames. Don't read every file — focus on the ones most likely stale.
+
+A single conversation can yield both user-scope and team-scope learnings. The user-specific angle goes to user-scope, the team fact goes to team-scope.
+
+For each file you audit, note:
+- **Staleness**: dates older than 2 weeks, metrics that may have changed
+- **Completeness**: tasks marked done but still listed, resolved questions still open
+- **Duplication**: same fact appearing in multiple files
+- **Contradictions**: conflicting info between files
+
+## Phase 4: Classify & Report
+
+**CRITICAL: This is your FINAL phase. Do NOT proceed to Phase 5 (Apply) unless the user explicitly replies with approval numbers.** Write the report, send the DM, and STOP. The reconcile job ends here — application happens in a separate conversation when the user responds.
+
+Compile findings into a timestamped reconciliation report. Create the reports folder if needed:
+
+```bash
+mkdir -p data/workspace/reconcile-reports
+```
+
+Write the report to `data/workspace/reconcile-reports/{YYYY-MM-DD}.md`:
+
+```markdown
+# Reconciliation Report — {date}
+
+## Findings
+- {number} stale items, {number} new learnings, {number} issues
+
+## Skill-Scope Changes
+1. **New skill**: `{name}` — {description}
+   - **Source traces**: {session IDs}
+   - **Proposed sections**: {brief outline}
+
+2. **Patch**: `{skill}.md` — add Pitfall: {description}
+   - **Source**: {session title}: {what happened}
+
+## Script Candidates
+1. **{description}** — `{mcp}`, {N} tool calls/run
+   - **Source**: {session title}
+   - **Sequence**: {tool1} → {tool2} → {tool3}
+   - **Action**: Run `/mcp-to-script {description}` to extract
+
+## Team-Scope Changes
+1. **File**: {path} | **Action**: {update/add/remove/deduplicate}
+   - **Current**: {brief quote}
+   - **Proposed**: {what it should say}
+   - **Source**: {session title or audit finding}
+
+## User-Scope Changes
+{group by user name}
+
+### {User Name} (`users/{id}/`)
+
+**Corrections:**
+1. {concrete rule extracted from a steering/correction moment} — Source: {session}
+
+**Patterns:**
+1. **{Category}**: {observation} — Source: {session}
+
+## Suggestions
+- {structural improvements, missing knowledge files, etc.}
+```
+
+Then send a Slack DM summary using `post_slack_message`:
+
+```
+🔄 Nightly Reconciliation — {date}
+
+{number} findings, {number} proposed changes.
+Full report: data/workspace/reconcile-reports/{date}.md
+
+Skill-scope:
+1. {1-liner — new skill or patch}
+...
+
+Script candidates:
+1. {description} — `{mcp}`, {N} calls/run → `/mcp-to-script`
+...
+
+Team-scope:
+1. {1-liner}
+...
+
+User-scope:
+{N}. {User Name} (`users/{id}/`)
+   Corrections:
+   • {concrete rule}
+   • {concrete rule}
+   Patterns:
+   • {category}: {observation}
+   • {category}: {observation}
+
+Reply with numbers to approve (e.g. "1,3,5") or "all" to apply everything.
+```
+
+**User-scope proposals must show the actual content inline with context** — for each correction or pattern, show what you'd write AND the story behind it (which session, what happened, why you think it's a durable learning). The user needs to judge: "yes, that's how I always work" vs "that was a one-off, don't generalize." Format:
+
+```
+{N}. {User Name} (`users/{id}/`)
+   Corrections:
+   • {concrete rule}
+     → {session}: {what happened that taught you this}
+   Patterns:
+   • {category}: {observation}
+     → {session(s)}: {evidence — what you saw them do}
+```
+
+A 1-liner like "Populate user context" is useless — show what you'd write and why.
+
+**Use numbered lists for all proposed changes** — both in the Slack message and the report file — so the user can reply with numbers to approve specific items.
+
+## Phase 5: Apply Approved Changes (only when asked)
+
+When the user replies with approvals (e.g. "1,3,5" or "all"), load the specific report file from `data/workspace/reconcile-reports/` and process only the approved items.
+
+**Mode check:** Read `selfImprovement` from `data/agent-config.json`. Map proposal types to areas: new skills → `skillCreation`, skill patches → `skillPatching`, user context → `userContext`, knowledge/context → `teamKnowledge`. If the area is `"auto"`, apply without waiting for approval and notify via Slack. If `"approval"` (default), wait for explicit approval numbers.
+
+Create a git checkpoint first:
+
+```bash
+cd data && git add -A && git commit -m "reconcile: pre-checkpoint $(date +%Y-%m-%d)" --allow-empty
+```
+
+Apply the approved edits, then commit:
+
+```bash
+cd data && git add -A && git commit -m "reconcile: $(date +%Y-%m-%d) — <brief summary>"
+```
+
+If the user provides feedback or corrections alongside approvals, treat those as learnings — update the relevant workspace files to reflect the correction.
+
+## Guidelines
+
+- **Report, don't act** — never edit workspace files without explicit approval
+- **Stay lean** — under 30 tool calls; skim don't deep-read
+- **Summaries first** — always check `.summary.md` before touching raw JSONL
+- **Be conservative** — when unsure, flag as "verify?" rather than proposing deletion
+- **Preserve voice** — match the existing tone of workspace files
+- **Don't fabricate** — only propose facts from conversations or existing files
+- **Cite sources** — every proposed change references the session or file it came from
+- **Knowledge hierarchy**: `context.md` is a discovery index (IDs, pointers, 1-liners). `knowledge/*.md` files hold detail. When deduplicating, keep detail in knowledge/ and replace the context.md copy with a pointer (`See knowledge/foo.md`).