Phase 8: align docs and public surface

OVERVIEW.md

@@ -0,0 +1,104 @@
+# Guard Rail Overview
+
+## Repository Split
+
+This repository contains two distinct surfaces:
+
+- `guard-rail-engine/` is the runtime. It is the container-first Rust service that enforces route and policy rules, persists audit and replay data, and exposes the operational endpoints used in the pilot deployment.
+- `app/` is the marketing site. It presents the product story, but it is not part of the control plane and does not participate in request enforcement.
+
+That split matters operationally: the landing page can change independently of the runtime, while the runtime remains the source of truth for request handling, policy enforcement, and execution records.
+
+## Current Product Shape
+
+Guard Rail is a policy enforcement runtime for internal API traffic. The current implementation is centered on a pilot deployment that evaluates a request before forwarding it to an upstream API.
+
+The runtime currently exposes these surfaces:
+- route execution for `POST /v1/execute/{route_id}`-style traffic
+- route and method validation before forwarding
+- authentication and authorization checks around runtime access
+- audit logging and audit persistence for every execution
+- replay capture and replay persistence for later investigation
+- readiness and metrics endpoints for health and operations
+- admin and maintenance commands for the pilot deployment path
+
+The important boundary is that Guard Rail governs the request path, not the upstream application itself.
+
+## Deployment Model
+
+The blessed deployment path is container-first:
+
+`container image + external Postgres + reverse proxy/LB`
+
+That model reflects the current runtime shape:
+- the image is the deployable unit
+- Postgres lives outside the container and stores durable state
+- a reverse proxy or load balancer fronts the runtime
+- config is mounted in from disk
+- secrets are injected through the environment
+
+This is the deployment path the docs and verification package are aligned to. Other packaging choices may exist in the repo, but they are not the recommended pilot path.
+
+## Request Flow
+
+At a high level, the runtime does the following on each request:
+
+1. Resolve the target route.
+2. Check the request method and basic request shape.
+3. Authenticate the caller and apply route-level access controls.
+4. Evaluate configured policies against the request payload and metadata.
+5. Record the execution in audit and replay surfaces.
+6. Forward the request upstream only if the checks pass.
+
+The exact policies are data-driven, so most behavior is controlled through repo-managed configuration rather than code changes.
+
+## Runtime Surfaces
+
+### Routing
+
+Routes define which upstream a client can reach, which HTTP methods are allowed, and which policies apply. The runtime resolves the route first so it can reject invalid or unauthorized traffic before any upstream call is made.
+
+### Authentication and Authorization
+
+The runtime has explicit request-access surfaces rather than assuming open access. That keeps the request path tied to runtime-issued or runtime-validated credentials instead of treating the engine as a public passthrough.
+
+### Audit
+
+Every execution is recorded so operators can reconstruct what happened, why a request was allowed or blocked, and which route or policy was involved.
+
+### Replay
+
+Replay artifacts capture the request context needed for later analysis and verification. In the current pilot posture, replay is an operational record, not a productized end-user workflow.
+
+### Runtime Health
+
+Readiness and metrics are part of the current operational contract. They exist so the runtime can be deployed behind a proxy/LB and observed like a production service, even though the product itself is still in pilot posture.
+
+## Data and Operations
+
+The operator-facing docs are split by concern:
+
+- `guard-rail-engine/deploy/container/DATA_OPERATIONS.md` covers cleanup, backup, restore, and rollback.
+- `guard-rail-engine/deploy/observability/` covers metrics, alerts, dashboards, and runbooks.
+- `guard-rail-engine/deploy/verification/README.md` covers the pilot verification suite and its expected scenarios.
+
+Those documents are the authoritative operational references for the current runtime posture.
+
+## Verification-Backed Position
+
+This repo should be described as a verified pilot runtime, not as a roadmap-era platform promise.
+
+That means the docs should stay aligned with what is actually covered by the current deployment and verification package:
+- containerized runtime deployment
+- external Postgres
+- request enforcement before forwarding
+- audit and replay persistence
+- readiness, metrics, and operational runbooks
+
+It does not mean claiming broader platform features, multi-tenant control-plane behavior, or unspecified enterprise guarantees that are not backed by the current code and verification assets.
+
+## Non-Goals In This Overview
+
+This file is intentionally not a full API reference or implementation spec. It does not enumerate every config key or every endpoint, and it should not promise features that belong in future work.
+
+For the concrete operator procedures and verification steps, use the deployment docs linked above.

README.md

@@ -1,95 +1,44 @@
 # Guard Rail
 
-`guard-rail-engine` is the Rust runtime in this repo. Stage 5 adds production-hardening support for readiness, metrics, trace-context-aware request logging, graceful drain on shutdown, and baseline deployment artifacts.
+Guard Rail is a policy enforcement runtime for internal API traffic. It sits between trusted clients and upstream APIs, evaluates requests against route and policy definitions, and either forwards the request or blocks it with an auditable verdict.
 
