@karmaniverous/jeeves-meta-openclaw 0.12.2 → 0.12.4

package/content/skills/coding.md

@@ -0,0 +1,149 @@
+---
+name: coding
+description: Engineering standards for all code work. Use when writing code, reviewing PRs, spawning coding sub-agents, or making architectural decisions in any project (not just Jeeves). Covers design-first development, schema-first patterns, testing, STAN workflow, dependency management, and pre-PR checklist.
+---
+
+# Engineering Standards
+
+These standards apply to ALL code work — whether done directly or via sub-agents.
+When spawning sub-agents for coding tasks, include the relevant rules in the task prompt.
+Sub-agents don't inherit your context — if you don't pass the rules, they don't exist.
+
+---
+
+## Design-First Development
+
+1. **Iterate on design until convergence** — Summarize requirements, propose approach, raise questions BEFORE writing code.
+2. **Services-first architecture** — Core logic in services behind ports; adapters thin; side effects at boundaries.
+3. **Schema-first** — Runtime schema (Zod) is source of truth; TypeScript types derived via `z.infer<>`; validation centralized. Plain TypeScript `interface` declarations for config surfaces are not acceptable.
+4. **300 LOC hard limit** — If a file would exceed 300 lines, stop and decompose first. No exceptions.
+5. **Avoid `any`** — Prefer `unknown` + narrowing; if unavoidable, narrowest scope + rationale.
+6. **Test pairing** — Every non-trivial module gets a `*.test.ts`.
+7. **Open-source first** — Prefer established deps over home-grown solutions. Search npm/GitHub before building anything non-trivial.
+
+## Module Design
+
+- **Single Responsibility** applies to modules as well as functions.
+- Prefer many small modules over a few large ones.
+- Keep module boundaries explicit and cohesive; avoid "kitchen-sink" files.
+- Co-locate tests with modules for discoverability.
+
+## Config Surfaces
+
+- Define config with **Zod schemas** — never bare TypeScript interfaces.
+- Derive types: `type MyConfig = z.infer<typeof myConfigSchema>`
+- Generate **JSON Schema** from Zod for IDE DX (`$schema` pointer in config files).
+- Validate at load time — fail fast with clear error messages.
+- `init` commands generate config with `$schema` pointer already in place.
+
+## Testing
+
+- **Unit tests** for pure services (no fs/process/network).
+- **Integration tests** for adapters/seams (minimal end-to-end slices).
+- Exercise happy paths AND representative error paths.
+- Table-driven cases encouraged for exhaustive coverage.
+- Keep coverage meaningful — prefer covering branches/decisions over chasing 100% lines.
+
+## STAN-Enabled Repos
+
+When working in a repo with `.stan/`:
+- Run `stan run --sequential --no-archive` **before** each commit. Scripts must pass before you commit. Sequential runs are preferred to limit side effects. Archives are not needed (you won't use them).
+- **Push after every commit.** Don't accumulate unpushed local commits. Jason needs to be able to see your work at any time.
+- All scripts must pass before claiming work is complete.
+- Read `.stan/output/<script>.txt` for evidence on failures.
+- When creating stan scripts, eliminate colorized output where possible (e.g. `--no-color`, `NO_COLOR=1`) to reduce noise in script output files.
+
+## Cross-Package Verification
+
+When changes affect exports consumed by another repo:
+- Standalone scripts passing ≠ "ready for review."
+- Use `npm link` or equivalent to verify the consumer builds against your changes.
+- Only claim completion when BOTH repos pass.
+
+## Dependencies: Latest Versions Required (HARD GATE)
+
+**NEVER use a superseded version of ANY dependency without direct human authorization.** When adding a new dependency — or creating a new project — ALWAYS check the latest stable version and use it. This applies to runtime deps, dev deps, and peer deps alike.
+
+- Before `npm install <package>`: run `npm view <package> version` (or check npmjs.com) to confirm you're installing the current major.
+- Before spawning sub-agents that install packages: include the latest version in the task prompt, or instruct the sub-agent to verify latest before installing.
+- If the latest major has known breaking issues that block adoption, flag it to the human — don't silently pin an old major.
+
+LLMs are trained on stale data. Your training cutoff means you will default to old versions of everything. **Assume your version knowledge is wrong** and verify before every install.
+
+*Earned: 2026-05-12, created the jeeves-tools repo with Zod 3 despite Zod 4 being available since mid-2025. Shipped 84 commits on the old major before catching it.*
+
+## Dependencies: Local Over Global
+
+- **Dev dependencies belong in the project, not the global environment.** Install with `npm install --save-dev`, not `npm install -g`.
+- This guarantees reproducibility across machines and CI. Global installs mask environment differences that cause "works on my machine" failures.
+- **Rare exceptions:** Tools that are genuinely machine-level utilities (e.g. `stan-cli`). If in doubt, install locally.
+## Dependency Failures
+
+When a third-party dependency is broken:
+1. Summarize the failure concisely.
+2. Enumerate options: switch dependency → fix upstream → temporary pin → shim (last resort).
+3. Recommend with rationale.
+4. Do NOT immediately code around the problem.
+
+## CHANGELOG
+
+- **Do not manually update CHANGELOG.md** — it is generated as part of the release process (e.g. via `standard-version`, `changesets`, or equivalent). Conventional commit messages are the input; the tooling produces the output.
+
+## Pre-PR Checklist (HARD GATE)
+
+**Before creating ANY PR, run the full verification sequence. No exceptions.**
+
+1. `stan run --sequential --no-archive` if `.stan/` exists — this is the canonical check suite
+2. In monorepos: run checks **from each package directory**, not just the root. Root-level runs may mask package-level failures due to config resolution differences.
+3. Exercise the release path: check `release-it` hooks (or equivalent) in each releasable package — run the same commands (`lint`, `typecheck`, `test`, `build`) from the same cwd the release process uses.
+
+If any step fails, fix it before committing. Do NOT create the PR and "note" the failures. Do NOT claim pre-existing failures without having actually run the commands first. Skipping this sequence is how we ship broken code and fabricate diagnoses.
+
+- **Compare against canonical template** (`karmaniverous/npm-package-template-ts`) before any npm package PR. If the project is behind the template, update it to conform. If the template is behind the project, raise the issue with Jason for template upkeep.
+- **Run `ncu --peer`** before any PR. Review the output. Update safe patches/minors. **Flag major version bumps for discussion** — never auto-apply `ncu -u` without reading what changed. Peer dep conflicts must be resolved, not ignored.
+- When spawning sub-agents, include `ncu --peer` in the quality gate commands: `ncu --peer && npm run lint && npm run typecheck && npm run build && npm test`. The sub-agent should report `ncu` output and only apply updates that don't involve major bumps or peer conflicts.
+- **Resolve ALL script warnings.** It is NOT acceptable to release code with outstanding warnings. They exist for a reason — fix them.
+- **Typecheck/lint rules apply to ALL authored code**, including configs at project root (`eslint.config.ts`, `rollup.config.ts`, `vitest.config.ts`, etc.). Only generated code (e.g. typedoc output) should be excepted from code quality checks.
+- **Never disable lint/typecheck rules** without surfacing it for discussion first. Disabled rules are a major code smell. If a rule must be disabled, document the rationale inline at the point of suppression.
+- **Multiple tsconfigs are a code smell.** Sometimes needed, but often they paper over poor configuration choices. Fix root causes rather than adding tsconfig variants.
+- **In a TS repo, all scripts should be authored in TS** (not JS). Prefer execution with `tsx`.
+- **Clean-room verify before claiming "all green."** Run `rimraf node_modules && npm install && npm run build` (or equivalent) to catch issues masked by cached state. If someone reports an error you can't reproduce, assume your cache is lying — not that they're wrong.
+- Verify build, test, and lint pass after updates.
+
+## Dev Workspace
+
+- **Clone location:** `D:\repos\{org-or-userid}\{repo}` (e.g. `D:\repos\karmaniverous\jeeves-watcher`)
+- D drive is the dev workspace. Do not clone repos elsewhere.
+- Fresh clones are preferred over copying existing checkouts — `npm install` from registry is faster than disk-copying `node_modules`.
+- D drive is NOT indexed by jeeves-watcher. Dev work stays off the archive.
+
+## GitHub Auth (HARD GATE)
+
+- **ALL GitHub operations use `jgs-jeeves` auth.** Set `GH_TOKEN` before any `gh` CLI command:
+  ```powershell
+  $env:GH_TOKEN = (Get-Content "J:\config\credentials\github\jgs-jeeves.token" -Raw).Trim()
+  ```
+- Never write to GitHub as `karmaniverous` — that's Jason's account.
+- If `jgs-jeeves` lacks permissions, **escalate to Jason** rather than falling back to `karmaniverous`.
+
+## Issue Hygiene
+
+- **Always comment rationale when closing an issue without resolution** (duplicate, won't-fix, obsolete). The close action alone doesn't explain why.
+- Reference the replacement issue/PR when closing as duplicate.
+
+## Code Style
+
+- Prettier is source of truth for formatting.
+- Keep imports sorted per repo tooling.
+- Avoid dead code.
+- TSDoc `@module` or `@packageDocumentation` on every non-test module.
+- First 160 chars of module doc should be high-signal: what it does, IO/side effects, traversal hints.
+
+## eslint-disable is a HARD GATE
+
+Never disable lint/typecheck rules without surfacing it for discussion first. Fix the code, don't suppress the warning. For test mocks, use properly typed partial objects (`Partial<RealType>`, typed `MockReply` interfaces) instead of `any`. Tests are code.
+
+## Git Merge Policy
+
+- **No squash merges.** Preserve commit history.
+- **PR reviewer:** When creating a PR under `jgs-jeeves` auth, always add `karmaniverous` (Jason) as a reviewer.

package/content/skills/jeeves.md

@@ -0,0 +1,122 @@
+---
+name: jeeves
+description: Jeeves platform architecture, data flow, component interaction, scripts repo, and coordination knowledge. Use when making architectural decisions, coordinating across components, checking platform health, managing service lifecycle, or working with the scripts repo.
+---
+
+# Jeeves Platform Skill
+
+## Platform Architecture
+
+Jeeves is a four-component platform coordinated by a shared library (`@karmaniverous/jeeves`):
+
+| Component | Role | Port |
+|-----------|------|------|
+| **jeeves-runner** | Execute: scheduled jobs, SQLite state, HTTP API | 1937 |
+| **jeeves-watcher** | Index: file→Qdrant semantic indexing, inference rules | 1936 |
+| **jeeves-server** | Present: web UI, file browser, doc render, export | 1934 |
+| **jeeves-meta** | Distill: LLM synthesis, .meta/ directories, scheduling | 1938 |
+
+Core (`@karmaniverous/jeeves`) is a **library + CLI**, not a service. No port.
+
+## Data Flow
+
+```
+Files → Watcher (index) → Qdrant → Meta (synthesize) → .meta/ → Watcher (re-index)
+                                                                      ↓
+Runner (schedule) → Scripts → Services ← Server (present) ← Browser
+```
+
+## Component Interaction
+
+- **Watcher** indexes files into Qdrant with inference rules and enrichments.
+- **Meta** reads from Qdrant, synthesizes `.meta/` directories, which watcher re-indexes.
+- **Runner** executes scheduled scripts that may call any service's HTTP API.
+- **Server** presents files, renders documents, and provides the event gateway.
+- **Core** provides shared content management (TOOLS.md, SOUL.md, AGENTS.md), service discovery, config resolution, and the component SDK.
+
+## Service Discovery
+
+Services find each other via config resolution:
+1. Component's own config file (`{configRoot}/jeeves-{name}/config.json`)
+2. Core config file (`{configRoot}/jeeves-core/config.json`)
+3. Default port constants
+
+## Scripts Repo
+
+Location: `{configRoot}/jeeves-core/scripts/`
+Template: `@karmaniverous/jeeves-scripts-template`
+
+Scripts use utilities from `@karmaniverous/jeeves` (general) and `@karmaniverous/jeeves-runner` (runner-specific). Any script that could be useful outside runner scheduling belongs in core.
+
+## Managed Content System
+
+Core maintains managed sections in workspace files using comment markers:
+- **TOOLS.md** — Component sections (section mode) + Platform section
+- **SOUL.md** — Professional discipline and behavioral foundations (block mode)
+- **AGENTS.md** — Operational protocols and memory architecture (block mode)
+- **HEARTBEAT.md** — Platform health status (heading-based)
+
+Managed blocks are stationary after initial insertion. Cleanup detection uses Jaccard similarity on 3-word shingles. Cleanup escalation spawns a gateway session when orphaned content is detected.
+
+## Workspace Configuration
+
+`jeeves.config.json` at workspace root provides shared defaults:
+- Precedence: CLI flags → env vars → file → defaults
+- Namespaced: `core.*` (workspace, configRoot, gatewayUrl, devRepos) and `memory.*` (budget, warningThreshold)
+- Inspect with `jeeves config [jsonpath]`
+
+## HEARTBEAT Protocol
+
+The HEARTBEAT system uses a state machine per component:
+`not_installed → deps_missing → config_missing → service_not_installed → service_stopped → healthy`
+
+Dependency-aware: hard deps block alerts, soft deps add informational notes. Declined components are tracked via heading suffix.
+
+## Plugin Lifecycle
+
+```bash
+# Core install (seed workspace content)
+npx @karmaniverous/jeeves install
+
+# Component plugin install
+npx @karmaniverous/jeeves-{component}-openclaw install
+
+# Component plugin uninstall
+npx @karmaniverous/jeeves-{component}-openclaw uninstall
+
+# Core uninstall (remove managed sections)
+npx @karmaniverous/jeeves uninstall
+```
+
+## Memory Hygiene
+
+MEMORY.md has a character budget (default 20,000). Core tracks:
+- Character count and usage percentage
+- Warning at 80% of budget
+- Stale section candidates (H2 sections whose most recent ISO date exceeds the staleness threshold)
+- Evergreen sections (no dates) are never flagged
+
+Review is human/agent-mediated — core does not auto-delete.
+
+### HEARTBEAT Integration
+
+Memory hygiene is checked on every `ComponentWriter` cycle alongside component health. When budget or staleness thresholds are breached, a `## MEMORY.md` alert appears in HEARTBEAT.md under `# Jeeves Platform Status`. The alert includes character count, budget usage percentage, and any stale section names. When memory is healthy, the heading is absent — no alert content, no LLM cost on heartbeat polls.
+
+The `## MEMORY.md` heading follows the same declined/active lifecycle as component headings (`## jeeves-{name}`). Users can decline memory alerts by changing the heading to `## MEMORY.md: declined`.
+
+## Workspace File Size Monitoring
+
+OpenClaw applies a ~20,000-char injection limit to all workspace bootstrap files (AGENTS.md, SOUL.md, TOOLS.md, USER.md, MEMORY.md). Files exceeding the limit are silently truncated.
+
+Core monitors all five files on every `ComponentWriter` cycle:
+- Warning at 80% of budget (fixed threshold; not configurable via `jeeves.config.json`)
+- Over-budget alert when charCount exceeds the budget
+- Missing files are silently skipped
+
+### HEARTBEAT Integration
+
+When a workspace file exceeds the warning threshold, a `## {filename}` alert appears in HEARTBEAT.md (e.g., `## AGENTS.md`). The alert includes:
+- Character count, budget, and usage percentage
+- Trimming guidance in priority order: (1) move domain-specific content to a local skill, (2) extract reference material to companion files with a pointer, (3) summarize verbose instructions, (4) remove stale content
+
+Each file heading follows the same declined/active lifecycle as component headings. Users can decline alerts by changing the heading to `## {filename}: declined` (e.g., `## AGENTS.md: declined`).

package/content/skills/operations.md

@@ -0,0 +1,125 @@
+---
+name: operations
+description: Operational knowledge for a Jeeves installation. Covers date formatting utilities, email pipeline architecture, curation signal protocol, label taxonomy, and data flow patterns. Use when working with date formatting, email scripts, debugging email pipeline issues, or understanding how human email actions are interpreted.
+---
+
+# Operations
+
+Operational knowledge for the Jeeves platform. Covers email pipeline architecture, curation protocols, and operational conventions.
+
+## Date Formatting
+
+A `date-fns` wrapper lives at `{configRoot}/jeeves-core/scripts/src/lib/dates.ts`. It provides:
+
+| Export | Purpose |
+|--------|---------|
+| `dayOfWeek(dateStr)` | Full weekday name for an ISO date string (e.g. `'Monday'`) |
+| `formatDate(dateStr, fmt)` | Format with any date-fns pattern |
+| `relativeDays(dateStr, refStr?)` | Human-friendly relative description (`'today'`, `'tomorrow'`, `'3 days ago'`) |
+| `parseISO` / `format` | Re-exported from date-fns for direct use |
+
+### Gateway session usage
+
+From a gateway session, call via `exec`:
+
+```
+node -e "import { dayOfWeek } from './src/lib/dates.js'; console.log(dayOfWeek('2026-05-11'));"
+```
+
+with `workdir: {configRoot}/jeeves-core/scripts`.
+
+Or use the simpler inline form when the full wrapper isn't needed:
+
+```
+node -e "import { format, parseISO } from 'date-fns'; console.log(format(parseISO('2026-05-11'), 'EEEE'));"
+```
+
+with `workdir: {configRoot}/jeeves-core/scripts` (so date-fns resolves from `node_modules`).
+
+### Hard gate
+
+NEVER state a day of the week without computing it first. LLMs cannot do day-of-week arithmetic reliably.
+
+## Email Curation Signal Protocol
+
+Defines how human email actions in Gmail are interpreted by Jeeves email processes.
+
+### Human Signals
+
+| Signal | Meaning | Action |
+|--------|---------|--------|
+| Label added | Human is adjusting Jeeves classification | Update domain process inputs to reflect new classification |
+| Label removed | Human is adjusting Jeeves classification (removal) | Update domain process inputs to reflect removed classification |
+| Archived → Inbox | Human wants to keep this email in sight | Add `watch` label via update queue |
+| Starred / Flagged | Elevated attention — email is important in context | Domain processes should weight higher |
+| Moved to Spam | Confirmed spam — human classified as junk | Learn from classification for future triage |
+| Removed from Spam | False positive — human rescued from spam | Process as normal email, learn from false positive |
+
+### Watch Label
+
+The `watch` label has special semantics:
+- When present, never auto-archive the email
+- When a watched email lands in archive (by anyone), remove the watch label
+- Added automatically when a human moves an archived email back to inbox
+
+### Label Taxonomy
+
+Labels applied by Jeeves processes fall into two categories:
+
+**Mechanical labels** (applied by domain extractors with high confidence):
+- `meeting` — meeting-related email (invite, notes, transcript)
+- `finance` — financial email (receipt, invoice, billing, statement)
+
+**Reasoning labels** (applied by Update Email Meta, requiring cross-domain context):
+- `project/<name>` — associated with a known project
+- `todo` — requires action or work from the user
+- `reply` — someone is waiting on a response
+- `alert` — automated notification from a service
+- `readme` — newsletter or subscribed informational content
+
+### Labeling Principles
+
+1. Label at the earliest point where confidence is high enough
+2. Domain extractors label what they know with certainty
+3. Update Email Meta labels what requires cross-domain context
+4. A thread can have multiple labels
+5. Do not re-label threads that already have the label
+6. **Prefer false negatives over false positives**
+
+### Poll Scope
+
+Query: `newer_than:1d in:anywhere`
+
+Must include spam and trash to detect human curation signals (e.g., moving to/from spam).
+
+## Email Pipeline Architecture
+
+### Directory Layout
+
+```
+{configRoot}/jeeves-core/email-config.json  — pipeline configuration (accounts, buckets)
+{workspace}/../email/threads/{account}/     — canonical email archive (thread.json + per-message JSONs)
+```
+
+### Data Flow
+
+1. **Poll** (`email/poll.ts`) — searches Gmail for recent threads, classifies, enqueues important ones for metadata fetch
+2. **Fetch** (`email/email-fetch.ts`) — fetches full thread metadata from Gmail, creates/updates `thread.json` cache, enqueues for body download
+3. **Download** (`email/download.ts`) — downloads full message bodies, writes per-message JSONs to `threads/{account}/{threadId}/`
+4. **Drain Updates** (`email/drain-updates.ts`) — applies label changes and other queued updates back to Gmail
+5. **Meta synthesis** — jeeves-meta synthesizes email archives into searchable summaries
+
+### thread.json (Cache Format)
+
+Each `threads/{account}/{threadId}/thread.json` contains:
+- `threadId`, `account`, `subject`, `participants`
+- `messages` — record of `{ messageId → { from, to, cc, date, internalDateMs, labels, snippet, attachments } }`
+- `provenance` — label change history
+- `cachedAt`, `updatedAt`
+
+### Per-Message JSONs
+
+Each `threads/{account}/{threadId}/{messageId}.json` contains full message data:
+- `messageId`, `threadId`, `account`, `subject`, `from`, `to`, `cc`
+- `date` (RFC 2822), `internalDateMs` (epoch ms)
+- `labels`, `body`, `attachments`, `downloadedAt`

package/content/skills/playbooks.md

@@ -0,0 +1,75 @@
+---
+name: playbooks
+description: >
+  Reusable operational workflow patterns for the Jeeves platform. Use when asked to
+  set up a daily briefing for a person or team, create standing meeting ops (notes +
+  agenda generation), replicate an existing workflow pattern for a new context, or
+  understand how recurring intelligence/ops workflows are structured. Covers the
+  full stack: content directory, TASK files, standing orders, runner jobs, dispatcher
+  scripts, Slack channel integration, and meta synthesis.
+---
+
+# Playbooks
+
+Proven, replicable operational patterns. Each playbook describes what it does, what
+infrastructure it needs, and how to instantiate a new instance.
+
+## Common Infrastructure
+
+All playbooks share these building blocks:
+
+| Component | Purpose |
+|-----------|---------|
+| **Content directory** | `{workspace}/../<silo>/<domain>/` — stores output files, `.meta/`, standing orders |
+| **TASK file** | Markdown prompt that defines the LLM session's entire job |
+| **Standing orders** | `standing-orders.md` — append-only file for persistent stakeholder preferences |
+| **Dispatcher script** | TypeScript in `{configRoot}/jeeves-core/scripts/src/` — reads TASK, spawns worker |
+| **Runner job** | jeeves-runner job with cron schedule, timezone, and rrstack |
+| **Slack channel** | Delivery surface — summary posts, quick-link pins, feedback loop |
+| **Meta entity** | `.meta/` directory seeded so jeeves-meta synthesizes context over time |
+
+### Dispatcher Pattern
+
+All dispatchers use `taskFileDispatcher` from `dispatchers/lib/task-file-dispatcher.ts`:
+
+```typescript
+import { taskFileDispatcher } from '../dispatchers/lib/task-file-dispatcher.js';
+
+taskFileDispatcher({
+  scriptName: '<silo>/<job-name>',
+  jobId: '<runner-job-id>',
+  taskFile: '<path-to-TASK.md>',
+  timeout: 600,
+  injectDateContext: true,
+  dateTimezone: '<IANA timezone>',
+});
+```
+
+`injectDateContext: true` prepends an authoritative date line so the LLM knows today's date.
+
+### Standing Orders Convention
+
+- Append-only — never modify existing entries
+- TASK files instruct the LLM to read standing orders at Step 0
+- TASK files instruct the LLM to append new persistent preferences from channel feedback
+- Include initial configuration section with participants, timezones, channel rules
+
+## Available Playbook Patterns
+
+| Pattern | Description |
+|---------|-------------|
+| **Daily Briefing** | Recurring intelligence or action-item report for a stakeholder |
+| **Standing Meeting Ops** | Post-meeting notes + next-day agenda generation for a recurring meeting |
+
+## Instantiation Checklist
+
+When creating a new playbook instance:
+
+1. Choose the appropriate pattern from the table above
+2. Create the content directory with `.meta/` and `standing-orders.md`
+3. Write the TASK file(s) — adapt from an existing instance. Ensure Step 0 reads feedback from the *delivery channel* (where output is posted), not only a DM
+4. Write the dispatcher script(s) in `{configRoot}/jeeves-core/scripts/src/<silo>/`
+5. Register the runner job(s) with appropriate cron, timezone, rrstack
+6. Set up the Slack channel — pin a quick-links message if the pattern calls for it
+7. Seed `.meta/` so meta synthesis begins
+8. Test with `--dry-run` before going live

package/content/skills/slack-bot-provisioner.md

@@ -0,0 +1,57 @@
+---
+name: slack-bot-provisioner
+description: Provision a new Slack bot identity for Clawdbot on a fresh server. Guides through Slack App creation steps, collects tokens, writes local config/env, and verifies connectivity.
+---
+
+# Slack bot provisioner (per-bot server)
+
+Use this when you are setting up **a new Clawdbot instance** that should have **its own Slack bot identity** (one Slack App per bot), and you want a repeatable guided setup.
+
+This skill assumes:
+- The user is a Slack workspace admin.
+- Each bot runs on its own server with its own Gateway config.
+
+## What can be automated vs not
+
+**Automated (this skill):**
+- Create local folders.
+- Write a `slack.env` (bot token, signing secret).
+- Patch the Clawdbot gateway config to enable Slack for this instance (user approves).
+- Run a connectivity test (send a message to a channel).
+
+**Not fully automatable (Slack-side):**
+- Creating/installing the Slack App and granting scopes (UI/OAuth).
+- Verifying event subscription URLs (requires public HTTPS endpoint).
+
+## Recommended mode
+Start with **outbound-only** (post messages) and expand to event subscriptions later.
+
+## Quick start
+
+1) Have the user do the Slack UI steps in `references/slack-app-checklist.md`.
+2) Run the provisioning script:
+
+- PowerShell:
+  - `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/provision.ps1`
+
+The script will prompt for:
+- bot name
+- Slack bot token (`xoxb-...`)
+- Slack signing secret
+- (optional) test channel id
+
+## Files
+- Script: `scripts/provision.ps1`
+- Reference checklist: `references/slack-app-checklist.md`
+- Reference scopes: `references/scopes.md`
+
+## Secrets (best practices)
+- **Do not** store secrets inside the skill folder (skills are meant to be shareable/publishable).
+- Store secrets **per-instance** in the Clawdbot runtime directory (recommended):
+  - `C:\Users\Administrator\.clawdbot\credentials\...`
+- Prefer environment variables / local credential files loaded by the Gateway/service manager.
+- Never paste Slack secrets into public chats.
+
+## Safety notes
+- Store secrets per-instance. Do not reuse tokens across bot identities.
+- Avoid bot-to-bot loops: bots should ignore messages from other bots by default.