Merge pull request 'chore: gardener housekeeping 2026-04-05' (#8) from chore/gardener-20260405-1804 into master

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Agent Brief: Harb Stack
 
 ## What is KRAIKEN?
@@ -32,6 +32,10 @@ KRAIKEN couples Harberger-tax staking with a dominant Uniswap V3 liquidity manag
 ```
 See [docs/dev-environment.md](docs/dev-environment.md) for restart modes, ports, Docker topology, and common pitfalls.
 
+## Docker / LXD Notes
+- Containers require `security_opt: apparmor=unconfined` when running inside LXD to avoid permission denied errors on Unix socket creation (Anvil, Postgres).
+- Umami analytics runs on **port 3001** (moved from 3000 to avoid conflict with Forgejo when running alongside the disinto factory stack).
+
 ## 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
@@ -48,6 +52,7 @@ The red-team agent (`scripts/harb-evaluator/red-team.sh`) injects the following
 - **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.
+- **viem v2 slot0**: `slot0()` returns an array, not a record. `tick` is at index 1 (e.g. `slot0Response[1]`), not `slot0Response.tick`.
 
 ## 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.

formulas/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Agent Brief: Formulas
 
 Formulas are TOML files that declare automated pipeline jobs for the harb evaluator.

gardener/pending-actions.json

@@ -1,22 +1 @@
-[
+[]
-  {
-    "action": "comment",
-    "issue": 1179,
-    "body": "Closing: action complete. Post-fix user-test run (`evidence/user-test/2026-03-27-post-stake-fix.json`) verified the /stakestake navigation bug (PR #1171) is fixed — all 3 personas that reached /stake navigated correctly with no invalid route. The prediction concern is resolved. New ponder 504 issue and chain-revert state corruption were discovered as separate items."
-  },
-  {
-    "action": "close",
-    "issue": 1179,
-    "reason": "actioned and verified — /stakestake fix confirmed working in post-fix user-test 2026-03-27"
-  },
-  {
-    "action": "comment",
-    "issue": 1177,
-    "body": "Closing: action complete. A fresh red-team session was run on 2026-03-27 (`evidence/red-team/2026-03-27.json`): 7 real attacks with full per-attack data, floor_held: true, verdict: floor_held. The ghost run concern is addressed — the new run provides the real evidence the 2026-03-26 ghost run lacked."
-  },
-  {
-    "action": "close",
-    "issue": 1177,
-    "reason": "actioned and verified — fresh red-team run 2026-03-27 completed with 7 real attacks"
-  }
-]

kraiken-lib/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Kraiken Library - Agent Guide
 
 Shared TypeScript helpers used by the landing app, txnBot, and other services to talk to KRAIKEN contracts and the Ponder GraphQL API.

landing/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Landing Interface - Agent Guide
 
 Vue 3 + Vite application that delivers the public marketing site and forthcoming staking UI.

onchain/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Agent Brief: Kraiken Protocol
 
 ## Protocol Philosophy & Business Logic

scripts/harb-evaluator/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Agent Brief: harb-evaluator
 
 The evaluator runtime executes formula-defined pipelines. Scripts in this

services/ponder/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Ponder Indexer - Agent Guide
 
 Ponder-based indexer that records Kraiken protocol activity and exposes the GraphQL API consumed by the app and automation bot.
@@ -13,8 +13,15 @@ Ponder-based indexer that records Kraiken protocol activity and exposes the Grap
 - `ponder.config.ts` - Network selection and contract bindings (update addresses after deployments).
 - `ponder.schema.ts` - Stats, hourly data, and position tables.
 - `src/kraiken.ts` / `src/stake.ts` - Event handlers; rely on Ponder v0.13 helpers for on-chain reads during sync.
+- `src/helpers/stats.ts` - Ring buffer logic; `MINIMUM_BLOCKS_FOR_RINGBUFFER` is configurable via env var (see below).
 - `.ponder/` - Local SQLite/state cache (safe to delete when schemas change).
 
+## Environment Variables
+- `LM_ADDRESS` — LiquidityManager contract address; must be set in `.env.local` for correct contract binding. Bootstrap (`containers/bootstrap.sh`) writes this automatically.
+- `POOL_ADDRESS` — Uniswap V3 pool address; discovered from the Uniswap factory during bootstrap and written to `.env.local`. Ponder uses this for pool event indexing.
+- `MINIMUM_BLOCKS_FOR_RINGBUFFER` — Override the minimum block count before ring buffer data is populated (default: 100). Set to `0` for local dev so early events populate the ring buffer from genesis.
+- `START_BLOCK` — Deploy block number; written by bootstrap; used as the Ponder `startBlock` for all contract event sources.
+
 ## Development Workflow
 - Primary path: `nohup ./scripts/dev.sh start &` boots Anvil, deploys contracts, and launches Ponder in watch mode.
 - Docker stack: `docker-compose up -d` starts all services including PostgreSQL; bootstrap creates `.env.local` automatically.
@@ -25,6 +32,7 @@ Ponder-based indexer that records Kraiken protocol activity and exposes the Grap
 - Confirm handler timestamps are monotonic; large gaps (>168 hours) reset the ring buffer by design.
 - Regenerate typings after schema edits by restarting Ponder; generated artifacts live in `generated/`.
 - If the stack script fails during boot, check `.ponder/logs` and RPC quota usage before rerunning.
+- If protocol activity statistics show all zeros, verify `LM_ADDRESS` and `POOL_ADDRESS` are present in `.env.local` — the indexer silently watches the wrong (zero) address if they are missing.
 
 ## Containerized Environment (Podman/Docker)
 - **Environment Loading**: `.env.local` must be explicitly sourced in the entrypoint script before `npm run dev`. Ponder's built-in env loader may not find it in containerized environments.

services/txnBot/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Transaction Bot - Agent Guide
 
 Automation service that maintains liquidity alignment and tax enforcement for the KRAIKEN protocol.

web-app/AGENTS.md

@@ -1,4 +1,4 @@
-<!-- last-reviewed: 79a93d41608f2cbe3b990f4613d04d310642bd2c -->
+<!-- last-reviewed: 62ba6f24fd0cf770dd8c3738563cb0bdeb48d6ea -->
 # Web App - Agent Guide
 
 Vue 3 + TypeScript staking interface for KRAIKEN, enabling users to stake tokens, manage positions, and interact with Harberger-tax mechanics.
@@ -34,6 +34,10 @@ Vue 3 + TypeScript staking interface for KRAIKEN, enabling users to stake tokens
 - `ChartComplete.vue` — Position visualization
 - `CollapseActive.vue` — Expandable position card with actions
 
+## viem v2 Contract Call Patterns
+- **`slot0()` returns an array, not a record.** `tick` is at index 1: `slot0Response[1]`. Do not access `slot0Response.tick` — that was viem v1 behaviour. `CheatsView.vue` handles both formats for backward compat.
+- When adding new contract reads, check whether viem v2 returns an array or named tuple before indexing into the result.
+
 ## Development Workflow
 - Boot full stack: `./scripts/dev.sh start` (see root AGENTS.md)
 - Targeted: `npm run dev` (assumes Ponder/Anvil already running)