popagent

public

Latest change 2c7138e7ddf8cb6b5ac0dc1abbe6d76743366c19 - Checkpoint workspace and secret management 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; `bunfig.toml` excludes the ignored
`workspace/**` agent checkouts from discovery. 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 and deployment workflow

- The public AkurAI Build repository at `https://akurai-build.olibuijr.com/git/popagent.git` is the Git synchronization boundary. Keep it free of credentials and runtime data. Commit locally; never copy or rsync source between Midget and Titan.
- `./deploy.sh publish` is the only publication path. It requires a clean `main`, runs built-in privacy checks plus Gitleaks when installed, and accepts optional Git credentials only through transient `POPAGENT_GIT_USERNAME`/`POPAGENT_GIT_TOKEN` environment variables.
- `./deploy.sh deploy` is the only deployment and service-restart path. From Midget it verifies that HEAD is published, then triggers Titan over SSH. On Titan it refuses dirty/divergent work, fast-forwards from public `main`, locks concurrent deployment, provisions disposable test databases, runs TypeScript and the full suite, validates a candidate on a temporary port, briefly restarts systemd, monitors protected `/api/health` for 60 seconds, and rolls back a failed release.
- Deployment starts required local Compose dependencies and aborts if live integration dependencies cannot be repaired. SQL changes trigger mode-restricted application and observability dumps under `POPAGENT_DATA_DIR/backups`; the newest ten are retained. Migrations must remain backward-compatible across the candidate and previous release.
- Deployment prefers a user systemd service and installs a system service only when run as root. Do not manually restart `popagent.service`, mutate the deployed checkout, or bypass the full-suite gate. Deployment logs and the current release marker live under `POPAGENT_DATA_DIR/deploy`.
- Credentials belong in the ignored mode-0600 `.env`; application-managed secrets belong in PostgreSQL through the secret tools. Do not create or use `.secrets/`. Missing deployment configuration is an error, never a reason to generate or restore credentials.
- 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.