popagent

Latest change 7f0ff66d6d9fb6468416c58bee46bd3d08169501 - Checkpoint browser channels and memory work by AkurAI Build

# Repository rules

## Run

- `bun run dev` (watch) / `bun run start` serves UI and API on `PORT`
  (default 3000).
- The Bun process requires `DATABASE_URL` and the isolated
  `OBSERVABILITY_DATABASE_URL`. Secret-tool operations additionally require
  `POPAGENT_SECRET_KEY`; `POSTGRES_PASSWORD` and
  `OBSERVABILITY_POSTGRES_PASSWORD` bootstrap the Compose databases. 9Router,
  SearXNG, retention, environment, and managed-hook settings are documented in
  `.env.example`.
- Development is test-driven for every observable behavior change. Before
  implementation, add or update the narrowest automated contract that fails for
  the missing behavior or regression. Confirm that the failure is relevant,
  then implement until it passes. A behavior-preserving refactor may begin from
  green characterization tests, but must not reduce coverage.
- `bun test <file>` is the preferred inner loop for the changed contract.
  `bun test` runs the full suite before handoff. Run isolated protocol/UI-helper
  tests, TypeScript checks, and other deterministic toolchain checks locally for
  fast feedback. Use disposable local PostgreSQL when a storage test needs it.
- Match tests to the changed boundary: stores need persistence and migration
  contracts; routes need status, validation, authentication, and response-shape
  contracts; event streams need connect, event, disconnect, and reconnect
  contracts; React changes need runtime coverage for mount, update, navigation,
  and unmount behavior. A TypeScript check is never a runtime-test substitute.
- Tests that call live 9Router models or shared services run on Titan. Start
  narrow, expand to the affected suite after green, and run the full suite once
  at the end; do not repeatedly pay for project-wide verification while editing.
- Domain files name contract owners and environment-specific exceptions only;
  keep this test sequence canonical instead of repeating it per subsystem.
- Do not report behavior as fixed, complete, working, or verified until all
  required checks have run after the final relevant edit. Report exact commands
  and results, distinguish narrow checks from the full suite, and disclose every
  skipped, unavailable, flaky, or environment-dependent check. For a reported
  regression, reproduce it first and add an automated regression contract before
  changing implementation whenever technically possible.
- UI changes require desktop and mobile browser verification after the final UI
  edit. At minimum exercise initial load, applicable loading/empty/error states,
  the changed interaction, route navigation, and component unmount/remount, then
  inspect console errors and failed requests. Streaming UI must additionally
  verify connection, event delivery, cancellation, route-away cleanup, reconnect,
  and polling fallback. Helper tests alone do not satisfy this browser gate.
- The running instance is `http://192.168.1.10:5180` on Titan. PostgreSQL
  container `popagent-postgres` binds only `127.0.0.1:5433`; durable data is in
  volume `popagent-postgres`. Observability PostgreSQL container
  `popagent-observability-postgres` binds only `127.0.0.1:5435` with durable
  state in volume `popagent-observability-postgres`. The `omniroute` container provides 9Router on
  `127.0.0.1:20128` with durable state in volume `omniroute-data`. SearXNG
  container `popagent-searxng` binds only `127.0.0.1:8889` and provides the
  agents' JSON web-search API.

## Source workflow

- Git is local-only for this repository. Commit changes locally; do not push.
- Local checks are the development loop. Copy changed files to
  `/home/olibuijr/Projects/popagent` on Titan only for live-service integration,
  authoritative full-suite verification, or deployment.
- Restart `popagent.service` after backend route changes; Bun hot reload covers
  UI source changes but does not reliably replace the running `Bun.serve` route
  table.
- Credentials belong in the ignored `.env`; application-managed secrets belong
  in PostgreSQL through the secret tools. Do not create or use `.secrets/`.
- Every behavior, architecture, configuration, or operating-rule change must
  update the relevant `AGENTS*.md` domain file in the same change. Remove stale
  facts instead of preserving historical guidance or duplicating another domain.

## Documentation layout

- `AGENTS.md` is an index only. Put operating rules and durable domain facts in
  the linked domain files.
- `.agents/skills/` contains task-triggered, repeatable workflows. Skills must
  reference the canonical domain files instead of copying architecture or
  policy into their instructions.
- Keep safety boundaries and facts required for every related change in the
  domain files; do not hide them exclusively in a skill whose loading is
  conditional.
- Keep each `AGENTS*.md` file at or below 500 lines. Split any file that exceeds
  500 lines into focused `AGENTS_$DOMAIN.md` files and add each new file to the
  index.

## Style

Ponytail: use the smallest solution that works; prefer native or installed
capabilities over new code; avoid speculative abstractions. The TDD and
verification gates above apply even when the implementation appears trivial.