stack/docs/MISSION-MANIFEST.md

Mission Manifest — MVP

Top-level rollup tracking Mosaic Stack MVP execution. Workstreams have their own manifests; this document is the source of truth for MVP scope, status, and history. Owner: Orchestrator (sole writer).

Mission

ID: mvp-20260312 Statement: Ship a self-hosted, multi-user AI agent platform that consolidates the user's disparate jarvis-brain usage across home and USC workstations into a single coherent system reachable via three first-class surfaces — webUI, TUI, and CLI — with federation as the data-layer mechanism that makes cross-host agent sessions work in real time without copying user data across the boundary. Phase: Execution (workstream W1 in planning-complete state) Current Workstream: W1 — Federation v1 Progress: 0 / 1 declared workstreams complete (more workstreams will be declared as scope is refined) Status: active (continuous since 2026-03-13) Last Updated: 2026-04-19 (manifest authored at the rollup level; install-ux-v2 archived; W1 federation planning landed via PR #468) Source PRD: docs/PRD.md — Mosaic Stack v0.1.0 Scratchpad: docs/scratchpads/mvp-20260312.md (active since 2026-03-13; 14 prior sessions of phase-based execution)

Context

Jarvis (v0.2.0) was a single-host Python/Next.js assistant. The user runs sessions across 3–4 workstations split between home and USC. Today every session reaches back to a single jarvis-brain checkout, which is brittle (offline-hostile, no consolidation, no shared state beyond a single repo). A prior OpenBrain attempt punished offline use, introduced cache/latency/opacity pain, and tightly coupled every session to a remote service.

The MVP solution: keep each user's home gateway as the source of truth, connect gateways gateway-to-gateway over mTLS with scoped read-only data exposure, and expose the unified experience through three coherent surfaces:

• webUI — the primary visual control plane (Next.js + React 19, apps/web)
• TUI — the terminal-native interface for agent work (packages/mosaic wizard + Pi TUI)
• CLI — mosaic command for scripted/headless workflows

Federation is required NOW because it unblocks cross-host consolidation; it is necessary but not sufficient for MVP. Additional workstreams will be declared as their scope solidifies.

Prior Execution (March 13 → April 5)

This manifest was authored on 2026-04-19 to rollup work that began 2026-03-13. Before this date, MVP work was tracked via phase-based Gitea milestones and the scratchpad — there was no rollup manifest at the docs/MISSION-MANIFEST.md path (the slot was occupied by sub-mission manifests for install-ux-hardening and then install-ux-v2).

Prior execution outline (full detail in scratchpads/mvp-20260312.md):

