docs(policy): sync sphinx docs with canonical policy runtime

docs/source/api_reference.rst

@@ -220,6 +220,42 @@ Removed (breaking change):
 * ``/api/lab/world-prompts/*``
 * ``/api/lab/world-policy-bundle/*``
 
+Canonical Policy APIs
+~~~~~~~~~~~~~~~~~~~~~
+
+These endpoints provide the DB-first policy control plane. All require
+admin or superuser session scope.
+
+* ``GET /api/policy-capabilities`` - Return allowed policy types/statuses for current role
+* ``GET /api/policies`` - List canonical policy variants with optional filters
+* ``GET /api/policies/{policy_id}`` - Get one policy variant (optional ``variant`` query)
+* ``POST /api/policies/{policy_id}/validate`` - Validate a policy variant payload
+* ``PUT /api/policies/{policy_id}/variants/{variant}`` - Validate and upsert a variant
+* ``POST /api/policy-activations`` - Set one activation pointer for world/client scope
+* ``GET /api/policy-activations`` - List activation pointers (effective overlay by default)
+* ``POST /api/policy-publish`` - Publish deterministic manifest/artifact metadata
+* ``GET /api/policy-publish/{publish_run_id}`` - Fetch one persisted publish run
+* ``POST /api/policy-import`` - Import one publish artifact payload into canonical DB state
+* ``GET /api/policy/hash-snapshot`` - Return deterministic world-scope hash snapshot from effective activations
+
+Publish request example:
+
+.. code-block:: json
+
+    {
+      "world_id": "pipeworks_web",
+      "client_profile": null
+    }
+
+Import request example:
+
+.. code-block:: json
+
+    {
+      "artifact": { "...": "publish_manifest_payload" },
+      "activate": true
+    }
+
 Pipeline Generation
 ~~~~~~~~~~~~~~~~~~~
 

docs/source/architecture.rst

@@ -127,7 +127,9 @@ Package Layout
     │   │   ├── game.py         # Commands, chat, status, heartbeat
     │   │   ├── auth.py         # Login, logout, session selection
     │   │   ├── admin.py        # Admin dashboard + management routes
-    │   │   ├── lab.py          # Axis Descriptor Lab canonical draft APIs
+    │   │   ├── lab.py          # Axis Descriptor Lab diagnostics + prompt compile APIs
+    │   │   ├── policies.py     # Canonical policy CRUD/activation/publish/import APIs
+    │   │   ├── policy.py       # Canonical policy hash snapshot API
     │   │   └── register.py     # Route assembly helper
     │   ├── auth.py             # DB-backed sessions with TTL
     │   ├── password.py         # bcrypt hashing via passlib
@@ -283,7 +285,8 @@ Located in ``src/mud_server/translation/``:
   from ``world.json``.
 
 See :doc:`translation_layer` for the full service contract and
-prompt template format. See :doc:`lab_artifact_editor` for the server-backed draft and promotion workflow exposed to the Axis Descriptor Lab.
+prompt template format. See :doc:`lab_artifact_editor` for the DB-first
+Axis Descriptor Lab diagnostics and prompt compilation workflow.
 
 Event Bus Architecture
 ~~~~~~~~~~~~~~~~~~~~~~

docs/source/database.rst

@@ -182,6 +182,88 @@ The ASCII diagram below reflects the current SQLite schema in ``data/mud.db``.
     | NN  value              TEXT      |
     +----------------------------------+
 
+
+    +----------------------------------+
+    | policy_item                      |
+    +----------------------------------+
+    | PK  policy_id          TEXT      |
+    | NN  policy_type        TEXT      |
+    | NN  namespace          TEXT      |
+    | NN  policy_key         TEXT      |
+    | NN  created_at         TEXT      | DEFAULT CURRENT_TIMESTAMP
+    | UNI(policy_type, namespace, policy_key)
+    +----------------------------------+
+
+
+    +----------------------------------+
+    | policy_variant                   |
+    +----------------------------------+
+    | PK  id                 INTEGER   |
+    | NN  policy_id          TEXT      | FK -> policy_item.policy_id (ON DELETE CASCADE)
+    | NN  variant            TEXT      |
+    | NN  schema_version     TEXT      |
+    | NN  policy_version     INTEGER   |
+    | NN  status             TEXT      | CHECK IN (draft, candidate, active, archived)
+    | NN  content_json       TEXT      |
+    | NN  content_hash       TEXT      |
+    | NN  updated_at         TEXT      |
+    | NN  updated_by         TEXT      |
+    | UNI(policy_id, variant)
+    +----------------------------------+
+
+
+    +----------------------------------+
+    | policy_activation                |
+    +----------------------------------+
+    | PK  world_id           TEXT      | FK -> worlds.id (ON DELETE CASCADE)
+    | PK  client_profile     TEXT      | DEFAULT ''
+    | PK  policy_id          TEXT      | FK -> policy_item.policy_id (ON DELETE CASCADE)
+    | NN  variant            TEXT      | FK -> policy_variant(policy_id, variant)
+    | NN  activated_at       TEXT      |
+    | NN  activated_by       TEXT      |
+    |     rollback_of_activation_id INTEGER |
+    +----------------------------------+
+
+
+    +----------------------------------+
+    | policy_validation_run            |
+    +----------------------------------+
+    | PK  id                 INTEGER   |
+    | NN  policy_id          TEXT      |
+    | NN  variant            TEXT      |
+    | NN  is_valid           INTEGER   | CHECK IN (0, 1)
+    | NN  errors_json        TEXT      | DEFAULT '[]'
+    | NN  validated_at       TEXT      |
+    | NN  validated_by       TEXT      |
+    +----------------------------------+
+
+
+    +----------------------------------+
+    | policy_audit_event               |
+    +----------------------------------+
+    | PK  id                 INTEGER   |
+    | NN  event_type         TEXT      |
+    |     world_id           TEXT      |
+    | NN  client_profile     TEXT      | DEFAULT ''
+    |     policy_id          TEXT      |
+    |     variant            TEXT      |
+    | NN  actor              TEXT      |
+    | NN  event_payload_json TEXT      | DEFAULT '{}'
+    | NN  created_at         TEXT      |
+    +----------------------------------+
+
+
+    +----------------------------------+
+    | policy_publish_run               |
+    +----------------------------------+
+    | PK  id                 INTEGER   |
+    | NN  world_id           TEXT      | FK -> worlds.id (ON DELETE CASCADE)
+    | NN  client_profile     TEXT      | DEFAULT ''
+    | NN  actor              TEXT      |
+    | NN  manifest_json      TEXT      |
+    | NN  created_at         TEXT      |
+    +----------------------------------+
+
 Notes
 -----
 
@@ -198,6 +280,9 @@ Notes
   in-world sessions must set both and match character ownership/world.
 - Axis state is tracked in **normalized tables** (``axis``, ``axis_value``,
   ``character_axis_score``) with an **event ledger** (``event*`` tables).
+- Canonical policy control-plane state lives in ``policy_*`` tables.
+  Runtime policy reads use effective ``policy_activation`` pointers rather than
+  world package files.
 - ``world_permissions`` stores invite-style access grants. Open-world access is
   policy-driven from config and may not require a row in this table.
 - Hot-path indexes are intentionally maintained for world-scoped session activity,

docs/source/getting_started.rst

@@ -39,7 +39,14 @@ Initialize Database
 
 This creates the SQLite database with required tables. If ``MUD_ADMIN_USER``
 and ``MUD_ADMIN_PASSWORD`` are set and no users exist, ``init-db`` also
-bootstraps the superuser.
+attempts superuser bootstrap.
+
+By default, ``init-db`` also bootstraps canonical policy artifacts for
+discovered worlds using ``latest.json`` pointers from the policy export repo
+(``pipe-works-world-policies``). To control this behavior:
+
+* Set ``MUD_POLICY_EXPORTS_ROOT`` to an explicit export-repo root path.
+* Use ``mud-server init-db --skip-policy-import`` to skip bootstrap import.
 
 Create Superuser
 ~~~~~~~~~~~~~~~~
@@ -158,9 +165,25 @@ To create your own world:
 
 1. Create ``data/worlds/<world_id>/world.json``.
 2. Add one or more zone files under ``data/worlds/<world_id>/zones/``.
-3. Initialize DB and import canonical policy artifacts into SQLite policy tables.
-4. Activate policy variants for the target world scope.
-5. Restart the server so the world package is loaded.
+3. Initialize DB:
+
+   .. code-block:: bash
+
+      mud-server init-db
+
+4. Import canonical policy artifact for the world (if needed):
+
+   .. code-block:: bash
+
+      mud-server import-policy-artifact --artifact-path /abs/path/publish_<manifest_hash>.json
+
+5. Verify effective activation for the world scope:
+
+   .. code-block:: bash
+
+      curl -s "http://127.0.0.1:8000/api/policy-activations?scope=<world_id>&effective=true&session_id=<sid>"
+
+6. Restart the server so the world package is loaded.
 
 No code changes are required.
 
@@ -351,6 +374,9 @@ Optional configuration:
    * - ``MUD_ADMIN_PASSWORD``
      - (none)
      - Superuser password for create-superuser or init-db bootstrap
+   * - ``MUD_POLICY_EXPORTS_ROOT``
+     - (auto-resolved)
+     - Override root path used by ``init-db`` artifact bootstrap + publish/import flows
    * - ``MUD_REQUEST_TIMEOUT``
      - ``30``
      - HTTP request timeout (seconds) for TUI
@@ -408,9 +434,18 @@ The ``mud-server`` CLI provides these commands:
 .. code-block:: text
 
     mud-server init-db           Initialize database schema
+    mud-server import-policy-artifact  Import one canonical publish artifact
     mud-server create-superuser  Create a superuser account
     mud-server run               Start the server
 
+Policy bootstrap/import helpers:
+
+.. code-block:: text
+
+    mud-server init-db --skip-policy-import
+    mud-server import-policy-artifact --artifact-path /abs/path/publish_<manifest_hash>.json
+    mud-server import-policy-artifact --artifact-path /abs/path/publish_<manifest_hash>.json --no-activate
+
 The ``pipeworks-admin-tui`` CLI (requires ``[admin-tui]`` extra):
 
 .. code-block:: text