### Tool Hierarchy

When searching for information across indexed paths, **always use `watcher_search` before filesystem commands** (`exec`, `grep`, `find`). The semantic index covers the full indexed corpus and surfaces related files you may not have considered.

Use `watcher_scan` (no embeddings, no query string) for structural queries: file enumeration, staleness checks, domain listing, counts.

Direct filesystem access is for **acting on** search results, not bypassing them.

### Shell Scripting

Default to `node -e` or `.js` scripts for `exec` calls. PowerShell corrupts multi-byte UTF-8 characters and mangles escaping. Use PowerShell only for Windows service management, registry operations, and similar platform-specific tasks.

### File Bridge for External Repos

When editing files outside the workspace, use the bridge pattern: copy in → edit the workspace copy → bridge out. Never write temp patch scripts. The workspace is the authoritative working directory.

### Gateway Self-Destruction Warning

⚠️ Any command that stops the gateway **stops the assistant**. Never run `openclaw gateway stop` or `openclaw gateway restart` without explicit owner approval. When approved, it must be the **absolute last action** — all other work must be complete first, all messages sent, all files saved.

### Messaging

**Same-channel replies:** Don't use the `message` tool. It fires immediately, jumping ahead of streaming narration. Just write text as your response.

**Cross-channel sends:** Use the `message` tool with an explicit `target` to send to a different channel or DM.

### Slack File Downloads

To download a Slack-hosted file, first try the `message` tool's `download-file` action. If that fails, fall back to a direct HTTP fetch using the bot token:

```js
fetch(url_private_download, {
  headers: { Authorization: 'Bearer ' + botToken },
});
```

The bot token is at `channels.slack.accounts.default.botToken` in `openclaw.json`.

Never tell the user a file can't be downloaded until both methods have been tried.

### Plugin Lifecycle

```bash
# Platform bootstrap (content seeding)
npx @karmaniverous/jeeves install

# Component plugin install
npx @karmaniverous/jeeves-{component}-openclaw install

# Component plugin uninstall
npx @karmaniverous/jeeves-{component}-openclaw uninstall

# Platform teardown (remove managed sections)
npx @karmaniverous/jeeves uninstall
```

Never manually edit `~/.openclaw/extensions/`. Always use the CLI commands above.

### Reference Templates

{{#if templatePath}}
Reference templates are available at `{{templatePath}}`:

| Template | Purpose |
|----------|---------|
| `spec.md` | Skeleton for new product specifications — all section headers, decision format, dev plan format |
| `spec-to-code-guide.md` | The spec-to-code development practice — 7-stage iterative process, convergence loops, release gates |

Read these templates when creating new specs, onboarding to new projects, or when asked about the development process.
{{else}}
> Reference templates not yet installed. Run `npx @karmaniverous/jeeves install` to seed templates.
{{/if}}

### Post-Upgrade Maintenance

After updating OpenClaw (`npm install -g openclaw@latest` or equivalent), reinstall all Jeeves component plugins to repair install state:

```bash
npx @karmaniverous/jeeves install
npx @karmaniverous/jeeves-runner-openclaw install
npx @karmaniverous/jeeves-watcher-openclaw install
npx @karmaniverous/jeeves-server-openclaw install
npx @karmaniverous/jeeves-meta-openclaw install
```

Then restart the gateway. Plugin installers copy dist files and patch config; reinstalling after an OpenClaw update ensures the extensions directory stays consistent.

### Source Code Preference

{{#if devRepos}}
When investigating, debugging, or analyzing Jeeves components, always read TypeScript source from dev repos — never compiled `dist/` from the global npm install. Dev repos:

| Component | Dev Repo |
|-----------|----------|
{{#each devRepos}}
| {{@key}} | `{{this}}` |
{{/each}}

Built code is minified, harder to reason about, and wastes context. Always `git pull` before analysis.
{{else}}
> Dev repo paths not configured. Add `core.devRepos` to `jeeves.config.json` to enable source code preference guidance.
{{/if}}