docs: clarify capabilities and contracts

README.md

@@ -1,8 +1,10 @@
 # Sentinel
 
-Open-source multilingual moderation API built to protect Kenya's 2027 general election from ethnic incitement and election disinformation.
+Open-source election-safety moderation API built to help protect Kenya's 2027 general election from ethnic incitement and election disinformation.
 
-Sentinel handles code-switched text across English, Swahili, and Sheng. It returns deterministic moderation decisions (`ALLOW`, `REVIEW`, or `BLOCK`) with full audit evidence, so every action can be explained and appealed.
+Sentinel currently supports code-switched moderation across English (`en`), Swahili (`sw`), and Sheng (`sh`) in the live moderation hot path. Language-pack artifacts for additional languages (including Luo and Kalenjin) are included for operator evaluation and staged rollout, but are not active in default hot-path enforcement.
+
+Sentinel returns deterministic moderation decisions (`ALLOW`, `REVIEW`, or `BLOCK`) with full audit evidence, so every action can be explained and appealed.
 
 ## Who is this for?
 
@@ -12,6 +14,12 @@ Sentinel handles code-switched text across English, Swahili, and Sheng. It retur
 
 Both audiences should begin with the [Quickstart](docs/quickstart.md).
 
+## Capability Snapshot
+
+- **Available now (default runtime)**: moderation routing and enforcement for `en`, `sw`, `sh`
+- **Included but not default-active**: additional language-pack artifacts (e.g., Luo, Kalenjin)
+- **Contract stability**: `POST /v1/moderate` is the stable integration surface; admin/internal interfaces are operator-oriented and can evolve
+
 ## What Sentinel returns
 
 ```jsonc

contracts/schemas/internal/appeal-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/appeal-request.schema.json",
+  "$id": "urn:sentinel:schema:internal:appeal-request",
   "title": "AppealRequest",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/appeal-resolution.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/appeal-resolution.schema.json",
+  "$id": "urn:sentinel:schema:internal:appeal-resolution",
   "title": "AppealResolution",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/appeal-state-transition.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/appeal-state-transition.schema.json",
+  "$id": "urn:sentinel:schema:internal:appeal-state-transition",
   "title": "AppealStateTransition",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/monitoring-cluster.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/monitoring-cluster.schema.json",
+  "$id": "urn:sentinel:schema:internal:monitoring-cluster",
   "title": "MonitoringCluster",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/monitoring-queue-item.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/monitoring-queue-item.schema.json",
+  "$id": "urn:sentinel:schema:internal:monitoring-queue-item",
   "title": "MonitoringQueueItem",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/partner-connector-ingest-report.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/partner-connector-ingest-report.schema.json",
+  "$id": "urn:sentinel:schema:internal:partner-connector-ingest-report",
   "title": "PartnerConnectorIngestReport",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/partner-connector-signal.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/partner-connector-signal.schema.json",
+  "$id": "urn:sentinel:schema:internal:partner-connector-signal",
   "title": "PartnerConnectorSignal",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/proposal-review-event.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/proposal-review-event.schema.json",
+  "$id": "urn:sentinel:schema:internal:proposal-review-event",
   "title": "ProposalReviewEvent",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/release-proposal.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/release-proposal.schema.json",
+  "$id": "urn:sentinel:schema:internal:release-proposal",
   "title": "ReleaseProposal",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/transparency-appeals-report.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/transparency-appeals-report.schema.json",
+  "$id": "urn:sentinel:schema:internal:transparency-appeals-report",
   "title": "TransparencyAppealsReport",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/internal/transparency-export-record.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/internal/transparency-export-record.schema.json",
+  "$id": "urn:sentinel:schema:internal:transparency-export-record",
   "title": "TransparencyExportRecord",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/metrics-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/metrics-response.schema.json",
+  "$id": "urn:sentinel:schema:metrics-response",
   "title": "MetricsResponse",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/moderation-request.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/moderation-request.schema.json",
+  "$id": "urn:sentinel:schema:moderation-request",
   "title": "ModerationRequest",
   "type": "object",
   "additionalProperties": false,

contracts/schemas/moderation-response.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://sentinel.dev/schemas/moderation-response.schema.json",
+  "$id": "urn:sentinel:schema:moderation-response",
   "title": "ModerationResponse",
   "type": "object",
   "additionalProperties": false,

docs/README.md

@@ -1,6 +1,12 @@
 # Sentinel Documentation
 
-Sentinel is an open-source multilingual moderation API for election safety. These docs cover integration, deployment, and operation.
+Sentinel is an open-source moderation API for election safety, currently supporting English (`en`), Swahili (`sw`), and Sheng (`sh`). These docs cover integration, deployment, and operation.
+
+## Interface stability levels
+
+- **Public integration contract (stable)**: `/v1/moderate` plus `contracts/api/openapi.yaml` and top-level request/response schemas.
+- **Operator/admin interfaces (managed, may evolve)**: `/admin/*` and `/internal/*` endpoints used for operations and governance workflows.
+- **Internal schemas (implementation contracts)**: `contracts/schemas/internal/*` support tests and operational pipelines; they are not a promise of long-term external API stability.
 
 ## Reading paths
 
@@ -37,7 +43,7 @@ You want to deploy and manage a Sentinel instance.
 | Path | Contents |
 |------|----------|
 | `contracts/api/openapi.yaml` | Machine-readable contract for `/health`, `/metrics`, and `/v1/moderate` |
-| `contracts/schemas/` | JSON Schema definitions for request/response models |
+| `contracts/schemas/` | JSON Schema definitions (public + internal operator schemas) |
 | `templates/go-live/` | Go-live readiness gate template bundle |
 | `config/policy/default.json` | Default policy configuration (thresholds, phases, hints) |
 | `data/lexicon_seed.json` | 7-term demonstration seed lexicon |

docs/deployment.md

@@ -20,6 +20,8 @@ Sentinel has three runtime components:
 - **PostgreSQL with pgvector** — Stores lexicon entries, releases, embeddings, appeals, transparency data, model artifacts. Required for production.
 - **Redis** — Distributed rate limiting and hot-trigger caching. Optional; Sentinel degrades gracefully if unavailable.
 
+Default moderation routing is active for `en`, `sw`, and `sh`. Additional language-pack artifacts may exist in the repository for staged rollout but are not automatically active in hot-path enforcement.
+
 Without Postgres, Sentinel runs in file-based fallback mode (lexicon loaded from `data/lexicon_seed.json`, appeals stored in-memory). This is suitable for development but not production.
 
 ## Environment variables

docs/faq.md

@@ -4,7 +4,7 @@
 
 ### What is Sentinel?
 
-Sentinel is an open-source multilingual moderation API built to protect Kenya's 2027 general election from ethnic incitement and election disinformation. It handles code-switched text across English, Swahili, and Sheng, and returns deterministic moderation decisions (`ALLOW`, `REVIEW`, `BLOCK`) with full audit evidence.
+Sentinel is an open-source election-safety moderation API built to help protect Kenya's 2027 general election from ethnic incitement and election disinformation. It currently supports code-switched moderation across English (`en`), Swahili (`sw`), and Sheng (`sh`), and returns deterministic moderation decisions (`ALLOW`, `REVIEW`, `BLOCK`) with full audit evidence.
 
 ### Is Sentinel production-ready?
 
@@ -25,7 +25,9 @@ Sentinel currently supports three language codes in the moderation pipeline:
 - **Swahili (sw)** — baseline deterministic support with hint-word detection
 - **Sheng (sh)** — baseline deterministic support with hint-word detection
 
-Language routing is token-informed and returns span-level `language_spans`, so code-switched text (e.g., English + Sheng in one sentence) is handled natively. Additional languages can be added via the language pack system.
+Language routing is token-informed and returns span-level `language_spans`, so code-switched text (e.g., English + Sheng in one sentence) is handled natively.
+
+Sentinel also includes language-pack artifacts for additional languages (currently Luo and Kalenjin), but these are for staged/operator rollout and are not active in the default moderation hot path.
 
 ### What are the six labels?
 

docs/integration-guide.md

@@ -4,6 +4,8 @@ This guide is for platform integrators calling the Sentinel API from a backend a
 
 Sentinel is a server-side API. Never call it directly from a browser or mobile client — always proxy through your backend.
 
+Default runtime language support for the moderation hot path is English (`en`), Swahili (`sw`), and Sheng (`sh`).
+
 ## Authentication
 
 All moderation requests require an API key passed in the `X-API-Key` header:

docs/quickstart.md

@@ -5,6 +5,8 @@ Choose your path:
 - **Path A** — You're an integrator calling an existing Sentinel instance
 - **Path B** — You're an operator setting up Sentinel from scratch
 
+Current default runtime language support is English (`en`), Swahili (`sw`), and Sheng (`sh`).
+
 ## Path A: Integrator
 
 You have access to a running Sentinel instance and an API key. Four steps to your first moderation call.