# Development

Set up a local development environment and run the test suites.

## Setup

```bash
git clone git@github.com:mrkhachaturov/hindclaw.git
cd hindclaw
npm install
npm run build    # TypeScript -> dist/
npm test         # unit tests
```

## Source Structure

```
src/
├── index.ts              # Plugin entry: init + hook registration
├── client.ts             # Stateless Hindsight HTTP client (bankId per-call)
├── types.ts              # Full type system
├── config.ts             # Config resolver + bank file parser + $include
├── utils.ts              # Shared utilities
├── hooks/
│   ├── recall.ts         # before_prompt_build (single + multi-bank + reflect)
│   ├── retain.ts         # agent_end (tags, context, observation_scopes)
│   └── session-start.ts  # session_start (mental models)
├── embed-manager.ts      # Local daemon lifecycle
├── derive-bank-id.ts     # Bank ID derivation
└── format.ts             # Memory formatting
```

## Key Patterns

**Two-level config.** Plugin defaults in `openclaw.json` + per-agent overrides. Shallow merge, agent entry wins.

**Stateless client.** Every client method takes `bankId` as first parameter. No instance-level bank state. Enables multi-bank operations.

**Server-side vs behavioral.** `snake_case` fields = server-side (managed via Terraform). `camelCase` fields = behavioral (used by hooks at runtime).

**Graceful degradation.** All hooks catch errors and log warnings. Never crash the gateway.

## Testing

```bash
npm test                   # unit tests (vitest)
npm run test:integration   # needs running Hindsight API
```

Integration test environment:

| Variable | Default | Description |
|----------|---------|-------------|
| `HINDSIGHT_API_URL` | `http://localhost:8888` | Hindsight server URL |
| `HINDSIGHT_API_TOKEN` | -- | Auth token (optional) |

## Publishing

Push a `v*` tag -- GitHub Actions publishes to npm via OIDC trusted publisher.

Before tagging:

1. Bump version in `package.json`
2. Add changelog entry in `CHANGELOG.md` with the exact same version (workflow reads it by tag)
3. Commit both files
4. Tag and push

```bash
git tag v0.2.0
git push origin main --tags
```