OrbitWard/docs/agent-handoff.md

Agent Handoff Notes

Last updated: 2026-05-26

Current Identity

• Product name: OrbitWard
• Local repository path: /home/ksmith/projects/OrbitalWard until the working directory is moved
• Git remote: https://git.firebugit.com/ksmith/OrbitWard.git
• Main branch: main
• Latest pushed commit: check origin/main with git log -1 --oneline origin/main

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/OrbitWard
• 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

OrbitWard 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.
• SNMPv2c credential profiles with encrypted community strings.
• Guided SNMP device discovery with friendly device, interface, and monitorable item results.
• Asset setup supports creating, selecting, and deleting assets, plus attaching ping, TCP, website, and SNMP monitors without creating alert rules automatically.
• Worker collects configured SNMP uptime, interface status, traffic counter, error, and discard monitors.
• SNMP profile mapping exposes friendly capability flags plus CPU, memory, storage, and standard sensor monitorable items when supported.
• Worker collects configured SNMP CPU load, memory usage, storage usage, and standard sensor value/status monitors.

Verification State

Recent Docker checks:

• docker compose -f docker-compose.dev.yml run --rm backend sh -c "pip install -e '.[test]' && python -m pytest tests/test_discovery.py tests/test_monitors.py"
• docker compose -f docker-compose.dev.yml run --rm frontend npm run typecheck
• docker compose -f docker-compose.dev.yml run --rm frontend npm run build
• docker compose -f docker-compose.dev.yml run --rm worker python -m unittest discover -s tests
• docker compose -f docker-compose.dev.yml run --rm worker python -m compileall app
• docker compose -f docker-compose.dev.yml run --rm backend sh -c "pip install -e '.[test]' >/dev/null && python -m compileall app"

Earlier rename and monitor work also verified:

• docker compose -f docker-compose.dev.yml up -d --build
• Backend health returned {"status":"ok","service":"orbitward-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 orbitward-* containers, images, network, and volumes.

Important Implementation Notes

• ORBITWARD_SECRET_KEY is the encryption/JWT secret environment variable.
• DATABASE_URL now defaults to the orbitward database/user in Compose.
• The frontend local storage key is orbitward_token.
• Notification default username is OrbitWard.
• 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/OrbitWard/issues?state=all
• Create issue: POST /repos/ksmith/OrbitWard/issues
• Update issue: PATCH /repos/ksmith/OrbitWard/issues/{index}
• List milestones: GET /repos/ksmith/OrbitWard/milestones
• List labels: GET /repos/ksmith/OrbitWard/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, alert rule editing UI, incident actions, webhook notification channels, SNMPv2c credential profiles, the SNMP device discovery API, guided SNMP discovery UI, asset-based monitor setup, initial SNMP collection for uptime plus interface counters/status, and SNMP profile mapping for standard CPU, memory, storage, and sensor health items. The next recommended implementation work is notification routing/policies or email/SMTP notifications.

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.