harb/AGENTS.md

<!-- last-reviewed: 4dedc723753c1fb776766cd22ff56e5659d2bbb0 -->
# Agent Brief: Harb Stack

## What is KRAIKEN?
KRAIKEN couples Harberger-tax staking with a dominant Uniswap V3 liquidity manager to create asymmetric slippage, sentiment-driven pricing, and VWAP "price memory" safeguards. Liquidity dominance is mission-critical; treat any regression that weakens the LiquidityManager's control as a priority incident.

## User Journey
1. **Buy** — Acquire KRAIKEN on Uniswap.
2. **Stake** — Declare a tax rate on kraiken.org to earn from protocol growth.
3. **Compete** — Snatch undervalued positions to optimise returns.

## Directory Map
| Path | What | Guide |
|------|------|-------|
| `onchain/` | Solidity + Foundry contracts, deploy scripts, fuzzing | [onchain/AGENTS.md](onchain/AGENTS.md) |
| `services/ponder/` | Ponder indexer powering the GraphQL API | [services/ponder/AGENTS.md](services/ponder/AGENTS.md) |
| `landing/` | Vue 3 marketing + staking interface | [landing/AGENTS.md](landing/AGENTS.md) |
| `web-app/` | Staking UI | [web-app/AGENTS.md](web-app/AGENTS.md) |
| `kraiken-lib/` | Shared TypeScript helpers for clients and bots | [kraiken-lib/AGENTS.md](kraiken-lib/AGENTS.md) |
| `services/txnBot/` | Automation bot for `recenter()` and `payTax()` upkeep | [services/txnBot/AGENTS.md](services/txnBot/AGENTS.md) |
| `formulas/` | TOML pipeline definitions (sense/act) for the evaluator | [formulas/AGENTS.md](formulas/AGENTS.md) |
| `scripts/` | `dev.sh`, bootstrap, build helpers; `harb-evaluator/` red-team agent | [scripts/harb-evaluator/AGENTS.md](scripts/harb-evaluator/AGENTS.md) |
| `packages/analytics/` | `@harb/analytics` — self-hosted Umami wrapper for funnel tracking | — |
| `tests/e2e/` | Playwright end-to-end tests — desktop + mobile viewports (iPhone 14, Pixel 7), Chromium + Firefox cross-browser matrix; includes conversion funnel spec (`07-conversion-funnel.spec.ts`) | — |
| `docs/` | Architecture, product truth, environment, ops guides | — |

## Quick Start
```bash
./scripts/dev.sh start    # boots full stack (~3-6 min first time)
./scripts/dev.sh health   # verify all services healthy
./scripts/dev.sh stop     # stop and clean up
```
See [docs/dev-environment.md](docs/dev-environment.md) for restart modes, ports, Docker topology, and common pitfalls.

## Red-team Agent Context
The red-team agent (`scripts/harb-evaluator/red-team.sh`) injects the following Solidity sources into the agent prompt so it can reason from exact contract logic:
- `LiquidityManager.sol` — three-position manager, recenter, floor formula
- `ThreePositionStrategy.sol` — position lifecycle abstractions
- `Optimizer.sol` / `OptimizerV3.sol` — current candidate under test
- `VWAPTracker.sol` / `PriceOracle.sol` — price oracle and VWAP mechanics
- `Kraiken.sol` — `outstandingSupply()`, KRK mint/burn, transfer mechanics
- `Stake.sol` — `snatch()`, withdrawal, KRK exclusion from floor denominator

## Key Patterns
- **ES Modules everywhere**: The entire stack uses `"type": "module"` and `import` syntax.
- **`token0isWeth`**: Flips amount semantics; confirm ordering before seeding or interpreting liquidity.
- **Price^2 (X96)**: VWAP, `ethScarcity`, and Optimizer outputs operate on price^2. Avoid "normalising" to sqrt inadvertently.
- **LiquidityManager funding**: Fund with Base WETH (`0x4200...0006`) before expecting `recenter()` to succeed.
- **Ponder state**: Stored in `.ponder/`; drop the directory if schema changes break migrations.
- **Harberger staking** supplies the sentiment oracle that drives Optimizer parameters, which in turn tune liquidity placement and supply expansion.

## Engineering Principles
These apply to infrastructure (Docker, scripts, startup/teardown) and test/scenario execution — NOT to frontend polling of HTTP APIs where caching is the correct solution.

1. **Never use fixed delays or `waitForTimeout`** — react to actual events instead. Use `eth_subscribe` (WebSocket) for on-chain push notifications, `eth_newFilter` + `eth_getFilterChanges` for on-chain polling, DOM mutation observers or Playwright's `waitForSelector`/`waitForURL` for UI changes, callback patterns for async flows. Even if event-driven code takes more effort, it is always the right answer.
2. **Never use hardcoded expectations** — dynamic systems change. React to actual state, not assumed state. Don't assert a specific block number, token amount, or address unless it's a protocol constant.
3. **Event subscription > polling with timeout > fixed delay** — prefer true push subscriptions (`eth_subscribe`, WebSocket, observers). When push is unavailable (e.g. HTTP-only RPC), polling with a timeout and clear error is acceptable. A fixed `sleep`/`wait`/`waitForTimeout` is never acceptable. Existing violations should be replaced when touched.

**Note:** Frontend components polling HTTP APIs (e.g. LiveStats polling Ponder GraphQL) are fine — the scalability solution there is caching at the proxy layer, not subscriptions.

## Before Opening a PR
1. `forge build && forge test` in `onchain/` — contracts must compile and pass.
2. Run `npm run test:e2e` from repo root if you touched frontend or services.
3. `git diff --check` — no trailing whitespace or merge markers.
4. Keep commits clean; never leave commented-out code or untested changes.
5. If you changed `kraiken-lib`, rebuild: `./scripts/build-kraiken-lib.sh`.
6. If you changed contract VERSION or events, update `COMPATIBLE_CONTRACT_VERSIONS` in `kraiken-lib/src/version.ts`.

## Code Quality & Git Hooks
Pre-commit hooks (Husky + lint-staged) run ESLint + Prettier on staged files. Each component has its own `.lintstagedrc.json`. To test manually: `git add <files> && .husky/pre-commit`.

## Deeper Docs
| Topic | File |
|-------|------|
| Dev environment, Docker, ports, pitfalls | [docs/dev-environment.md](docs/dev-environment.md) |
| Woodpecker CI setup and debugging | [docs/ci-pipeline.md](docs/ci-pipeline.md) |
| Testing: Foundry, E2E, version validation | [docs/testing.md](docs/testing.md) |
| Codeberg API access and webhooks | [docs/codeberg-api.md](docs/codeberg-api.md) |
| Product truth and positioning | [docs/PRODUCT-TRUTH.md](docs/PRODUCT-TRUTH.md) |
| Architecture overview | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
| UX decisions | [docs/UX-DECISIONS.md](docs/UX-DECISIONS.md) |
| Environment configuration | [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) |
| Version validation architecture | [VERSION_VALIDATION.md](VERSION_VALIDATION.md) |
| Uniswap V3 math deep dive | [onchain/UNISWAP_V3_MATH.md](onchain/UNISWAP_V3_MATH.md) |
| Technical appendix | [TECHNICAL_APPENDIX.md](TECHNICAL_APPENDIX.md) |
| Harberger tax mechanics | [HARBERG.md](HARBERG.md) |

## References
- Deployment history: `onchain/deployments-local.json`, `onchain/broadcast/`.