# Agent Handoff Notes

Last updated: 2026-05-23

## Current Identity

- Product name: OrbitalWard
- Local repository path: `/home/ksmith/projects/OrbitalWard`
- Git remote: `https://git.firebugit.com/ksmith/OrbitalWard.git`
- Main branch: `main`
- Latest pushed commit at last update: `3b75075 Rename project to OrbitalWard`

The project was previously named InfraPulse. Do not reintroduce the old name in product copy, package names, environment variables, service names, or docs unless explicitly discussing historical context.

## Gitea Access

- Gitea API base: `https://git.firebugit.com/api/v1`
- Repository API path: `/repos/ksmith/OrbitalWard`
- Access token file: `/home/ksmith/.codex_security/gitea_token`

Never print the token value. Read it only inside commands that call the Gitea API.

## Current Product State

OrbitalWard is a secure monitoring appliance focused on the v0.1 vertical slice:

- Authenticated FastAPI backend with SQLAlchemy, Alembic, Pydantic, and JWT auth.
- React, TypeScript, Vite, and Tailwind frontend.
- Docker Compose development stack with PostgreSQL, Redis, backend, worker, and frontend.
- Website monitor create/edit/delete flow.
- HTTP status and expected-text checks.
- Optional TLS certificate expiry checks for HTTPS monitors.
- Ping and TCP port monitor create/edit/delete flow.
- Alert rules, incident opening/resolution, acknowledge, silence, and webhook notifications.
- Generic webhook, Mattermost, and Zoom Team Chat notification channels.
- Saved webhook URLs encrypted at rest and not returned to the UI.

## Verification State

After the rename and TLS expiry work, these checks passed in Docker:

- `docker compose -f docker-compose.dev.yml up -d --build`
- `docker compose -f docker-compose.dev.yml exec -T backend python -m pytest tests`
- `docker compose -f docker-compose.dev.yml exec -T frontend npm run typecheck`
- `docker compose -f docker-compose.dev.yml exec -T worker python -m compileall app`
- Backend health returned `{"status":"ok","service":"orbitalward-backend"}`.
- Direct worker probes for TCP and ICMP ping checks passed inside the Docker network.
- API probe created and deleted one ping monitor and one TCP monitor successfully.

The final Compose project uses `orbitalward-*` containers, images, network, and volumes.

## Important Implementation Notes

- `ORBITALWARD_SECRET_KEY` is the encryption/JWT secret environment variable.
- `DATABASE_URL` now defaults to the `orbitalward` database/user in Compose.
- The frontend local storage key is `orbitalward_token`.
- Notification default username is `OrbitalWard`.
- The TLS expiry check lives in `worker/app/collectors/website.py` and is enabled per monitor through JSON config fields:
  - `check_tls_expiry`
  - `tls_warning_days`

## Issue Tracker Workflow

Use the Gitea API with the token file above. Useful endpoints:

- List issues: `GET /repos/ksmith/OrbitalWard/issues?state=all`
- Create issue: `POST /repos/ksmith/OrbitalWard/issues`
- Update issue: `PATCH /repos/ksmith/OrbitalWard/issues/{index}`
- List milestones: `GET /repos/ksmith/OrbitalWard/milestones`
- List labels: `GET /repos/ksmith/OrbitalWard/labels`

Issue source docs:

- `docs/gitea-issues.md`
- `docs/progress.md`
- `docs/roadmap.md`

Current completed items include TLS expiry monitor support, HTTP/website checks, ping and TCP port checks, basic alert evaluation, incident actions, and webhook notification channels. The next recommended implementation issue is alert rule editing UI.

## Guardrails

- Never commit or push changes without explicit user approval for that specific commit/push.
- Keep monitoring separate from alerting.
- Do not expose raw SNMP OIDs in the normal UI.
- Use friendly names, profiles, and guided setup instead of raw configuration.
- Do not include LANCache in product scope.
- Avoid broad NMS features until the v0.1 vertical slice is stable.
- Never log secrets or return saved secret values after creation.