ThothII/docs/superpowers/plans/2026-07-11-portable-deployment-program.md

Portable Deployment Program

For agentic workers: execute the linked plans in order. Each plan ends with a compatibility gate and can be released independently.

Goal: Deliver the approved portable ThothII architecture through four independently reviewable implementation plans.

Architecture: Preserve the current frontend → backend → Pi → tht workflow while moving DWH, vector, and Evidence access behind typed adapters. Build two application images and compose optional pgvector and preprocessing services through deployment profiles.

Tech Stack: Python 3.11+, Pydantic 2, SQLAlchemy/PostgreSQL, Fastify/TypeScript, React/Vite, Docker BuildKit, Docker Compose, PostgreSQL+pgvector.

Global Constraints

• Keep harness/workflow.yaml and phase semantics unchanged.
• Keep session documents and review_decisions.jsonl as the persistence truth.
• Preserve pristine JSON stdout for every tht --json command.
• Keep DWH access read-only by credentials and client-side guards.
• Keep vector reader and writer credentials separate.
• Produce exactly two ThothII-owned application images; infrastructure images are optional dependencies.
• Preserve current workspace behavior through an explicit migration window.
• UI strings remain English; workspace content retains its configured language.
• Run harness pytest, gate JS tests, backend vitest+tsc, and frontend vitest+tsc before release.

---

Ordered plans

1. Adapter Foundations
   Establishes protocols, capability reporting, factories, and backwards-compatible configuration.

2. Container Packaging and Portable Storage
   Builds thothii-core and thothii-frontend, runtime configuration, logical roots, Compose base, and diagnostics.

3. Optional Local pgvector
   Adds the direct vector adapter, schema migration tooling, persistent service profile, backup/restore, and parity tests.

4. Evidence Sources and Preprocessing
   Adds source adapters, canonical corpus, incremental manifests, atomic publish, and separate document/DWH jobs.

Program gates

• After Plan 1, current server and workstation workspaces behave identically through the new factories.
• After Plan 2, the current external-service installation runs from the two images.
• After Plan 3, profiles B and C run with an optional local pgvector volume.
• After Plan 4, runtime retrieval no longer requires live access to original Evidence sources.
• Complete one L2 session for each deployed DWH transport and vector transport pairing in scope.
• Update PROJECT_STATE.md only after each plan's verification evidence is available.