Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

docs: add full project documentation suite

auroracapital1cb6ef1acc9b
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 00000000..1ce105a7
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,141 @@
+<!-- generated-by: gsd-doc-writer -->
+# Architecture
+
+claude-ops is a Claude Code plugin (v0.8.0) that installs as a business operating system on top of the Claude Code CLI. It exposes 22 slash-command skills that orchestrate 12 autonomous agents, a persistent background daemon, and a bundled Telegram MCP server. The primary inputs are tool calls from Claude Code sessions; the primary outputs are structured reports, drafted communications, and autonomous code/infrastructure actions executed via shell and API calls.
+
+---
+
+## Component Diagram
+
+```mermaid
+graph TD
+ User["User (Claude Code session)"]
+ Skills["Skills Layer\n22 slash commands\nskills/<name>/SKILL.md"]
+ Agents["Agents Layer\n12 autonomous agents\nagents/<name>.md"]
+ Daemon["ops-daemon\nlaunchd-managed\nscripts/ops-daemon.sh"]
+ Hooks["Hooks\nhooks/hooks.json"]
+ Bin["Bin Scripts\nbin/ops-*"]
+ TelegramMCP["Telegram MCP Server\ntelegram-server/index.js"]
+ Registry["Project Registry\nscripts/registry.json"]
+ Cache["Daemon Cache\n~/.claude/plugins/data/.../daemon-cache.json"]
+ Prefs["User Preferences\nplugin.json userConfig"]
+ Secrets["Secrets (Doppler / 1Password / env)"]
+
+ User -->|slash command| Skills
+ Skills -->|spawn| Agents
+ Skills -->|read| Registry
+ Skills -->|read| Cache
+ Skills -->|call| Bin
+ Agents -->|Bash + tool calls| Bin
+ Daemon -->|writes| Cache
+ Daemon -->|runs| Bin
+ Hooks -->|PreToolUse / SessionStart / Stop| Skills
+ TelegramMCP -->|MCP protocol| Skills
+ Prefs -->|userConfig injection| Skills
+ Secrets -->|env vars| Bin
+ Secrets -->|env vars| TelegramMCP
+```
+
+---
+
+## Data Flow
+
+A typical `/ops:go` morning briefing flows as follows:
+
+1. **SessionStart hook** — `hooks/hooks.json` fires `bin/ops-welcome` (displays setup status) and `scripts/setup.sh` (surfaces any unresolved configuration issues).
+2. **Skill invocation** — the user runs `/ops:go`; the `skills/ops-go/SKILL.md` skill is loaded by Claude Code.
+3. **Cache read** — the skill calls `bin/ops-gather` (or reads the pre-warmed `daemon-cache.json` written by the daemon's `briefing-pre-warm` service every 2 minutes).
+4. **Agent fan-out (optional)** — for deeper analysis (`/ops:yolo`), the skill spawns 4 parallel agents (CEO, CTO, CFO, COO) via the Claude Agent SDK. Each agent runs independently using `claude-opus-4-6` and writes its analysis to a temp file.
+5. **Merge + present** — the main skill orchestrator reads all agent output files, merges them into a unified report, and returns it to the user in the Claude Code session.
+6. **Stop hook** — `bin/ops-post-session-cleanup` runs on session end to clean up temp files and stale PIDs.
+
+For communication skills (`/ops:inbox`, `/ops:comms`), a PreToolUse hook (`bin/ops-pretool-wacli-health`) checks the WhatsApp daemon health file before any `wacli` Bash call and surfaces a warning if the sync is stale (>10 min).
+
+---
+
+## Key Abstractions
+
+| Abstraction | Location | Description |
+|-------------|----------|-------------|
+| `plugin.json` | `claude-ops/.claude-plugin/plugin.json` | Plugin manifest: name, version, `userConfig` schema (20 configurable keys), MCP server declarations |
+| `SKILL.md` | `claude-ops/skills/<name>/SKILL.md` | Each skill is a markdown prompt file loaded by Claude Code as a slash command |
+| Agent `.md` files | `claude-ops/agents/<name>.md` | Each agent is a markdown prompt file with frontmatter declaring model, effort, maxTurns, and memory scope |
+| `hooks.json` | `claude-ops/hooks/hooks.json` | Declares SessionStart, PreToolUse (Bash matcher), and Stop lifecycle hooks |
+| `registry.json` | `claude-ops/scripts/registry.json` | User-maintained project index with alias, repo, infra platform, revenue model, and GSD flag per project |
+| `ops-daemon.sh` | `claude-ops/scripts/ops-daemon.sh` | Shell supervisor for 7 persistent background services; managed via launchd |
+| `daemon-cache.json` | `~/.claude/plugins/data/.../daemon-cache.json` | Pre-warmed briefing data written by `briefing-pre-warm` every 2 min; read by `/ops:go` for <3s load |
+| `CLAUDE.md` | `claude-ops/CLAUDE.md` | Plugin-root rules (Rules 0–5) that override individual skill instructions for all agents |
+| Telegram MCP server | `claude-ops/telegram-server/index.js` | Node.js MCP server providing MTProto user-auth Telegram access (personal account, not bot API) |
+
+---
+
+## Directory Structure Rationale
+
+```
+claude-ops/
+├── .claude-plugin/
+│ └── plugin.json # Plugin manifest and userConfig schema
+├── agents/ # 12 agent prompt files (.md) — spawned by skills
+├── bin/ # 22 shell/node scripts (ops-*) — the executable layer
+├── docs/ # Reference documentation for plugin internals
+├── hooks/
+│ └── hooks.json # Lifecycle hook declarations (SessionStart, PreToolUse, Stop)
+├── output-styles/ # Output formatting guides used by skills
+├── scripts/ # Daemon, cron jobs, setup wizard, project registry
+├── skills/ # 22 skill directories, each containing a SKILL.md prompt
+├── telegram-server/ # Bundled MCP server for Telegram MTProto access
+├── tests/ # Bash test suite (no-secrets, skills-lint, hooks, bin-scripts)
+├── CHANGELOG.md # Version history
+├── CLAUDE.md # Plugin-root rules applied to all skills and agents
+├── LICENSE # MIT
+└── package.json # Runtime deps for bin .mjs scripts (telegram, playwright)
+```
+
+- **`skills/`** — User-facing layer. Each subdirectory is one slash command. Skills are markdown prompt files; they contain no executable code, only instructions for Claude.
+- **`agents/`** — Background worker layer. Agent `.md` files are spawned by skills using the Claude Agent SDK. They have declared resource budgets (model, maxTurns, effort) and memory scopes.
+- **`bin/`** — Executable layer. Shell and Node.js scripts that interact with external CLIs (`wacli`, `aws`, `gh`, `doppler`, `gog`) and APIs. Skills and agents call these via Bash tool calls.
+- **`scripts/`** — Infrastructure layer. The daemon supervisor, launchd plists, cron scripts, and the project registry live here.
+- **`telegram-server/`** — Bundled MCP server. Provides Telegram access via MTProto (personal account authentication, not bot tokens). Declared in `.mcp.json` and auto-started by Claude Code.
+- **`hooks/`** — Automation layer. Three lifecycle hooks: SessionStart (welcome + setup check), PreToolUse/Bash (WhatsApp health check), and Stop (cleanup).
+- **`tests/`** — Validation layer. Bash scripts that check for committed secrets, skill markdown lint, hook schema validity, and bin script executability. Run via `tests/run-all.sh`.
+
+---
+
+## Daemon Architecture
+
+The `ops-daemon` is a launchd-managed supervisor that runs 7 background services continuously:
+
+| Service | Cadence | Purpose |
+|---------|---------|---------|
+| `briefing-pre-warm` | every 2 min | Runs `bin/ops-gather` to keep `/ops:go` cache hot |
+| `wacli-sync` | persistent | Keeps WhatsApp connected via wacli, auto-reconnects |
+| `memory-extractor` | every 30 min | Spawns `memory-extractor` agent to refresh `memories/` |
+| `inbox-digest` | every 15 min | Pre-classifies communications across all channels |
+| `store-health` | every 10 min | Shopify orders and inventory polling (if configured) |
+| `competitor-intel` | hourly | Background market and competitor monitoring |
+| `message-listener` | persistent | Surfaces urgent patterns ("urgent", "ASAP", "fire", "down") |
+
+The daemon installs at setup Step 2c — deliberately early — so the briefing cache is pre-warmed while the user completes the remaining integration configuration steps.
+
+---
+
+## Agent Model Assignments
+
+| Agent class | Model | Use case |
+|-------------|-------|----------|
+| C-suite analysts (`yolo-ceo`, `yolo-cto`, `yolo-cfo`, `yolo-coo`) | `claude-opus-4-6` | High-depth strategic, technical, financial, operational analysis |
+| Scanner, fix, and daemon agents | `claude-sonnet-4-6` | Efficient read-scan-report loops and targeted code fixes |
+| `memory-extractor` | `claude-haiku-4-5-20251001` | High-frequency (every 30 min) low-cost contact extraction |
+
+---
+
+## Plugin Rule Enforcement
+
+`claude-ops/CLAUDE.md` defines 6 rules (Rule 0 through Rule 5) that apply to every skill and agent in the plugin, overriding any conflicting instruction in individual files:
+
+- **Rule 0** — No personal data ever committed (public open-source repo)
+- **Rule 1** — Maximum 4 options per `AskUserQuestion` call
+- **Rule 2** — Never delegate commands to the user; use Bash tool instead
+- **Rule 3** — Never auto-skip channels or integrations during setup
+- **Rule 4** — Background by default during setup and configuration flows
+- **Rule 5** — Destructive actions require explicit per-action confirmation
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
new file mode 100644
index 00000000..d76cc2da
--- /dev/null
+++ b/docs/CONFIGURATION.md
@@ -0,0 +1,227 @@
+<!-- generated-by: gsd-doc-writer -->
+# Configuration
+
+claude-ops has four distinct layers of configuration: plugin `userConfig` fields set inside Claude Code, a project registry file, a daemon services file, and a runtime preferences file written by the setup wizard. This document covers all four.
+
+---
+
+## Plugin Settings (`userConfig`)
+
+These fields are set through the Claude Code plugin UI (`/plugin` → `ops` → Settings) or via `/ops:setup`. They map directly to the `userConfig` schema in `.claude-plugin/plugin.json`. Sensitive values are stored encrypted by Claude Code and are never written to disk in plaintext.
+
+| Field | Required | Default | Description |
+|---|---|---|---|
+| `telegram_api_id` | Optional | `""` | Numeric API ID from [my.telegram.org/apps](https://my.telegram.org/apps). Run `/ops:setup telegram` to auto-configure. |
+| `telegram_api_hash` | Optional | `""` | API hash from [my.telegram.org/apps](https://my.telegram.org/apps). Run `/ops:setup telegram` to auto-configure. |
+| `telegram_phone` | Optional | `""` | Your Telegram phone number in E.164 format (e.g. `+14155550100`). |
+| `telegram_session` | Optional | `""` | gram.js `StringSession` token. Generated automatically by `/ops:setup telegram`. |
+| `sentry_org` | Optional | `""` | Sentry organization slug (e.g. `my-org`). Used by `/ops:triage` and `/ops:fires`. |
+| `linear_team` | Optional | `""` | Default Linear team key (e.g. `HEA`). Used by `/ops:linear`. |
+| `aws_region` | Optional | `us-east-1` | Default AWS region for infra checks. Used by `/ops:deploy`, `/ops:fires`, `/ops:revenue`. |
+| `klaviyo_private_key` | Optional | `""` | Private API key from Klaviyo Settings → API Keys (starts with `pk_` or `ck_`). Used by `/ops:marketing`. |
+| `meta_ads_token` | Optional | `""` | Meta Marketing API access token from Facebook Business. Used by `/ops:marketing`. |
+| `meta_ad_account_id` | Optional | `""` | Meta ad account ID in `act_XXXXXXXXX` format. Used by `/ops:marketing`. |
+| `ga4_property_id` | Optional | `""` | GA4 property ID (numeric, from Admin → Property Settings). Used by `/ops:marketing`. |
+| `google_search_console_site` | Optional | `""` | Site URL as registered in Google Search Console (e.g. `https://example.com`). |
+| `shopify_store_url` | Optional | `""` | Shopify store URL (e.g. `mystore.myshopify.com`). Used by `/ops:ecom`. |
+| `shopify_admin_token` | Optional | `""` | Shopify Admin API access token from Shopify Partners or a custom app. Used by `/ops:ecom`. |
+| `shipbob_access_token` | Optional | `""` | ShipBob Personal Access Token for fulfillment tracking. Used by `/ops:ecom`. |
+| `bland_ai_api_key` | Optional | `""` | API key from [app.bland.ai](https://app.bland.ai). Used by `/ops:voice` for outbound calls. |
+| `elevenlabs_api_key` | Optional | `""` | API key from [elevenlabs.io](https://elevenlabs.io). Used by `/ops:voice` for TTS. |
+| `groq_api_key` | Optional | `""` | API key from [console.groq.com](https://console.groq.com). Used by `/ops:voice` for Whisper transcription. |
+| `stripe_secret_key` | Optional | `""` | Stripe secret key (`sk_live_...` or `sk_test_...`). Prefer a Doppler reference. Used by `/ops:revenue`. |
+| `revenuecat_api_key` | Optional | `""` | RevenueCat V1 API key for mobile subscription revenue tracking. Used by `/ops:revenue`. |
+| `revenuecat_project_id` | Optional | `""` | RevenueCat project ID (visible in the app.revenuecat.com URL). Used by `/ops:revenue`. |
+
+**Sensitive fields** (`telegram_api_id`, `telegram_api_hash`, `telegram_phone`, `telegram_session`, `klaviyo_private_key`, `meta_ads_token`, `shopify_admin_token`, `shipbob_access_token`, `bland_ai_api_key`, `elevenlabs_api_key`, `groq_api_key`, `stripe_secret_key`, `revenuecat_api_key`) are marked `"sensitive": true` in the schema and are encrypted at rest by Claude Code.
+
+---
+
+## Telegram MCP Server (`.mcp.json`)
+
+The bundled Telegram MCP server is wired in `.mcp.json` at the plugin root. It reads all four Telegram credentials directly from `userConfig` at runtime — no manual file editing is required.
+
+```json
+{
+ "mcpServers": {
+ "telegram": {
+ "command": "node",
+ "args": ["${CLAUDE_PLUGIN_ROOT}/telegram-server/index.js"],
+ "env": {
+ "TELEGRAM_API_ID": "${user_config.telegram_api_id}",
+ "TELEGRAM_API_HASH": "${user_config.telegram_api_hash}",
+ "TELEGRAM_PHONE": "${user_config.telegram_phone}",
+ "TELEGRAM_SESSION": "${user_config.telegram_session}"
+ }
+ }
+ }
+}
+```
+
+`CLAUDE_PLUGIN_ROOT` is resolved at runtime to the plugin's installed cache directory. It is also exported into your shell profile by `/ops:setup` so shell scripts can reference it.
+
+---
+
+## Project Registry (`scripts/registry.json`)
+
+The registry tells every skill which projects you own, where they live on disk, and how they are deployed. It is **gitignored** — copy `scripts/registry.example.json` to `scripts/registry.json` and fill in your values.
+
+```json
+{
+ "version": "1.0",
+ "owner": "Your Name",
+ "projects": [
+ {
+ "alias": "my-app",
+ "paths": ["~/Projects/my-app"],
+ "repos": ["your-org/my-app"],
+ "org": "your-org",
+ "type": "monorepo",
+ "infra": {
+ "platform": "vercel"
+ },
+ "revenue": { "model": "saas", "stage": "pre-launch" },
+ "gsd": true,
+ "priority": 1
+ },
+ {
+ "alias": "my-api",
+ "paths": ["~/Projects/my-api"],
+ "repos": ["your-org/my-api"],
+ "org": "your-org",
+ "type": "monorepo",
+ "infra": {
+ "ecs_clusters": ["my-api-production", "my-api-staging"],
+ "platform": "aws"
+ },
+ "revenue": { "model": "saas", "stage": "growth" },
+ "gsd": true,
+ "priority": 2
+ }
+ ]
+}
+```
+
+### Registry fields
+
+| Field | Required | Description |
+|---|---|---|
+| `version` | Required | Schema version. Always `"1.0"`. |
+| `owner` | Required | Your display name, used in briefing headings. |
+| `projects[].alias` | Required | Short name used in skill commands (e.g. `/ops:fires my-api`). |
+| `projects[].paths` | Required | Array of local directory paths for this project. Multi-repo projects list multiple paths. |
+| `projects[].repos` | Required | Array of `org/repo` slugs on GitHub. |
+| `projects[].org` | Required | GitHub org or username. |
+| `projects[].type` | Required | `"monorepo"` or `"multi-repo"`. |
+| `projects[].infra.platform` | Optional | `"aws"` or `"vercel"`. Determines which deploy checks run. |
+| `projects[].infra.ecs_clusters` | Optional | Array of ECS cluster names (AWS only). Used by `/ops:deploy` and `/ops:fires`. |
+| `projects[].revenue.model` | Optional | `"saas"`, `"subscription"`, `"ecom"`, etc. |
+| `projects[].revenue.stage` | Optional | `"pre-launch"`, `"growth"`, etc. Shown in `/ops:revenue`. |
+| `projects[].revenue.mrr` | Optional | Current MRR in USD. Used in revenue dashboard. |
+| `projects[].gsd` | Optional | `true` if the project uses GSD planning. Enables GSD phase display in `/ops:projects`. |
+| `projects[].priority` | Optional | Integer. Skills process projects in ascending priority order. |
+
+The interactive wizard (`/ops:setup registry`) builds this file project-by-project via structured prompts.
+
+---
+
+## Daemon Services (`scripts/daemon-services.example.json`)
+
+The ops-daemon is managed by launchd and runs shell services on cron schedules or as persistent processes. To customize which services run, copy `scripts/daemon-services.example.json` to `~/.claude/plugins/data/ops-ops-marketplace/daemon-services.json`.
+
+**All optional services are disabled by default in the example file.** The `wacli-sync` service is enabled; `memory-extractor` is **disabled** and must be explicitly enabled.
+
+### Available services
+
+| Service | Default | Type | Schedule | Notes |
+|---|---|---|---|---|
+| `wacli-sync` | **enabled** | persistent | — | Keeps WhatsApp connected. Restarts up to 10 times with a 60 s delay. Requires `wacli` installed. |
+| `memory-extractor` | **disabled** | cron + persistent | every 30 min | Extracts contact profiles and conversation context via a background Haiku agent. |
+| `inbox-digest` | disabled | cron | every 4 hours | Sends an inbox summary to Telegram. Requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`, and `gog` for email. |
+| `store-health` | disabled | cron | daily at 09:00 | Sends Shopify store health report to Telegram. Requires `SHOPIFY_STOREFRONT_TOKEN`, `SHOPIFY_STORE_DOMAIN`, `TELEGRAM_BOT_TOKEN`. |
+| `competitor-intel` | disabled | cron | Mondays at 10:00 | Weekly competitor research delivered to Telegram. Requires `TELEGRAM_BOT_TOKEN`. Optional: `TAVILY_API_KEY`. |
+| `message-listener` | disabled | persistent | — | Listens for incoming messages and triggers responses. Requires `wacli`. Optional: `TELEGRAM_BOT_TOKEN`, `TELEGRAM_OWNER_ID`. Restarts up to 20 times with a 30 s delay. |
+
+### Service schema
+
+```json
+{
+ "services": {
+ "memory-extractor": {
+ "enabled": false,
+ "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ops-memory-extractor.sh",
+ "health_file": "~/.claude/plugins/data/ops-ops-marketplace/memories/.health",
+ "restart_delay": 3600,
+ "cron": "*/30 * * * *"
+ }
+ }
+}
+```
+
+| Field | Description |
+|---|---|
+| `enabled` | `true` to activate the service. `false` to disable (daemon ignores it). |
+| `command` | Shell command to run. Use `${CLAUDE_PLUGIN_ROOT}` for portability. |
+| `cron` | Cron expression for scheduled services. Omit for persistent services. |
+| `health_file` | Path the service writes to signal it is healthy. Read by the daemon for restart decisions. |
+| `restart_delay` | Seconds to wait before restarting a crashed service. |
+| `max_restarts` | Maximum restart attempts before the daemon gives up. |
+
+The default daemon configuration (before any user customization) is in `scripts/daemon-services.default.json`. It enables `briefing-pre-warm`, `wacli-sync`, and `memory-extractor` — but the **user-facing example disables `memory-extractor`** so it is opt-in.
+
+The `_variables` block in the example documents two runtime substitution variables:
+
+- `CLAUDE_PLUGIN_ROOT` — resolved at runtime to the plugin install directory.
+- `OPS_DATA_DIR` — overrides the default data directory (`~/.claude/plugins/data/ops-ops-marketplace`).
+
+---
+
+## Runtime Preferences (`preferences.json`)
+
+The `/ops:setup` wizard writes a `preferences.json` file to `~/.claude/plugins/data/ops-ops-marketplace/preferences.json`. This file is **outside the plugin source tree** and survives plugin reinstalls and version bumps. It stores your display name, timezone, briefing verbosity, default channels, and channel-specific tokens that are not managed through plugin `userConfig`.
+
+<!-- VERIFY: Full schema of preferences.json — fields written by /ops:setup are not documented in the repository source files accessible here. -->
+
+---
+
+## Hooks (`hooks/hooks.json`)
+
+Three Claude Code lifecycle hooks are registered automatically when the plugin is installed.
+
+| Hook | Trigger | Command |
+|---|---|---|
+| `SessionStart` | Every new Claude Code session | `ops-welcome` — shows a startup dashboard; `setup.sh` — prints any unresolved config issues (first 3 lines). |
+| `PreToolUse` (Bash matcher) | Before every `Bash` tool call | `ops-pretool-wacli-health` — checks WhatsApp connection health before any shell command runs. |
+| `Stop` | Session end | `ops-post-session-cleanup` — runs cleanup tasks after the session closes. |
+
+Hooks are wired via `hooks/hooks.json` and reference scripts via `${CLAUDE_PLUGIN_ROOT}`. No user configuration is required.
+
+---
+
+## Environment Variables (daemon cron services)
+
+These environment variables are read by optional cron service shell scripts. They are not managed by plugin `userConfig` and must be available in the daemon's shell environment (e.g. via Doppler, your shell profile, or a secrets manager).
+
+| Variable | Required by | Description |
+|---|---|---|
+| `TELEGRAM_BOT_TOKEN` | `inbox-digest`, `store-health`, `competitor-intel`, `message-listener` | Telegram Bot API token for sending notifications. |
+| `TELEGRAM_CHAT_ID` | `inbox-digest` | Telegram chat ID to send the inbox digest to. |
+| `TELEGRAM_OWNER_ID` | `message-listener` | Optional. Telegram user ID of the owner for message routing. |
+| `SHOPIFY_STOREFRONT_TOKEN` | `store-health` | Shopify Storefront API token. |
+| `SHOPIFY_STORE_DOMAIN` | `store-health` | Shopify store domain (e.g. `mystore.myshopify.com`). |
+| `TAVILY_API_KEY` | `competitor-intel` | Optional. Improves web search quality for competitor research. |
+| `CLAUDE_PLUGIN_ROOT` | All daemon scripts | Path to the plugin install directory. Exported by `/ops:setup`. |
+
+---
+
+## Per-Environment Overrides
+
+claude-ops does not use `.env` files. All secrets resolve through the following chain in priority order:
+
+1. **Doppler** — if `doppler` CLI is installed and configured, `/ops:setup` will link it. Skills read secrets via `doppler run --` or environment injection.
+2. **Password manager** — 1Password (`op`), Dashlane (`dcli`), or Bitwarden (`bw`) vaults are scanned by `/ops:setup` during credential collection.
+3. **macOS Keychain** — the Telegram wizard stores `api_id`, `api_hash`, `phone`, and `session` in the system keychain automatically.
+4. **Plugin `userConfig`** — values set in Claude Code plugin settings (see Plugin Settings section above).
+5. **Shell environment** — variables exported in your shell profile (e.g. `~/.zshrc`).
+
+For production deployments, Doppler is the recommended secrets source. Skills degrade gracefully when optional credentials are absent — features that require a missing credential are skipped rather than erroring.
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
new file mode 100644
index 00000000..819d5fd2
--- /dev/null
+++ b/docs/DEVELOPMENT.md
@@ -0,0 +1,335 @@
+<!-- generated-by: gsd-doc-writer -->
+# Development Guide
+
+This guide covers everything you need to contribute to claude-ops — from understanding the nested directory layout to adding new skills, agents, and bin scripts.
+
+---
+
+## Local Setup
+
+```bash
+git clone https://github.com/Lifecycle-Innovations-Limited/claude-ops.git
+cd claude-ops
+
+# Load the plugin directly from the local checkout
+claude --plugin-dir ./claude-ops/claude-ops
+```
+
+After making any change to a skill, agent, hook, or CLAUDE.md, reload without restarting Claude Code:
+
+```bash
+/reload-plugins
+```
+
+No additional install step is required for the plugin itself. The `claude-ops/node_modules/` directory (used by the `.mjs` autolink scripts) is committed, so no `npm install` is needed unless you are adding new bin-script dependencies.
+
+---
+
+## Repo Structure
+
+The repository uses a two-level layout required by the Claude Code plugin marketplace:
+
+```
+claude-ops/ ← marketplace root (the GitHub repo)
+├── .claude-plugin/
+│ └── marketplace.json # points "source" to ./claude-ops
+├── README.md
+├── CONTRIBUTING.md
+├── LICENSE
+├── SECURITY.md
+│
+└── claude-ops/ ← plugin root (Claude Code loads from here)
+ ├── .claude-plugin/plugin.json # plugin manifest (name, version, userConfig)
+ ├── CLAUDE.md # 6 non-negotiable plugin rules (Rule 0–5)
+ ├── skills/ # 22 slash commands — one subdirectory per skill
+ ├── agents/ # 12 autonomous agents (Opus/Sonnet/Haiku)
+ ├── bin/ # ops-* shell scripts called by skills
+ ├── hooks/
+ │ └── hooks.json # SessionStart / PreToolUse / Stop hooks
+ ├── scripts/ # daemon plists, cron scripts, registry.json
+ ├── telegram-server/ # bundled MTProto MCP server (gram.js)
+ ├── templates/ # Shopify Admin scaffolding
+ ├── tests/ # bash validation suites
+ ├── output-styles/ # reusable output format templates
+ ├── node_modules/ # runtime deps for .mjs autolink scripts
+ └── package.json # claude-ops-bin v0.2.2
+```
+
+**Why the nested `claude-ops/claude-ops/` layout?** Claude Code's marketplace resolves the plugin root from the `"source"` field in `marketplace.json`. The outer directory is the marketplace container; the inner directory is what Claude Code actually loads. This cannot be flattened — the marketplace system requires exactly this two-level structure.
+
+---
+
+## Adding a Skill
+
+Each skill is a subdirectory under `claude-ops/claude-ops/skills/` containing a single `SKILL.md` file.
+
+```
+skills/
+└── ops-myfeature/
+ └── SKILL.md
+```
+
+`SKILL.md` format (YAML frontmatter + markdown body):
+
+```markdown
+---
+name: ops-myfeature
+description: One-sentence description shown in the skills list.
+argument-hint: "[optional-arg]"
+allowed-tools:
+ - Bash
+ - Read
+ - Grep
+ - Glob
+ - AskUserQuestion
+effort: low # low | medium | high
+maxTurns: 20
+---
+
+# OPS ► MY FEATURE
+
+Skill body — instructions Claude follows when this slash command is invoked.
+```
+
+**Key frontmatter fields:**
+
+| Field | Required | Notes |
+|---|---|---|
+| `name` | Yes | Must match the directory name exactly |
+| `description` | Yes | Shown in `/ops` dashboard |
+| `allowed-tools` | Yes | Allowlist of Claude tools the skill can use |
+| `effort` | No | `low` / `medium` / `high` — controls token budget hint |
+| `maxTurns` | No | Hard turn limit for the skill |
+| `argument-hint` | No | Displayed after the slash command in autocomplete |
+
+After adding a skill, run `/reload-plugins` and verify it appears in `/ops`.
+
+---
+
+## Adding an Agent
+
+Agents live under `claude-ops/claude-ops/agents/` as individual `.md` files:
+
+```
+agents/
+└── my-agent.md
+```
+
+Agent `.md` format:
+
+```markdown
+---
+name: my-agent
+description: What this agent does and when it is invoked.
+model: claude-sonnet-4-6 # claude-opus-4-6 | claude-sonnet-4-6 | claude-haiku-4-5
+effort: medium
+maxTurns: 25
+tools:
+ - Bash
+ - Read
+ - Grep
+disallowedTools:
+ - Write
+ - Edit
+ - Agent
+memory: project # project | user | none
+---
+
+# MY AGENT
+
+Agent instructions here.
+```
+
+**Model selection convention:**
+- `claude-opus-4-6` — C-suite agents (`yolo-ceo`, `yolo-cfo`, `yolo-coo`, `yolo-cto`)
+- `claude-sonnet-4-6` — Scanner, monitor, and fix agents
+- `claude-haiku-4-5` — High-frequency lightweight agents (memory extraction)
+
+Agents are invoked from skills via the `Agent` tool. They never call other agents (note `Agent` in `disallowedTools` for most agents — this prevents recursive spawning).
+
+---
+
+## Adding a Bin Script
+
+Bin scripts live under `claude-ops/claude-ops/bin/` and are called directly by skills via the `Bash` tool or from `hooks.json`.
+
+**Naming convention:** all scripts use the `ops-` prefix (e.g., `ops-gather`, `ops-prs`, `ops-infra`).
+
+**Standard structure:**
+
+```bash
+#!/usr/bin/env bash
+# ops-myscript — Short description of what this script does
+# Usage: ops-myscript [--json] [args...]
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+# ... implementation ...
+
+# Output: emit JSON to stdout
+jq -n --arg key "value" '{"key": $key}'
+```
+
+**`--json` convention:** scripts that can be called in two modes (human-readable summary vs. machine-readable data) accept a `--json` flag. When present, output is pure JSON consumed by `ops-gather` or skills. Without the flag, output is formatted for direct terminal display.
+
+`ops-gather` runs all data-collecting scripts in parallel and merges their JSON output into a single payload:
+
+```bash
+"$SCRIPT_DIR/ops-git" > "$TMPDIR_OPS/git.json" 2>/dev/null &
+"$SCRIPT_DIR/ops-infra" > "$TMPDIR_OPS/infra.json" 2>/dev/null &
+"$SCRIPT_DIR/ops-prs" > "$TMPDIR_OPS/prs.json" 2>/dev/null &
+wait
+```
+
+New data-gathering scripts should be added to `ops-gather` so they are included in pre-warm briefing data.
+
+---
+
+## Hooks
+
+Hooks are declared in `claude-ops/claude-ops/hooks/hooks.json`. Three event types are supported:
+
+```json
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/ops-welcome 2>/dev/null || true"
+ },
+ {
+ "type": "command",
+ "command": "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh 2>/dev/null | grep '✗' | head -3 || true"
+ }
+ ]
+ }
+ ],
+ "PreToolUse": [
+ {
+ "matcher": "Bash",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/ops-pretool-wacli-health \"$TOOL_INPUT\" 2>/dev/null || true"
+ }
+ ]
+ }
+ ],
+ "Stop": [
+ {
+ "hooks": [
+ {
+ "type": "command",
+ "command": "bash ${CLAUDE_PLUGIN_ROOT}/bin/ops-post-session-cleanup 2>/dev/null || true"
+ }
+ ]
+ }
+ ]
+ }
+}
+```
+
+| Event | Matcher | Current use |
+|---|---|---|
+| `SessionStart` | (all) | Run `ops-welcome` banner + surface any setup health failures |
+| `PreToolUse` | `Bash` | Check wacli health before any Bash call |
+| `Stop` | (all) | Post-session cleanup |
+
+Hook commands must always exit `0` (note the `|| true` suffix). A failing hook causes Claude Code to surface an error — never let hooks fail loudly.
+
+The `$CLAUDE_PLUGIN_ROOT` environment variable is injected by Claude Code at runtime and resolves to the `claude-ops/claude-ops/` directory.
+
+---
+
+## CLAUDE.md Rules
+
+`claude-ops/claude-ops/CLAUDE.md` defines six rules that apply to every skill and agent. They cannot be overridden by individual skill instructions.
+
+| Rule | Name | Summary |
+|---|---|---|
+| Rule 0 | PUBLIC REPO — No personal data ever | Never commit real names, emails, tokens, org names, store URLs, or hardcoded paths. Use placeholders (`owner`, `[email protected]`, `<YOUR_TOKEN>`). Run `tests/test-no-secrets.sh` before every commit. |
+| Rule 1 | Max 4 options per AskUserQuestion | The `AskUserQuestion` tool enforces a hard limit of `<=4` items. Paginate larger lists at 4 per page using `[More options...]` as a bridge. |
+| Rule 2 | Never delegate commands to the user | Run all commands via the `Bash` tool. Use `run_in_background: true` for OAuth flows and long-running installs. The only exception is QR-based auth (`wacli auth`). |
+| Rule 3 | Never auto-skip channels or integrations | If auto-scan returns empty for a credential, always present an explicit `AskUserQuestion` with `[Paste manually]`, `[Deep hunt]`, `[Skip]`. Never silently skip. |
+| Rule 4 | Background by default during setup | Use `run_in_background: true` on every Bash call in setup flows unless the result is immediately needed for the next decision. |
+| Rule 5 | Destructive actions require per-action confirmation | Never execute `delete-*`, `stop-*`, `terminate-*`, force-push, or any infrastructure destruction without an explicit `AskUserQuestion` confirmation per action. |
+
+When writing a new skill or agent, verify each of these rules applies correctly before submitting a PR.
+
+---
+
+## Build Commands
+
+The plugin has no compilation step — all skills and agents are plain markdown. The `package.json` at `claude-ops/claude-ops/package.json` manages runtime dependencies for the `.mjs` autolink scripts only.
+
+| Command | What it does |
+|---|---|
+| `bash tests/run-all.sh` | Run all six test suites and report pass/fail |
+| `bash tests/test-no-secrets.sh` | Scan for leaked secrets, tokens, or personal data |
+| `bash tests/test-skills-lint.sh` | Lint all SKILL.md files for required frontmatter fields |
+| `bash tests/test-bin-scripts.sh` | Validate bin scripts are executable and have correct shebangs |
+| `bash tests/test-hooks.sh` | Validate hooks.json structure |
+| `bash tests/test-claude-md.sh` | Verify CLAUDE.md contains all required rules |
+| `bash tests/test-template.sh` | Validate Shopify scaffolding template |
+
+All commands run from the `claude-ops/claude-ops/` directory.
+
+---
+
+## Pre-commit Checklist
+
+There is no automated pre-commit hook wired to git. Before every commit, run these manually:
+
+```bash
+cd claude-ops/claude-ops
+
+# Required — scan for secrets and personal data
+bash tests/test-no-secrets.sh
+
+# Recommended — run the full suite
+bash tests/run-all.sh
+```
+
+If `test-no-secrets.sh` fails, the commit must not proceed. This is enforced by Rule 0 in CLAUDE.md.
+
+---
+
+## Coding Conventions
+
+**Shell scripts (`bin/`):**
+- Always start with `#!/usr/bin/env bash` and `set -euo pipefail`
+- Include a one-line comment after the shebang: `# ops-scriptname — what it does`
+- Emit JSON to stdout; emit errors to stderr (`2>/dev/null` at the call site silences them)
+- Scripts must be idempotent — calling them multiple times must not cause side effects
+- Never hardcode paths; use `$HOME`, `~`, `$CLAUDE_PLUGIN_ROOT`, or `$CLAUDE_PLUGIN_DATA_DIR`
+
+**Skills (`skills/`):**
+- One skill per directory; one `SKILL.md` per skill directory
+- Frontmatter `name` must match directory name exactly
+- Never include personal data, real org names, store URLs, or tokens in examples (Rule 0)
+- Use pre-execution shell blocks (`!` fences) to gather data before model context loads — this is the primary token-saving pattern used across all 22 skills
+
+**Agents (`agents/`):**
+- Agents are read-only by default — add `Write` and `Edit` to `disallowedTools` unless the agent genuinely needs to write files
+- C-suite agents run on `claude-opus-4-6`; scanner and fix agents run on `claude-sonnet-4-6`
+- Agents must not call other agents (`Agent` in `disallowedTools`) to prevent recursive spawning
+
+**Secrets and credentials:**
+- Never committed to the repo
+- Stored in `$PREFS_PATH` (preferences.json, gitignored), `scripts/registry.json` (gitignored), Claude Code's encrypted `userConfig` (`~/.claude.json`), or the credential resolution chain: Doppler → 1Password/Dashlane/Bitwarden → macOS Keychain → env vars
+
+---
+
+## Branch Conventions
+
+- `main` is the only long-lived branch
+- Feature branches: `feat/description` or `fix/description`
+- All changes go through a PR targeting `main`
+- No direct pushes to `main` (enforced at repo and org level)
+- Merge via `gh pr merge --merge --admin` (maintainers); external contributors require 1 approval
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full PR workflow.
diff --git a/docs/GETTING-STARTED.md b/docs/GETTING-STARTED.md
new file mode 100644
index 00000000..e5ebdb71
--- /dev/null
+++ b/docs/GETTING-STARTED.md
@@ -0,0 +1,186 @@
+<!-- generated-by: gsd-doc-writer -->
+# Getting Started with claude-ops
+
+claude-ops v0.8.0 — Business Operating System for Claude Code. This guide takes you from zero to your first morning briefing in under five minutes.
+
+---
+
+## Prerequisites
+
+- **Claude Code 1.0+** — the only hard requirement. Install from [claude.ai/code](https://claude.ai/code).
+
+Everything else (CLIs, tools, integrations) is installed automatically by `/ops:setup` via Homebrew on macOS, apt on Linux, or winget on Windows. No manual dependency management required.
+
+---
+
+## Installation
+
+### Option 1 — Marketplace (recommended)
+
+Install directly from the Claude Code plugin marketplace in two commands:
+
+```bash
+# Add the marketplace source
+/plugin marketplace add Lifecycle-Innovations-Limited/claude-ops
+
+# Install the plugin
+/plugin install ops@lifecycle-innovations-limited-claude-ops
+```
+
+### Option 2 — Local development
+
+Clone the repo and point Claude Code at the inner plugin directory:
+
+```bash
+git clone https://github.com/Lifecycle-Innovations-Limited/claude-ops.git
+claude --plugin-dir ./claude-ops/claude-ops
+```
+
+> **Why the nested `claude-ops/claude-ops/` path?** Claude Code's marketplace system requires a two-level layout. The repo root is the marketplace container; the inner `claude-ops/` directory is the actual plugin root that Claude Code loads. See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full explanation.
+
+To reload after making changes in local dev mode:
+
+```bash
+/reload-plugins
+```
+
+---
+
+## Setup Wizard (`/ops:setup`)
+
+Run the guided wizard immediately after installing:
+
+```
+/ops:setup
+```
+
+The wizard walks you through every integration in a conversational, step-by-step flow:
+
+1. **Preflight** — detects already-configured CLIs, credentials, and MCP servers. Reads from `/tmp/ops-preflight/` cache so no probe runs twice.
+2. **Core CLIs** — installs `jq`, `git`, `gh`, `aws`, and `node` if missing.
+3. **Daemon install** — installs `briefing-pre-warm` early (Step 2c) so it begins pre-fetching ECS health, git state, PRs, CI, and unread counts while you answer the remaining wizard questions. By the time setup finishes, your first `/ops:go` loads in **<3 seconds** from warm cache instead of ~30 seconds cold.
+4. **Channels** — configures each integration you choose: Telegram, WhatsApp, Gmail, Slack, Linear, Sentry, Vercel, Stripe, RevenueCat, Shopify, and more.
+5. **Project registry** — scans your local directories and builds `scripts/registry.json` with your project list.
+6. **Preferences** — saves your name, timezone, and default channels to `preferences.json` in Claude Code's plugin data directory.
+
+**Rules the wizard enforces:**
+
+- Never skips a channel silently — if a credential isn't found, you are always offered `[Paste manually]`, `[Deep hunt]`, or `[Skip]`.
+- Never installs anything without your confirmation.
+- Runs all probes in parallel and in the background — the conversation keeps moving while tools install.
+
+For credentials, the wizard resolves secrets in this order: Doppler → 1Password/Dashlane/Bitwarden → macOS Keychain → environment variables. If none are found, it asks you directly.
+
+See [CONFIGURATION.md](./CONFIGURATION.md) for the full list of configurable values and their plugin.json `userConfig` keys.
+
+---
+
+## Health Check (`/ops:doctor`)
+
+After setup, verify the plugin is healthy:
+
+```
+/ops:doctor
+```
+
+The doctor runs a diagnostic script and displays a report:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ OPS ► DOCTOR — 2026-04-14 09:00
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+ Plugin: 0.8.0 at /path/to/plugin
+ Skills: 22 defined
+ Agents: 12 defined
+ Bin scripts: 8 available
+
+ ERRORS 0
+ WARNINGS 0
+
+ TOOLS
+ [table of CLI tool availability]
+
+ ENV VARS
+ [table of env var status]
+
+ Registry: 19 projects
+ Preferences: configured
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If errors or warnings are found, the doctor automatically spawns a repair agent to fix them. After the agent completes, diagnostics re-run to confirm the fix. To check without auto-repairing:
+
+```
+/ops:doctor --check-only
+```
+
+---
+
+## First Briefing (`/ops:go`)
+
+Once the doctor reports all checks passing, run your first briefing:
+
+```
+/ops:go
+```
+
+Output looks like this:
+
+```
+╭──────────────────────────────────────────────────────────────────────────────╮
+│ /ops:go ► MORNING BRIEFING 2026-04-14 09:03 │
+├─────────────────────────────────┬────────────────────────────────────────────┤
+│ INFRA ████████████████ ok │ ECS: 4/4 healthy RDS: ok Redis: ok │
+│ CI/CD ████████████░░░░ 75% │ 3 passing 1 failing (my-api #847) │
+│ INBOX ░░░░░░░░░░░░░░░░ 14 │ Slack: 9 Telegram: 3 Gmail: 2 unread │
+│ PRs ████████████████ 3 │ 3 ready to merge 1 needs review │
+│ SPRINT ████████████░░░░ 67% │ Sprint 24 — 8 of 12 issues complete │
+│ REVENUE ████████████████ $ │ $2,847 MTD ↑12% vs last month │
+├─────────────────────────────────┴────────────────────────────────────────────┤
+│ Next action: merge feat/user-profile · fix my-api CI · reply @alice │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+Each section (INFRA, CI/CD, INBOX, PRs, SPRINT, REVENUE) is pre-gathered by shell scripts before model context loads — no extra latency. The `briefing-pre-warm` daemon runs every 2 minutes in the background so data is always warm.
+
+From here, explore the other 21 skills — see the full command table in the root [README.md](../README.md).
+
+---
+
+## Common Issues
+
+### Plugin not found after marketplace install
+
+The marketplace cache can lag by a few seconds. Try:
+
+```bash
+/plugin list
+/plugin install ops@lifecycle-innovations-limited-claude-ops
+```
+
+If the plugin still does not appear, confirm Claude Code is version 1.0 or later: `claude --version`.
+
+### `/ops:setup` hangs on a credential scan
+
+Background probes run in parallel during setup. If a step appears stuck for more than 30 seconds, it is likely waiting on a slow network probe (Doppler, keychain, password manager). You can safely answer the current `AskUserQuestion` — the wizard will resume when the background result arrives. If a probe never completes, `/ops:doctor` will flag the affected integration.
+
+### `/ops:go` shows cold load (~30s) on first run
+
+This means the `briefing-pre-warm` daemon was not installed during setup, or has not yet completed its first cycle. Run `/ops:setup` again and confirm the daemon step (Step 2c). After installation, pre-warm runs every 2 minutes — subsequent briefings will be fast.
+
+### Missing integration data in `/ops:go`
+
+Each integration only appears if its credential is configured. Run `/ops:doctor` to see which env vars or API keys are unset, then run `/ops:setup <section>` (e.g., `/ops:setup slack`) to configure just that integration.
+
+### WhatsApp shows `needs_auth`
+
+WhatsApp authentication requires a QR code scan on your phone — this is the one step that cannot be automated. Run `/ops:setup whatsapp` and point your phone camera at the QR code shown in the terminal.
+
+---
+
+## Next Steps
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) — how the plugin is structured, the daemon, and the two-level directory layout
+- [CONFIGURATION.md](./CONFIGURATION.md) — full reference for every configurable value, credential key, and userConfig field
+- [../CONTRIBUTING.md](../CONTRIBUTING.md) — branch rules, PR workflow, and how to add new skills
diff --git a/docs/TESTING.md b/docs/TESTING.md
new file mode 100644
index 00000000..3d55bd12
--- /dev/null
+++ b/docs/TESTING.md
@@ -0,0 +1,94 @@
+<!-- generated-by: gsd-doc-writer -->
+# Testing
+
+## Test framework and setup
+
+claude-ops uses a custom Bash-based test framework. There is no external test runner dependency — all tests are plain shell scripts executed directly with `bash`. Each script follows a consistent pattern: `ok()` / `err()` helpers accumulate pass/fail counts and the script exits non-zero if any check fails.
+
+Before running tests, install Node dependencies (required by `test-bin-scripts.sh` when `shellcheck` lints `.mjs` files indirectly, and by the CI syntax checks):
+
+```bash
+cd claude-ops
+npm ci
+```
+
+`shellcheck` is used by `test-bin-scripts.sh` when available. Install it with:
+
+```bash
+brew install shellcheck # macOS
+apt-get install shellcheck # Debian/Ubuntu
+```
+
+## Running tests
+
+Run the full test suite from the `claude-ops/` directory:
+
+```bash
+bash tests/run-all.sh
+```
+
+Run a single suite in isolation:
+
+```bash
+bash tests/test-skills-lint.sh
+bash tests/test-bin-scripts.sh
+bash tests/test-hooks.sh
+bash tests/test-template.sh
+bash tests/test-claude-md.sh
+bash tests/test-no-secrets.sh
+```
+
+`run-all.sh` executes all six suites in the order listed above, prints per-suite pass/fail, and exits 1 if any suite fails.
+
+## Writing new tests
+
+Test files live in `claude-ops/tests/` and are named `test-<area>.sh`. Each script must:
+
+1. Start with `#!/usr/bin/env bash` and `set -euo pipefail`.
+2. Resolve `PLUGIN_ROOT` relative to `$0` so the script is location-independent:
+ ```bash
+ PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+ ```
+3. Use the `ok()` / `err()` helper pattern and exit with code 1 when `$fail > 0`.
+4. Be registered in `run-all.sh` via a `run_suite "$TESTS_DIR/test-<area>.sh"` call.
+
+No shared test helper file exists — each script is self-contained.
+
+## Coverage requirements
+
+No line/branch/function coverage thresholds are configured. Coverage is structural: each test suite validates a specific area of the plugin (skills, bin scripts, hooks, templates, CLAUDE.md rules, secrets). A new feature is considered covered when a corresponding `test-<area>.sh` check exists for its key invariants.
+
+## CI integration
+
+**Workflow:** `.github/workflows/ci.yml` — "CI"
+
+**Triggers:** push to `dev`; pull requests targeting `dev` or `main`
+
+**Steps run in CI (in order):**
+
+1. Install Node dependencies: `cd claude-ops && npm ci`
+2. Syntax check Node scripts (`node --check`) for `ops-slack-autolink.mjs`, `ops-telegram-autolink.mjs`, and `telegram-server/index.js`
+3. Syntax check shell scripts (`bash -n`) for `ops-merge-scan`, `ops-prs`, `ops-ci`, `ops-git`, `ops-infra`, `ops-unread`, `ops-gather`, `ops-setup-detect`, `ops-setup-install`
+4. Prettier format check: `npx prettier --check "**/*.{js,mjs,json}"`
+5. Secret scanning: gitleaks v8.30.1 using `claude-ops/.gitleaks.toml`
+
+Note: the six `tests/` suite scripts are not currently invoked in CI — they run locally and in the pre-commit hook. The CI job focuses on syntax validity, formatting, and secret detection.
+
+## Pre-commit hook
+
+`.githooks/pre-commit` runs automatically on `git commit`. It:
+
+- Scans the staged diff for secrets and personal data (tokens, API keys, emails, hardcoded paths, phone numbers, IP addresses)
+- Invokes `tests/test-no-secrets.sh` against the full working tree
+
+To install the hook:
+
+```bash
+git config core.hooksPath .githooks
+```
+
+To bypass in an emergency (not recommended for this public repo):
+
+```bash
+git commit --no-verify
+```