Align docs with current platform behavior

Update the written guides and generated OpenAPI metadata to match the
current repo layout, env-loading workflow, and API contract.

This also fixes the health/OpenAPI smoke test and documents the
remaining legacy Agora compatibility behavior more precisely.

Author: andreivcodes

AGENTS.md

@@ -1,22 +1,22 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-The workspace is a multi-crate Cargo project. Service code lives under `api/` (Axum REST server with Swagger UI) and `indexers/{indexer-1,indexer-2,indexer-3}/` for ingestion services. Shared libraries (`shared/common`, `shared/db-core`, `shared/entities`) hold reusable logic and schema definitions. Database migrations reside in `migration/`, while service-specific settings inherit from the root `config.toml` alongside `api/config.toml` and `indexers/<name>/config.toml`.
+The workspace is a multi-crate Cargo project. Service code lives under `api/` (Axum REST server with Swagger UI) and `indexers/{discourse-indexer,near-indexer,telegram-indexer}/` for ingestion services. Shared libraries (`shared/common`, `shared/db-core`, `shared/entities`) hold reusable logic and schema definitions. Database migrations reside in `migration/`, while service-specific defaults live in `api/config.toml` and `indexers/<name>/config.toml`.
 
 ## Build, Test, and Development Commands
-Use `cargo check-all` to compile every crate before opening a PR. Run `cargo test-all` for the full workspace test suite; scope to a crate with commands such as `cargo test -p api` or `cargo test -p api handlers::health`. Development binaries include `cargo run-api` (serves at http://127.0.0.1:3000) and `cargo run-indexer-1` (similar for other indexers). Apply schema updates with `cargo migrate-up`, generate new migrations via `cargo migrate-generate <name>`, and rebuild SeaORM entities with `cargo generate-entities`.
+Use `cargo check-all` to compile every crate before opening a PR. Run `cargo test-all` for the full workspace test suite; scope to a crate with commands such as `cargo test -p api` or `cargo test -p api health_`. Development binaries include `cargo run-api` (serves at http://127.0.0.1:3000) and `cargo run-indexer-1` (similar for other indexers). Apply schema updates with `cargo migrate-up`, generate new migrations via `cargo migrate-generate <name>`, and rebuild SeaORM entities with `cargo generate-entities`.
 
 ## Coding Style & Naming Conventions
 Target Rust 2021 idioms with 4-space indentation, `snake_case` for modules/functions, and `CamelCase` types. Libraries favor `thiserror` for typed errors; binaries use `anyhow` for rich context. Always format with `cargo fmt` and consider `cargo clippy -- -D warnings` before pushing.
 
 ## Testing Guidelines
-Tests mirror module layout (e.g., `api/tests/handlers/`). Prefer deterministic handler tests for business logic and route tests for HTTP behavior. Frameworks in use include `rstest`, `axum-test`, and `testcontainers` for PostgreSQL-backed scenarios. Run targeted suites during development, then confirm with `cargo test-all` prior to merge.
+Tests mirror the service surface (for example, `api/tests/{unit,e2e}/`). Prefer deterministic handler tests for business logic and route tests for HTTP behavior. Frameworks in use include `rstest`, `axum-test`, and `testcontainers` for PostgreSQL-backed scenarios. Run targeted suites during development, then confirm with `cargo test-all` prior to merge.
 
 ## Commit & Pull Request Guidelines
 Write concise, imperative commit subjects (≈50 characters) similar to "fix Railway caching" or "observability". Pull requests should summarize the change, link relevant issues, note testing performed, and call out config or migration impacts; include Swagger screenshots when UI behavior changes.
 
 ## Security & Configuration Tips
-Never commit secrets. Copy `.env.example` to `.env` locally and configure runtime with environment variables such as `DATABASE_URL` and `RUST_LOG`. Override Figment settings by exporting keys like `APP_SERVER__HOST` or `APP_LOGGING__LEVEL` for service-specific tuning.
+Never commit secrets. Copy `.env.example` to `.env.local` locally and configure runtime with environment variables such as `DATABASE_URL` and `APP_LOGGING__LEVEL`. If you use the checked-in `.envrc`, install the Doppler CLI because the direnv workflow invokes it before sourcing `.env.local`. Override Figment settings by exporting keys like `APP_SERVER__HOST` or `APP_LOGGING__LEVEL` for service-specific tuning, and use `RUST_LOG` only when you need a fine-grained tracing filter override.
 
 ## Documentation Maintenance
 Keep the files in `docs/` in sync with the codebase. Update them as part of the same PR that introduces the change:

README.md

@@ -26,14 +26,21 @@ hos-api/
 ```bash
 git clone <repository-url> && cd hos-api
 cargo install sea-orm-cli --version 1.1.15 --locked
-cp .env.example .env  # Edit with database settings
-direnv allow
+cp .env.example .env.local  # Used by the checked-in .envrc
+direnv allow                # Requires Doppler CLI; loads env for DB-backed migration/entity commands
 cargo migrate-up && cargo generate-entities
 cargo run-api
 ```
 
 **Access**: API at http://localhost:3000 • [Swagger UI](http://localhost:3000/swagger-ui) • [OpenAPI spec](http://localhost:3000/api-docs/openapi.json)
 
+If you do not use the checked-in `direnv` + Doppler workflow, export
+`DATABASE_URL` manually before running DB-backed commands such as
+`cargo migrate-up`, `cargo migrate-down`, `cargo migrate-status`,
+`cargo migrate-reset`, `cargo migrate-fresh`, `cargo generate-entities`, or
+`cargo backfill-identity-accounts`. `cargo migrate-generate` does not require a
+live database connection.
+
 **Detailed setup**: [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)
 
 ## Database Operations
@@ -68,7 +75,7 @@ This monorepo ships as independently deployable services plus a shared PostgreSQ
 | Component | Role | Public ingress | Main requirements |
 |---|---|---|---|
 | `api` | Axum REST API and Swagger UI | Yes | `DATABASE_URL`, platform `PORT` or `APP_SERVER__PORT` |
-| `web` | Next.js frontend | Yes | `VENEAR_API_BASE_URL` |
+| `web` | Next.js frontend | Yes | `VENEAR_API_BASE_URL` or `NEXT_PUBLIC_VENEAR_API_BASE_URL` |
 | `discourse-indexer` | Discourse ingestion worker | No | `DATABASE_URL` |
 | `near-indexer` | NEAR ingestion worker | No | `DATABASE_URL`, optional FastNEAR credentials |
 | `telegram-indexer` | Telegram ingestion worker | No | `DATABASE_URL`, Telegram credentials, durable session state |
@@ -299,13 +306,13 @@ Notes for this compose stack:
 - `api`: `/api/Dockerfile` and `/api/railway.toml`
 - `web`: `/web/Dockerfile` and `/web/railway.toml`
 - `migration`: `/migration/Dockerfile`
-- `discourse-indexer`: `/indexers/discourse-indexer/Dockerfile` and `/indexers/discourse-indexer/railway.toml`
-- `near-indexer`: `/indexers/near-indexer/Dockerfile` and `/indexers/near-indexer/railway.toml`
-- `telegram-indexer`: `/indexers/telegram-indexer/Dockerfile` and `/indexers/telegram-indexer/railway.toml`
+- `discourse-indexer`: `/indexers/discourse-indexer/Dockerfile`
+- `near-indexer`: `/indexers/near-indexer/Dockerfile`
+- `telegram-indexer`: `/indexers/telegram-indexer/Dockerfile`
 
 This layout works on Railway, Fly.io, Render, Kubernetes, ECS, Nomad, or plain Docker Compose as long as the platform can run one container per service, inject environment variables, provide PostgreSQL connectivity, and expose public HTTP only for `api` and `web`.
 
-Railway is the easiest fit today because this repo already includes one `railway.toml` per service, Dockerfile-based builds, watch patterns, and API support for Railway's injected `PORT` environment variable. If you use Railway, prefer one service per component, run migrations as a separate release step, and use private networking from `web` to `api` with a base URL like `http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}/api/v1/venear`.
+Railway is the easiest fit today because this repo already includes Railway manifests for the long-running services, Dockerfile-based builds for every deployable component, watch patterns, and API support for Railway's injected `PORT` environment variable. If you use Railway, prefer one service per component, run migrations as a separate release step, and use private networking from `web` to `api` with a base URL like `http://${{api.RAILWAY_PRIVATE_DOMAIN}}:${{api.PORT}}/api/v1/venear`.
 
 ## Testing
 
@@ -325,7 +332,7 @@ The platform uses `tracing` with `tracing-subscriber` and emits structured JSON
 **Features**:
 - **Logs**: Structured JSON logs for all services
 - **Traces**: Span-aware request and background-job tracing
-- **Filtering**: Log level control via `RUST_LOG`
+- **Filtering**: Log level control via `APP_LOGGING__LEVEL`
 
 ## Tech Stack
 

api/src/docs.rs

@@ -8,7 +8,7 @@ use utoipa::OpenApi;
     info(
         title = "HOS API",
         version = "0.1.0",
-        description = "Read-only REST API for indexed identity, Discourse, Telegram, and veNEAR governance data.\n\nOpenAPI contract notes for AI clients:\n- The API is read-only. Every endpoint is discoverable through generated OpenAPI metadata.\n- List endpoints are consistently paginated with `limit` and `cursor`.\n- Cursor pagination uses opaque base64url cursors.\n  - `limit` defaults to 20 and is clamped to a maximum of 100.\n  - `cursor` is an opaque base64url token from a prior response and should be treated as an opaque string.\n  - Omit `cursor` to request the first page in a sequence.\n  - Continue until `next_cursor` is `null` or absent.\n- All paginated responses return `data`, `next_cursor`, and `has_more`.\n- `next_cursor` and pagination order are endpoint-specific; always follow the ordering declared in each endpoint description.\n- Timestamp fields use RFC 3339 / ISO-8601 format with timezone.\n- Error responses follow RFC 9457 Problem Details as `application/problem+json`, including machine-friendly `code` when present.\n- Indexers are asynchronous: newly emitted data may lag or reorder briefly during backfill.\n- `identity` values are stable while indexer-sourced entity references may vary by environment and snapshot time.",
+        description = "Read-only REST API for indexed identity, Discourse, Telegram, and veNEAR governance data.\n\nOpenAPI contract notes for AI clients:\n- The API is read-only. Every endpoint is discoverable through generated OpenAPI metadata.\n- `/api/v1` list endpoints use `limit` and `cursor` with opaque base64url cursors.\n  - `limit` defaults to 20 and is clamped to a maximum of 100.\n  - `cursor` is an opaque base64url token from a prior response and should be treated as an opaque string.\n  - Omit `cursor` to request the first page in a sequence.\n  - Continue until `next_cursor` is `null` or absent.\n- Paginated `/api/v1` responses return `data`, `next_cursor`, and `has_more`.\n- Legacy `/api/agora` endpoints intentionally preserve page-based params and older payload shapes for compatibility.\n- `next_cursor` and pagination order are endpoint-specific; always follow the ordering declared in each endpoint description.\n- Timestamp fields use RFC 3339 / ISO-8601 format with timezone.\n- Error responses follow RFC 9457 Problem Details as `application/problem+json`, including machine-friendly `code` when present.\n- Indexers are asynchronous: newly emitted data may lag or reorder briefly during backfill.\n- `identity` values are stable while indexer-sourced entity references may vary by environment and snapshot time.",
         contact(
             name = "HOS API Team",
             url = "https://github.com/HackHumanityOrg/hos-api"

api/src/handlers/health/health_check.rs

@@ -15,8 +15,7 @@ use tracing::{info, instrument};
     description = "Performs service liveness checks and an optional database probe (`SELECT 1`). Returns `healthy` when the database probe succeeds and `degraded` when the database is unavailable or fails.",
     tag = "health",
     responses(
-        (status = 200, description = "Current API health report", body = HealthResponse),
-        (status = 500, description = "Health check failed", body = crate::errors::ApiError)
+        (status = 200, description = "Current API health report", body = HealthResponse)
     )
 )]
 #[instrument(skip(app_state))]

api/src/handlers/venear/mod.rs

@@ -1,4 +1,5 @@
 //! Canonical-query veNEAR governance handlers.
+#![allow(clippy::result_large_err)]
 
 pub mod accounts;
 pub mod activity;

api/src/handlers/venear/sql.rs

@@ -16,6 +16,7 @@ pub(crate) struct ParsedEventLog {
     pub log_index: i64,
 }
 
+#[allow(dead_code)]
 #[derive(Debug, Clone)]
 pub(crate) struct CanonicalAction {
     pub id: String,
@@ -127,6 +128,7 @@ pub(crate) fn decode_row_col<T: sea_orm::TryGetable>(
     })
 }
 
+#[allow(dead_code)]
 pub(crate) async fn scalar_i64_with_values(
     db: &DatabaseConnection,
     sql: &str,

api/tests/e2e/openapi.rs

@@ -15,8 +15,10 @@ fn openapi_spec_exposes_health_path_and_schemas() {
         .and_then(|v| v.as_str())
         .expect("api description present");
     assert!(
-        description.contains("Cursor pagination uses opaque base64url cursors"),
-        "api description should document pagination conventions"
+        description.contains("/api/v1` list endpoints use `limit` and `cursor`")
+            && description
+                .contains("Legacy `/api/agora` endpoints intentionally preserve page-based params"),
+        "api description should document both canonical and Agora pagination conventions"
     );
 
     let paths = value