UNS documentation

Durable human-response coordination for agent workflows and high-trust backend operations.

Task	Document
Evaluate UNS	Product, roadmap, architecture, delivery semantics
Quickstart: send a signal	README
Configure policies	Policy lifecycle
Integrate an app	API, integration modes, producer integration guide
Integrate an AI agent (MCP)	Agent & MCP integration guide, API (MCP)
Operate and audit	Deployment, local runbook, deployment smoke, security, observability, operator console guide
Support & troubleshoot incidents	Support state machine & schema, Troubleshooting Guides (TSG-01 – TSG-06)
Extend UNS	Architecture
Verify implementation	Testing, consolidated baseline
Independent/adversarial review	External review brief, iteration 2 disposition
Migrate existing callers	Migration

Documentation Tracks

1. Architecture & Product Contract
2. Product Contract - Core boundaries, obligation semantics, and safety posture
3. Roadmap (v0.2.0 → v1.0.0) - Milestone horizons (v0.3.0–v1.0.0), in-tree scaffolding rationale, and live GitHub Milestones
4. Architecture - Durable SQLite & PostgreSQL outbox (uns.Runtime), policy engine, and transport topology
5. Delivery Semantics - Idempotency, deduplication windows, fallback, and ACK lifecycles
6. Policy Lifecycle - Policy version states (DRAFT, PREVIEW, ACTIVE, RETIRED), autonomy modes (PREVIEW, SHADOW, LIVE), and change proposals (PROPOSED, APPROVED, APPLIED)

7. Security Model - Authentication, principal binding, and Console/MCP security boundaries

8. Deployment & Operations

9. Deployment Guide - Complete environment variable matrix, process topology, reverse-proxy/TLS setup, uns-migrate, backups, and uns-maintain
10. Local Deployment Runbook - Persistent localhost recording stack (127.0.0.1:8000 and 127.0.0.1:5173)
11. Deployment Smoke Report - Container, socket, and browser verification evidence

12. Observability & Probes - Health/readiness checks, /metrics, structured logs, and SQLite/PostgreSQL audit queries

13. Support Reference & Troubleshooting Guides (TSGs)

14. State Machine & Schema Reference - Entity-Relationship diagram, state transition diagrams, and complete column/event reference

15. Troubleshooting Guides Index:

    • TSG-01: Dead Letter Queue (DLQ) Spikes & Replay
    • TSG-02: Stuck Leases, Slow Providers & Ambiguous Side Effects
    • TSG-03: ACK Timeouts, Principal Conflicts & Callback Backlog
    • TSG-04: Policy Reload Failures & Producer Override Rejections
    • TSG-05: MCP Server (uns-mcp) & Agent Integration Recovery
    • TSG-06: Database Maintenance (uns-maintain), Retention & Archival

16. End-User & Integrator Guides

17. Operator Console Guide - Screen-by-screen walkthrough of the React UNS Console (/ui/* read models and capability-gated /api/v1/* actions)
18. Producer Integration Guide - End-to-end recipes for Python (uns.Client), HTTP REST, and WebSockets
19. Agent & MCP Integration Guide - Safe MCP host setup, tool catalog, and simulation-first agent workflows

Console Preview

Historical specifications are indexed in migration and provenance. They do not override current contracts. The package names notification and uns are retained implementation/compatibility details, not separate products.