Documentation Overhaul

Docs/integrations.md

@@ -0,0 +1,50 @@
+# Integrations
+[Back to Docs Index](index.md) | [Index (HTML)](index.html)
+
+## Purpose
+Document external integrations used by Borealis, primarily the GitHub repository hash service.
+
+## GitHub Integration (Repository Hash)
+- The Engine can query GitHub for the latest commit hash of a repository/branch.
+- Results are cached locally to reduce API usage.
+- Admins can store a GitHub API token via the WebUI.
+
+## API Endpoints
+- `GET /api/github/token` (Admin) - GitHub token status.
+- `POST /api/github/token` (Admin) - update GitHub token.
+- `GET /api/repo/current_hash` (Device or Token Authenticated) - current repo hash.
+
+## Related Documentation
+- [Engine Runtime](engine-runtime.md)
+- [API Reference](api-reference.md)
+- [Logging and Operations](logging-and-operations.md)
+
+## Codex Agent (Detailed)
+### Integration implementation
+- `Data/Engine/integrations/github.py` implements `GitHubIntegration`.
+- The integration uses:
+  - Cached results stored in `repo_hash_cache.json` (under the Engine cache directory).
+  - Token storage in the `github_token` SQLite table.
+
+### Defaults and overrides
+- Default repo: `bunny-lab-io/Borealis`.
+- Default branch: `main`.
+- Environment overrides:
+  - `BOREALIS_REPO`
+  - `BOREALIS_REPO_BRANCH`
+- Cache TTL can be overridden via Engine config (`repo_hash_refresh`).
+
+### Token management
+- Admins manage tokens via `/api/github/token`.
+- The token is stored in the Engine database (`github_token` table).
+- `GitHubIntegration.verify_token()` reports validity and rate-limit status.
+
+### `GET /api/repo/current_hash`
+- This endpoint uses the cached GitHub integration to return a hash.
+- It supports device-auth and operator-auth contexts.
+- Useful for agent update checks and diagnostics.
+
+### Debug checklist
+- Token missing: call `/api/github/token` as Admin and confirm `has_token`.
+- API rate limit errors: inspect the response payload for `rate_limit` fields.
+- Cache stale: use the `force_refresh` behavior in `GitHubIntegration` (via config or code).