popagent

Latest change 6edc7e928c57dab23c0973ed3f7ee70b3ebb72d5 - Initial popagent baseline 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`. Secret-tool operations additionally
  require `POPAGENT_SECRET_KEY`; `POSTGRES_PASSWORD` bootstraps the Compose
  database. 9Router, SearXNG, and managed-hook settings are documented in
  `.env.example`.
- `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.
- 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.
- 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`. 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. Add tests for new
observable contracts.