# TEACH Technical Implementation Guide

This kit supplies Hermes with an immutable working DISCOVER v2 baseline, educator/TEACH sources, strict schemas, fixtures, registries, governance contracts, 216 control rows, 48 packaged scenarios, 169 canonical checks and an independent kit verifier. It does not supply the completed target application.

## Required staged build

1. Verify the ZIP sidecar, internal manifest, source inventory and all file hashes.
2. Run the embedded verifier against the extracted kit.
3. Perform read-only platform, dependency, port, storage and Hermes capability preflight.
4. Show the Implementation Activation Card and obtain explicit approval before mutation.
5. Copy—not edit—the baseline application into a new target workspace.
6. Implement migrations, server routes, UI, state machines and tests in small checkpoints.
7. Keep all integrations, agents, tools, memory and external action off until their exact approved test stage.
8. Build a reproducible candidate, execute the 433-record ledger, inspect evidence and fix blockers.
9. Verify the candidate from a clean extraction on each claimed operating system.
10. Produce a target release manifest, checksums, dependency/SBOM record, install/backup/update/rollback/uninstall guides and evidence-derived handoff report.

## Minimum runtime architecture

- Loopback-only local full-stack application with authenticated opaque sessions, Origin/Host/CSRF checks, size/rate limits, security headers, no default password and single-writer lock.
- Server-side store/role/hat/context/partition/data-ceiling binding on every read, search, write, AI, agent, badge, export and backup path.
- Physically separate private and institution-approved repositories. No cross-store joins, shared search indexes, caches, memory, model context, badges, exports or backups.
- Strict JSON Schema 2020-12 input validation with unknown fields, duplicate keys, non-finite numbers, raw quiz answers and incompatible shapes rejected.
- Pre-persistence and pre-AI data classifier. `TEACH-DATA-X` is rejected without echo, transformation or content logging.
- Append-only content-free audit events using IDs, hashes, classifications, decisions, timestamps and reviewer references only.
- Exact source recommendation registry resolution by ID, bundled path and SHA-256. A missing/mismatched source disables the recommendation.
- Genuine Hermes capability discovery, provider session creation, ordered deltas, tool events, cancellation and retry idempotency. If unavailable, expose a truthful offline/manual mission path; never simulate streaming with canned text or timers.
- Pause All and selected-run Kill on a control path independent from model/agent execution.

## State contracts

Artifact lifecycle is exact and monotonic except explicit return/branch:

`Exploration → Simulation → Recommendation → Draft Artifact → Approved Plan → Authorized Execution → Completed Action → Evaluated Outcome`

Review state is independent. `Approved Plan` does not authorize action. `Authorized Execution` and `Completed Action` represent verified events outside the app; there is no TEACH execution endpoint.

Agent run state:

`disabled → draft_charter → proposed → authorized → running → reconciled → disabled`

Additional terminal states are `blocked`, `killed` and `retired`. P1/P2 authorization is one-use, exact-hash, context-bound and expiring. P3 is deterministic personal reminder code only; P4 is absent.

## Migration and recovery

Every migration requires a verified pre-backup, schema/version check, atomic transaction, integrity and foreign-key checks, context-isolation assertions, post-migration verification and rollback instructions. Rollback never revives expired sessions, approvals, tokens, source versions or authority receipts.

Backups default to the private store only. An institutional backup is separately authorized for exactly one partition and excludes private/other partitions. Restore begins in a quarantine preview and fails closed for corrupt, foreign or wrong-context data.

Overlay removal preserves the educator foundation and unrelated Nurse AI OS roles. Uninstall separately offers application removal, private-data deletion, institutional-partition deletion, cached-provider material deletion and backup retention/deletion with a preview and explicit confirmation.

## Required proof

Kit validation proves file integrity and contract coherence only. Target readiness requires executed positive, negative, permission, persistence, offline, failure, accessibility, security, recovery, fresh-extraction and clean-machine evidence. Every result record includes exact package hash and environment. Non-passing labels never count as Passed.
