fusionAIze · typelicious · Mar 15, 2026 · Mar 15, 2026 · Mar 15, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,7 +4,7 @@ All notable changes to FoundryGate should be documented here.
 
 The format is intentionally lightweight and human-readable. Group entries by release and focus on user-visible behavior, operational changes, and compatibility notes.
 
-## Unreleased
+## v1.0.0 - 2026-03-15
 
 ### Added
 
@@ -14,6 +14,7 @@ The format is intentionally lightweight and human-readable. Group entries by rel
 - Added a separate npm CLI package under `packages/foundrygate-cli` for basic health, model, update, and route-preview checks
 - Added a documented `v1.0.0` security review with mitigations and residual-risk notes
 - Added functional API coverage for upstream error sanitization on top of the earlier dashboard and request-boundary hardening tests
+- Streamlined the root README into a shorter landing page and moved deeper API, configuration, and operations detail into dedicated docs pages
 
 ## v0.9.0 - 2026-03-15
 

diff --git a/README.md b/README.md
diff --git a/RELEASES.md b/RELEASES.md
@@ -22,11 +22,11 @@ This repo does not require a heavy release process. Use lightweight tags plus Gi
 ```bash
 git checkout main
 git pull --ff-only origin main
-git tag -a v0.9.0 -m "FoundryGate v0.9.0"
-git push origin v0.9.0
+git tag -a v1.0.0 -m "FoundryGate v1.0.0"
+git push origin v1.0.0
 ```
 
-Then open GitHub Releases and publish a release for `v0.9.0`.
+Then open GitHub Releases and publish a release for `v1.0.0`.
 
 ## Automation Baseline
 