-## Guard Rail Engine Operations
+The repo has two user-facing parts:
+- `guard-rail-engine/` for the Rust runtime
+- `app/` for the marketing site, which is separate from the control plane
 
-### Canonical Pilot Deployment
+## Blessed deployment path
 
-The only supported pilot deployment path is:
+The supported pilot deployment is:
 
 `container image + external Postgres + reverse proxy/LB`
 
-The container expects:
-- a mounted config directory at `/etc/guard-rail-engine`
-- env overrides for secrets such as `GUARDRAIL_DATABASE__URL` and `GUARDRAIL_ADMIN__TOKEN`
-- migrations to be run separately from the normal service start path
+That path assumes:
+- the runtime is run from the built container image
+- Postgres is managed outside the container
+- a reverse proxy or load balancer fronts the runtime
+- runtime config is mounted from disk and secrets are injected through the environment
 
-Build the container image:
+The runtime is not positioned as a standalone VM install, a Docker Compose production target, or a Kubernetes-first control plane.
 
-```bash
-cd guard-rail-engine
-docker build -t guard-rail-engine .
-```
+## What the runtime does
 
-Run migrations:
+The engine currently covers the pilot-grade request flow:
+- route lookup and method checks
+- request authentication and authorization surfaces
+- policy evaluation before forwarding
+- audit persistence for executed requests
+- replay capture and related runtime artifacts
+- readiness and metrics surfaces for operations
 
-```bash
-docker run --rm \
-  -v "$(pwd)/deploy/container:/etc/guard-rail-engine:ro" \
-  --env-file ./deploy/container/guard-rail-engine.env.example \
-  guard-rail-engine \
-  migrate --config /etc/guard-rail-engine/config.yaml
-```
+## Operational docs
 
-Start the runtime:
+Use these repo-native docs for the supported operator workflows:
+- Data operations: `guard-rail-engine/deploy/container/DATA_OPERATIONS.md`
+- Observability: `guard-rail-engine/deploy/observability/`
+- Verification: `guard-rail-engine/deploy/verification/README.md`
 
-```bash
-docker run --rm \
-  -p 8080:8080 \
-  -v "$(pwd)/deploy/container:/etc/guard-rail-engine:ro" \
-  --env-file ./deploy/container/guard-rail-engine.env.example \
-  guard-rail-engine
-```
+## Current scope
 
-`systemd` remains in the repo only as a deferred fallback example. It is not a supported Phase 5 production path.
+Guard Rail is focused on the runtime and its pilot deployment story. It is intentionally not framed here as a full SaaS platform, management console, or multi-environment control plane.
 
-## Data Operations
-
-Retention cleanup is an explicit operator command, not part of normal startup:
-
-```bash
-cd guard-rail-engine
-GUARDRAIL_DATABASE__URL="$TEST_DATABASE_URL" \
-GUARDRAIL_ADMIN__TOKEN=phase3-admin-token \
-cargo run -- cleanup --config ./deploy/container/config.yaml
-```
-
-See `guard-rail-engine/deploy/container/DATA_OPERATIONS.md` for cleanup, backup, restore, and rollback guidance.
-
-## Local DB-Backed Testing
-
-DB-backed backend tests require `TEST_DATABASE_URL` locally. CI provisions Postgres automatically for these commands:
-
-```bash
-cd guard-rail-engine
-export TEST_DATABASE_URL=postgres://guardrail:secret@127.0.0.1:5432/guardrail
-
-cargo test --test audit_api_test
-cargo test --test auth_integration_test
-cargo test --test replay_integration_test
-```
-
-The CI runtime-smoke lane runs the shipped entrypoints through the helper script:
-
-```bash
-cd guard-rail-engine
-export GUARDRAIL_DATABASE__URL="$TEST_DATABASE_URL"
-export GUARDRAIL_ADMIN__TOKEN=ci-admin-token
-export GUARDRAIL_ENVIRONMENT=development
-export GUARDRAIL_SERVER__HOST=127.0.0.1
-export GUARDRAIL_SERVER__PORT=18080
-
-./scripts/ci/runtime-smoke.sh
-```
-
-## Observability
-
-The runtime exposes Prometheus metrics at `/metrics`. See `guard-rail-engine/deploy/observability/` for:
-- Alert rules (`prometheus-alerts.yml`)
-- Grafana dashboard (`grafana-dashboard.json`)
-- Operator runbooks (`RUNBOOKS.md`)
-
-## Verification
-
-See `guard-rail-engine/deploy/verification/README.md` for the Phase 7 verification package covering load, resilience, and security verification.
+If you need the deeper runtime layout, request/response surfaces, or repo structure, start with `OVERVIEW.md`.