From f4cb0133da0c59d036ac8cbb8bb178cd4847b867 Mon Sep 17 00:00:00 2001
From: thelastpoet <emcie4@gmail.com>
Date: Fri, 13 Feb 2026 21:40:36 +0300
Subject: [PATCH] docs: clarify capabilities and contracts

---
 README.md                                            | 12 ++++++++++--
 .../schemas/internal/appeal-request.schema.json      |  2 +-
 .../schemas/internal/appeal-resolution.schema.json   |  2 +-
 .../internal/appeal-state-transition.schema.json     |  2 +-
 .../schemas/internal/monitoring-cluster.schema.json  |  2 +-
 .../internal/monitoring-queue-item.schema.json       |  2 +-
 .../partner-connector-ingest-report.schema.json      |  2 +-
 .../internal/partner-connector-signal.schema.json    |  2 +-
 .../internal/proposal-review-event.schema.json       |  2 +-
 .../schemas/internal/release-proposal.schema.json    |  2 +-
 .../internal/transparency-appeals-report.schema.json |  2 +-
 .../internal/transparency-export-record.schema.json  |  2 +-
 contracts/schemas/metrics-response.schema.json       |  2 +-
 contracts/schemas/moderation-request.schema.json     |  2 +-
 contracts/schemas/moderation-response.schema.json    |  2 +-
 docs/README.md                                       | 10 ++++++++--
 docs/deployment.md                                   |  2 ++
 docs/faq.md                                          |  6 ++++--
 docs/integration-guide.md                            |  2 ++
 docs/quickstart.md                                   |  2 ++
 20 files changed, 42 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index cc77599..9a13161 100644
--- a/README.md
+++ b/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
diff --git a/contracts/schemas/internal/appeal-request.schema.json b/contracts/schemas/internal/appeal-request.schema.json
index 1f6a797..34b1e53 100644
--- a/contracts/schemas/internal/appeal-request.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/appeal-resolution.schema.json b/contracts/schemas/internal/appeal-resolution.schema.json
index 5f29a87..db98bf5 100644
--- a/contracts/schemas/internal/appeal-resolution.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/appeal-state-transition.schema.json b/contracts/schemas/internal/appeal-state-transition.schema.json
index 62d80f3..da2ee2c 100644
--- a/contracts/schemas/internal/appeal-state-transition.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/monitoring-cluster.schema.json b/contracts/schemas/internal/monitoring-cluster.schema.json
index f4e3514..ce0c9a8 100644
--- a/contracts/schemas/internal/monitoring-cluster.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/monitoring-queue-item.schema.json b/contracts/schemas/internal/monitoring-queue-item.schema.json
index 18a08d5..24d10f8 100644
--- a/contracts/schemas/internal/monitoring-queue-item.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/partner-connector-ingest-report.schema.json b/contracts/schemas/internal/partner-connector-ingest-report.schema.json
index 0f10f2a..732ec9b 100644
--- a/contracts/schemas/internal/partner-connector-ingest-report.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/partner-connector-signal.schema.json b/contracts/schemas/internal/partner-connector-signal.schema.json
index b75b76d..471a2e6 100644
--- a/contracts/schemas/internal/partner-connector-signal.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/proposal-review-event.schema.json b/contracts/schemas/internal/proposal-review-event.schema.json
index 6f0e059..23383a6 100644
--- a/contracts/schemas/internal/proposal-review-event.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/release-proposal.schema.json b/contracts/schemas/internal/release-proposal.schema.json
index 1bd1917..838c7d3 100644
--- a/contracts/schemas/internal/release-proposal.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/transparency-appeals-report.schema.json b/contracts/schemas/internal/transparency-appeals-report.schema.json
index a9775fb..6367614 100644
--- a/contracts/schemas/internal/transparency-appeals-report.schema.json
+++ b/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,
diff --git a/contracts/schemas/internal/transparency-export-record.schema.json b/contracts/schemas/internal/transparency-export-record.schema.json
index 3ad0474..f3fb83b 100644
--- a/contracts/schemas/internal/transparency-export-record.schema.json
+++ b/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,
diff --git a/contracts/schemas/metrics-response.schema.json b/contracts/schemas/metrics-response.schema.json
index b289a79..6e0f90c 100644
--- a/contracts/schemas/metrics-response.schema.json
+++ b/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,
diff --git a/contracts/schemas/moderation-request.schema.json b/contracts/schemas/moderation-request.schema.json
index 96e8baf..fad4272 100644
--- a/contracts/schemas/moderation-request.schema.json
+++ b/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,
diff --git a/contracts/schemas/moderation-response.schema.json b/contracts/schemas/moderation-response.schema.json
index 77a85d6..e481a63 100644
--- a/contracts/schemas/moderation-response.schema.json
+++ b/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,
diff --git a/docs/README.md b/docs/README.md
index 0206273..f9ec403 100644
--- a/docs/README.md
+++ b/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 |
diff --git a/docs/deployment.md b/docs/deployment.md
index 9c40e79..20e9372 100644
--- a/docs/deployment.md
+++ b/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
diff --git a/docs/faq.md b/docs/faq.md
index 01d39a6..00e19f2 100644
--- a/docs/faq.md
+++ b/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?
 
diff --git a/docs/integration-guide.md b/docs/integration-guide.md
index 7d3044e..51d3cea 100644
--- a/docs/integration-guide.md
+++ b/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:
diff --git a/docs/quickstart.md b/docs/quickstart.md
index ca877f6..de61a3e 100644
--- a/docs/quickstart.md
+++ b/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.