@@ -59,6 +59,7 @@ The repo also includes [publish-dry-run](./.github/workflows/publish-dry-run.yml
 - `v0.7.0` establishes the operations-polish baseline: update alerts, operator events, rollout guardrails, scoped update checks, maintenance windows, and post-update verification hints.
 - `v0.8.0` establishes the onboarding baseline: repeatable provider/client rollout helpers, starter templates, delegated-traffic examples, env validation, and shareable onboarding reports.
 - `v0.9.0` is the pre-`v1.0` hardening baseline: conservative response headers, bounded request surfaces, stronger functional API coverage, and a full documentation pass over operator-facing behavior.
+- `v1.0.0` establishes the stable baseline: trust-boundary validation for upstream base URLs, sanitized provider-error responses, a documented security review, and the separate `@foundrygate/cli` npm package for CLI-facing workflows.
 
 ## Planned Publishing Path
 

diff --git a/docs/API.md b/docs/API.md
@@ -0,0 +1,178 @@
+# FoundryGate API Reference
+
+FoundryGate keeps the client-facing surface intentionally small: OpenAI-compatible paths for chat and image workloads, plus a compact operator API for health, routing introspection, and updates.
+
+## Core OpenAI-Compatible Endpoints
+
+### `GET /v1/models`
+
+Returns the virtual `auto` model plus one entry for every provider that actually loaded at startup.
+
+```bash
+curl -fsS http://127.0.0.1:8090/v1/models
+```
+
+### `POST /v1/chat/completions`
+
+Routes OpenAI-style chat requests.
+
+- `model: "auto"` runs the normal routing flow
+- `model: "<provider-id>"` routes directly to a loaded provider
+- request size is bounded by `security.max_json_body_bytes`
+
+```bash
+curl -fsS http://127.0.0.1:8090/v1/chat/completions \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "auto",
+    "messages": [
+      {"role": "user", "content": "Summarize the benefits of a local AI gateway."}
+    ],
+    "max_tokens": 128
+  }'
+```
+
+### `POST /v1/images/generations`
+
+Routes image-generation requests to providers with `capabilities.image_generation: true`.
+
+- validates `prompt`, `n`, and `size` before any provider call
+- supports image-policy hints via `metadata.image_policy` or `X-FoundryGate-Image-Policy`
+
+```bash
+curl -fsS http://127.0.0.1:8090/v1/images/generations \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "auto",
+    "prompt": "An architectural diagram of a local AI gateway, blueprint style",
+    "size": "1024x1024"
+  }'
+```
+
+### `POST /v1/images/edits`
+
+Routes image-editing requests to providers with `capabilities.image_editing: true`.
+
+- expects `multipart/form-data`
+- currently supports one required `image` and one optional `mask`
+- rejects uploads above `security.max_upload_bytes`
+- accepts image-policy hints via `image_policy`, `metadata.image_policy`, or `X-FoundryGate-Image-Policy`
+
+```bash
+curl -fsS http://127.0.0.1:8090/v1/images/edits \
+  -F 'model=auto' \
+  -F 'prompt=Remove the background and keep the subject centered' \
+  -F 'image=@input.png' \
+  -F 'mask=@mask.png'
+```
+
+## Operator Endpoints
+
+### `GET /health`
+
+Returns overall service status, provider summary, and capability coverage.
+
+Each provider entry includes health, failure counters, average latency, last error, contract, backend, tier, capabilities, and image metadata.
+
+```bash
+curl -fsS http://127.0.0.1:8090/health
+```
+
+### `GET /api/providers`
+
+Returns the loaded provider inventory plus the same capability-coverage summary used by the dashboard.
+
+- optional `capability=<name>`
+- optional `healthy=true|false`
+
+```bash
+curl -fsS 'http://127.0.0.1:8090/api/providers?capability=image_generation'
+```
+
+### `GET /api/stats`
+
+Returns aggregate request counters, cost data, and operator-action summaries.
+
+```bash
+curl -fsS http://127.0.0.1:8090/api/stats
+```
+
+### `GET /api/recent`
+
+Returns recent request records with optional filters for provider, client tag, layer, and success state.
+
+```bash
+curl -fsS 'http://127.0.0.1:8090/api/recent?limit=20'
+```
+
+### `GET /api/traces`
+
+Returns detailed route traces including requested model, decision reason, attempt order, client profile, and selected provider.
+
+```bash
+curl -fsS 'http://127.0.0.1:8090/api/traces?limit=20'
+```
+
+### `GET /api/update`
+
+Returns current release information plus update guardrails such as alert level, rollout ring, release age eligibility, maintenance-window state, and verification hints.
+
+```bash
+curl -fsS http://127.0.0.1:8090/api/update
+```
+
+### `GET /api/operator-events`
+
+Returns helper-driven operator actions such as update checks and auto-update attempts.
+
+```bash
+curl -fsS 'http://127.0.0.1:8090/api/operator-events?limit=20'
+```
+
+### `POST /api/route`
+
+Dry-runs chat routing and returns the selected provider, routing layer, decision reason, profile resolution, and attempt order.
+
+```bash
+curl -fsS http://127.0.0.1:8090/api/route \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "model": "auto",
+    "messages": [
+      {"role": "user", "content": "Plan a low-latency response path for a CLI agent."}
+    ]
+  }'
+```
+
+### `POST /api/route/image`
+
+Dry-runs image-generation or image-editing routing without calling an upstream provider.
+
+```bash
+curl -fsS http://127.0.0.1:8090/api/route/image \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "operation": "generation",
+    "model": "auto",
+    "prompt": "A clean dashboard screenshot mockup",
+    "size": "1024x1024"
+  }'
+```
+
+### `GET /dashboard`
+
+Serves the built-in no-build operator dashboard.
+
+```bash
+open http://127.0.0.1:8090/dashboard
+```
+
+## Response Headers
+
+Non-streaming chat completions include:
+
+- `X-FoundryGate-Provider`
+- `X-FoundryGate-Layer`
+- `X-FoundryGate-Rule`
+
+These are intentionally bounded and sanitized before they leave the gateway.
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -0,0 +1,160 @@
+# FoundryGate Configuration
+
+FoundryGate is configured through `config.yaml` plus environment variables loaded from `.env`.
+
+## Start Here
+
+- Main runtime config: [`config.yaml`](../config.yaml)
+- Environment template: [`../.env.example`](../.env.example)
+- Provider starter snippets: [`./examples`](./examples)
+
+## Core Environment Variables
+
+### `FOUNDRYGATE_DB_PATH`
+
+Use this for the SQLite metrics database. The default service path is:
+
+```text
+/var/lib/foundrygate/foundrygate.db
+```
+
+For local non-root runs, point it somewhere writable outside the repo checkout:
+
+```bash
+export FOUNDRYGATE_DB_PATH="$HOME/.local/state/foundrygate/foundrygate.db"
+```
+
+### Stock Provider API Keys
+
+The stock config references these variables directly:
+
+- `DEEPSEEK_API_KEY`
+- `GEMINI_API_KEY`
+- `OPENROUTER_API_KEY`
+- `OPENAI_API_KEY`
+
+Optional base URL overrides in `.env.example`:
+
+- `DEEPSEEK_BASE_URL`
+- `GEMINI_BASE_URL`
+- `OPENROUTER_BASE_URL`
+- `OPENAI_BASE_URL`
+
+Additional optional provider entries in `config.yaml` reference further env vars when you uncomment them.
+
+## Security Settings
+
+`config.yaml` exposes explicit security controls for the request surface:
+
+- `security.response_headers`
+- `security.cache_control`
+- `security.max_json_body_bytes`
+- `security.max_upload_bytes`
+- `security.max_header_value_chars`
+
+These settings drive the bounded JSON, upload, and routing-header behavior that ships in `v0.9.0+`.
+
+## Provider Fields
+
+Each provider entry can include:
+
+- `contract`
+- `backend`
+- `base_url`
+- `api_key`
+- `model`
+- `max_tokens`
+- `context_window`
+- `tier`
+- `limits`
+- `cache`
+- `capabilities`
+- `timeout`
+- `pricing`
+- `image`
+
+The comments in [`config.yaml`](../config.yaml) are the source of truth for the current schema.
+
+## Provider Contracts
+
+### `generic`
+
+Default contract for normal chat-capable providers.
+
+### `local-worker`
+
+Use this for network-local OpenAI-compatible workers.
+
+Runtime rules:
+
+- backend must be `openai-compat`
+- `base_url` must point to localhost or private network space
+- `tier` defaults to `local`
+- capabilities are normalized to `local=true`, `cloud=false`, `network_zone=local`
+
+### `image-provider`
+
+Use this for providers that can serve `POST /v1/images/generations` and optionally `POST /v1/images/edits`.
+
+Useful `image` metadata:
+
+- `max_outputs`
+- `max_side_px`
+- `supported_sizes`
+- `policy_tags`
+
+## Client Profiles And Request Hooks
+
+FoundryGate supports two lightweight extension seams:
+
+- `client_profiles`
+  - caller-aware defaults for OpenClaw, n8n, CLI tools, and custom apps
+  - only apply when policy/static/heuristic routing did not already make a stronger decision
+- `request_hooks`
+  - bounded pre-routing hint injection
+  - can fail closed depending on `request_hooks.on_error`
+
+Use the onboarding docs and starter examples when introducing a new client instead of hand-authoring these sections from scratch.
+
+## Update And Rollout Settings
+
+Operational update behavior is also configured in `config.yaml`.
+
+Important blocks:
+
+- `update_check`
+  - release channel
+  - refresh interval
+- `auto_update`
+  - enable/disable
+  - rollout ring
+  - release age guard
+  - maintenance window
+  - provider scope
+  - post-update verification
+
+See [Operations](./OPERATIONS.md) for the helper and schedule side of the same feature set.
+
+## Examples
+
+The repo ships ready-to-copy examples under [`docs/examples`](./examples):
+
+- OpenClaw client config
+- n8n HTTP Request node example
+- CLI environment starter
+- cloud provider starter YAML
+- local-worker starter YAML
+- image-provider starter YAML
+- matching provider `.env` examples
+
+## Validation Helpers
+
+Use these before rolling out a new provider or client:
+
+```bash
+./scripts/foundrygate-doctor
+./scripts/foundrygate-onboarding-report
+./scripts/foundrygate-onboarding-validate
+```
+
+These helpers catch missing env placeholders, rollout blockers, provider capability gaps, and profile issues before live traffic hits the gateway.