# Project: Tools (CTM + Wall-E)

## Service Management

NEVER kill CTM or Wall-E processes directly (e.g. `kill`, `lsof | xargs kill`, `pkill`).
Always use the restart API or helper script — they handle graceful shutdown and auto-respawn.

- **Restart CTM**: `bash claude-task-manager/bin/restart-ctm.sh` or `curl -sX POST http://localhost:3456/api/restart/ctm?force=true`
- **Restart Wall-E**: `curl -sX POST http://localhost:3456/api/restart/walle`
- **Stop Wall-E**: `curl -sX POST http://localhost:3456/api/stop/walle`
- **Start Wall-E**: `curl -sX POST http://localhost:3456/api/start/walle`
- **Check status**: `curl -s http://localhost:3456/api/services/status`

## CTM Development — CRITICAL SAFETY RULE

**NEVER test code changes against the primary instance (port 3456/3457).**
The primary instance is the user's live workbench — restarting or testing against it
kills all active sessions. This applies to ALL operations: curl, fetch, restart, etc.

When developing CTM or Wall-E code:
1. Use the `/ctm-dev` skill (or run it manually)
2. Start a dev instance: `bash bin/dev.sh --fresh` or `bash bin/dev.sh --refresh`
3. Read the printed `Dev CTM:` URL and use that port for all curl/browser tests
4. Test ONLY against your dev port, never 3456
5. Only restart primary when the user explicitly asks — and ask for confirmation first

## Testing

Both projects use Node.js built-in test runner with `--test-force-exit` to prevent hangs:
- **Wall-E**: `cd wall-e && npm test`
- **CTM**: `cd claude-task-manager && npm test`

When writing new tests, follow these rules to avoid handle leaks and cross-test contamination:
- **Never set `process.env` at module top level** — set in `before()`, restore in `after()`
- **Close every DB connection you open** — store `readDb` handles in module scope, close in `after()`/teardown
- **Call `brain.closeDb()` before `brain.initDb()`** in tests that reinitialize the brain singleton
- **Don't change `journal_mode`** on readonly connections (causes SQLITE_BUSY against WAL dbs)

## Publishing to npm (create-walle)

When publishing with `/publish`:
1. **Always review and update `create-walle/README.md`** before publishing — this is the npm doc page shown on https://www.npmjs.com/package/create-walle
2. Check that feature descriptions, skill counts, and capabilities match the current codebase
3. Bump version in both `create-walle/package.json` AND root `package.json`
4. Run `bash build.sh` and verify file count
5. Ask for confirmation before `npm publish`

## Architecture reference

For Wall-E architecture (loops, brain DB, scheduler, skills, channels, anti-patterns):
read `wall-e/docs/architecture.md` before making non-trivial changes. The
"Non-goals" section is a guardrail — coordinate via data, not via
manager-of-managers.