• Phases 0 → 7 (Gitea milestones ms-157 → ms-164, issues #1–#59): foundation, core API, agent layer, web dashboard, memory, remote control, CLI/tools, polish/beta. Substantially shipped by Session 13.
• Phase 8 (Gitea milestone ms-165, issues #160–#172): platform architecture extension — teams, workspaces, /provider OAuth, preferences, etc. Wave-based execution plan defined at Session 14.
• Sub-missions during the gap: install-ux-hardening (complete, mosaic-v0.0.25), install-ux-v2 (complete on 2026-04-19, 0.0.27 → 0.0.29). Both archived under docs/archive/missions/.

Going forward, MVP execution is tracked through the Workstreams table below. Phase-based issue numbering is preserved on Gitea but is no longer the primary control plane.

Cross-Cutting MVP Requirements

These apply to every workstream and every milestone. A workstream cannot ship if it breaks any of them.

#	Requirement
MVP-X1	Three-surface parity: every user-facing capability is reachable via webUI and TUI and CLI (read paths at minimum; mutating paths where applicable to the surface).
MVP-X2	Multi-tenant isolation is enforced at every boundary; no cross-user leakage under any circumstance.
MVP-X3	Auth via BetterAuth (existing); SSO adapters per PRD; admin bootstrap remains a one-shot.
MVP-X4	Three quality gates green before push: pnpm typecheck, pnpm lint, pnpm format:check.
MVP-X5	Federated tier (PG + pgvector + Valkey) is the canonical MVP deployment topology; local/standalone tiers continue to work for non-federated installs but are not the MVP target.
MVP-X6	OTEL tracing on every request path; traceparent propagated across the federation boundary in both directions.
MVP-X7	Trunk merge strategy: branch from main, squash-merge via PR, never push to main directly.

Success Criteria

The MVP is complete when ALL declared workstreams are complete AND every cross-cutting requirement is verifiable on a live two-host deployment (woltje.com ↔ uscllc.com).

• AC-MVP-1: All declared workstreams reach complete status with merged PRs and green CI
• AC-MVP-2: A user session on the home gateway can transparently query work-gateway data subject to scope, with no data persisted across the boundary
• AC-MVP-3: The same user-facing capability is reachable from webUI, TUI, and CLI (per MVP-X1)
• AC-MVP-4: Two-gateway production deployment (woltje.com ↔ uscllc.com) operational ≥7 days without incident
• AC-MVP-5: All cross-cutting requirements (MVP-X1 → MVP-X7) verified with evidence
• AC-MVP-6: PRD docs/PRD.md "In Scope (v0.1.0 Beta)" list mapped to evidence (each item: shipped / explicitly deferred with rationale)

Workstreams

#	ID	Name	Status	Manifest	Notes
W1	FED	Federation v1	planning-complete	docs/federation/MISSION-MANIFEST.md	7 milestones, ~175K tokens, issues #460–#466 filed
W2+	TBD	(additional workstreams declared as scoped)	—	—	Scope creep is expected and explicitly accommodated

Likely Additional Workstreams (Not Yet Declared)

These are anticipated based on the PRD In Scope list but are NOT counted toward MVP completion until they have their own manifest, milestones, and tracking issues. Listed here so the orchestrator knows what's likely coming.

• Web dashboard parity with PRD scope (chat, tasks, projects, missions, agent status surfaces)
• Pi TUI integration for terminal-native agent work
• CLI completeness for headless / scripted workflows that mirror webUI capability
• Remote control plugins (Discord priority, then Telegram)
• Multi-user / SSO finishing (BetterAuth + Authentik/WorkOS/Keycloak adapters per PRD)
• LLM provider expansion (Anthropic, Codex, Z.ai, Ollama, LM Studio, llama.cpp) + routing matrix
• MCP server/client capability + skill import interface
• Brain (@mosaicstack/brain) as the structured data layer on PG + vector

When any of these solidify into a real workstream, add a row to the Workstreams table, create a workstream-level manifest under docs/{workstream}/MISSION-MANIFEST.md, and file tracking issues.

Risks

• Scope creep is the named risk. Workstreams will be added; the rule is that each must have its own manifest + milestones + acceptance criteria before it consumes execution capacity.
• Federation urgency vs. surface parity — federation is being built first because it unblocks the user, but webUI/TUI/CLI parity (MVP-X1) cannot slip indefinitely. Track surface coverage explicitly when each workstream lands.
• Three-surface fan-out — the same capability exposed three ways multiplies test surface and design effort. Default to a shared API/contract layer, then thin surface adapters; resist surface-specific business logic.
• Federated-tier dependency — MVP requires PG + pgvector + Valkey; users on local/standalone tier cannot federate. This is intentional but must be communicated clearly in the wizard.

Out of Scope (MVP)

• SaaS / multi-tenant revenue model — personal/family/team tool only
• Mobile native apps — responsive web only
• Public npm registry publishing — Gitea registry only
• Voice / video agent interaction
• Full OpenClaw feature parity — inspiration only
• Calendar / GLPI / Woodpecker tooling integrations (deferred to post-MVP)

Session History

For sessions 1–14 (phase-based execution, 2026-03-13 → 2026-03-15), see scratchpads/mvp-20260312.md. Sessions below are tracked at the rollup level.

Session	Date	Runtime	Outcome
S15	2026-04-19	claude	MVP rollup manifest authored. Install-ux-v2 archived (IUV-M03 retroactively closed — shipped via PR #446 + releases 0.0.27 → 0.0.29). Federation v1 planning landed via PR #468. W1 manifest reachable at docs/federation/MISSION-MANIFEST.md. Next: kickoff FED-M1.

Next Step

Begin W1 / FED-M1 — federated tier infrastructure. Task breakdown lives at docs/federation/TASKS.md.