stack/docs/PRDs/2026-08-31_PRD_rev1/VIS.1-north-star.md

id, status, ratified

id	status	ratified
VIS.1	ratified	2026-09-01 (Jason Woltje; PRD rev1 ratification PR)

VIS.1 — Product north star

Successor text to rev0 Part I (rev0 PRD lines 33–215, preserved there verbatim). Base text unchanged except marked rev1 annotations; the decision registry moves to GOV.3-decision-map.

1. What Mosaic Stack is (D1)

Mosaic Stack is an open-source, AI-first platform for people who want a self-hosted environment for agentic management and a life operating system. It serves personal, business, and employee needs from one deployment, and the work is offered freely.

"AI-first" means agents are first-class operators of the system, not a bolted-on chat box: the platform exists to let humans direct fleets of agents over their projects, tasks, communications, and infrastructure, with the same tools and the same guarantees whether a human or an agent is acting.

2. Who it is for (D1, D9)

The operator of a deployment is its user. Mosaic Stack is not a hosted business: running the system as a service for external customers is outside the north star. Multi-tenancy exists WITHIN a deployment so that one operator can separate their world — for example, several LLCs plus a personal domain — while every deployment is self-hosted by its own operator.

"Company" in the hierarchy is organizational separation for one operator's world, not a customer account.

3. Deployment modes (D3)

Two modes, chosen at install time:

	Standalone / personal	Enterprise
Brains	one mosaic-brain (system + user files)	system brain for config + one brain per user
User-data isolation	single user	no user-data leakage between users; sharing is opt-in
Secrets	OpenBao/Vault or flat files	OpenBao/Vault REQUIRED
Conversion	Standalone → Enterprise, one-way	terminal state

Brains are configurable as external git repositories (recommended, not required); git tracking is always on locally.

Federation (connecting deployments: system-level config, assigned users, rights and data-access control, trusts with boundaries, exfiltration monitoring) is intentionally not fully designed. It is deferred, appears on the roadmap as a placeholder phase per D11, and nothing in v1 may foreclose it. D3 as amended 2026-09-01 (Q-T1 ruling B): federation milestones M1–M3 (Step-CA, enrollment, grants, mTLS auth guard, ScopeService, list/get/ capabilities verbs) are shipped but frozen — present in code behind the tier === 'federated' gate, dormant since 2026-06-25, absent from the canonical compose topology (D15), excluded from the v1 bar, tracked as a dormant workstream in docs/fleet/NORTH_STAR.yaml, and gated on a security re-audit before any resumption. See GOV.5-open-questions Q-T1.

4. Structure and tenancy (D2, D9, D13)

The hierarchy:

company/organization  (N per deployment)
└─ estate             (each in exactly one company)
   └─ project         (each in exactly one estate)
      └─ workspace    (project-specific; carries the Kanban)

Rules:

• Users can create N companies, N estates, N projects.
• Tasks bubble UP the hierarchy so whole-system status is visible at every level. Bubble-up is read-only aggregation, never a cross-workspace write.
• Granular RBAC: admins restrict access per company, estate, and project; grants are evaluated down the chain. Assets are transferable subject to the structure.
• workspace_id remains the hard mechanical isolation unit exactly as ratified in docs/requirements/native-kanban-sot.md (#751): PostgreSQL sole writable SOT, cross-workspace relationships rejected, fail-closed mutations. The hierarchy is parent structure ABOVE workspaces, used for RBAC evaluation and read-only roll-ups. The kanban SOT carries this as Amendment A1, added by reviewed PR — an amendment, not a rewrite (D13).

5. Identity (D10)

Built-in auth (better-auth) is the account system of record. Authentik and other external IdPs federate in via OIDC as login methods; they never become the system of record. Perimeter shims (forward-auth in front of a web host) are deployment workarounds, not the design.

6. Onboarding (D4)

Onboarding is a wizard that differs by mode, is re-runnable (no lock-in), and is extensible — new wizards attach as tabs.

Standalone flow captures: system and company name; component choices (Mosaic Comms/Matrix vs external; Mosaic SSO/Authentik vs external; Mosaic DB/PostgreSQL vs external; vector DB); the initial user (email/password/name/SSO); comms setup (Matrix/Discord/Slack); agent enrollment (harness choice and install, OAuth or API-key login, multi-account, model choice with recommendation, agent name and persona, account assignment, optional comms auto-enroll); a user onboarding profile (disabilities including ADHD/autism/PDA/vision, professional background, education, desired agent communication style, optional voice-matching interview, family/pets/friends/ hobbies/likes-dislikes); email and drive connectors (Gmail/IMAP, Google Drive/OneDrive/Dropbox) with granular agentic-access consent; SSO/OIDC configuration; an initial estate, an initial project, and seeded example data.

Enterprise uses the same skeleton with personal data optional; the focus moves to business structure, org chart, RBAC, M365 and external systems, immediate OIDC, SSO prominent.

Profile answers feed USER.md and/or the user's data store subject to the custody rule in §7.

7. Data custody (D6, D14)

• Sensitive profile categories (disabilities, family, communication style, and similar) live in the user's own brain ONLY. PostgreSQL holds structural data, consent records, and pointers — never the content. "User data does not leak" is enforced by architecture, not policy (D14).
• Standalone (one user, one brain) may keep the same split — D14 makes it optional in Standalone, not required. Keeping it is the recommended default because it preserves forward-compatibility with the one-way Enterprise conversion (D3).
• Estate brains hold operational records. Only product-relevant material migrates into this repository's docs; operational records stay in their brains and are linked (D6).

8. Architecture gate — the webUI sits OVER official tooling (D8, D12)

HARD RULE: every webUI operation goes through the Gateway API backed by the same official framework tooling the CLI uses. The CLI remains the primary execution method; the webUI uses the tools to operate and configure the system. The webUI never bypasses tooling to reach the database or filesystem directly.

Consequence for planning: when a desired webUI operation has no backing tool, the gap is scored "blocked on tooling" and the tool is built first. The product baseline therefore always includes all three D8 inputs: the tool inventory (what exists and what is missing), the webUI→tool mapping, and the measured current state of the next branch.

9. v1 slice (D11)

v1 is deliberately small:

1. Standalone onboarding wizard — system/company name, component choices, initial user, initial estate + project, seeded examples, re-runnable.
2. Hierarchy core — company → estate → project → workspace → kanban, with read-only task bubble-up.
3. Basic RBAC on the hierarchy.
4. Minimal agent enrollment — one harness, API key, name/persona.

Deferred beyond v1: connectors, comms integrations, voice-matching, M365, Enterprise conversion, federation. Every deferred item appears in docs/ROADMAP.md per the D11 rule: nothing exists only in heads.

10. Relationship to the fleet north star

docs/fleet/NORTH_STAR.md (generated from docs/fleet/NORTH_STAR.yaml) is the delivery-fleet north star: how the agent fleet that builds and operates the system should run (NS-1..NS-10, workstreams A–L). This PRD is the product north star. They are not competitors: the fleet north star is subordinate product-wise — its workstream J ("Web control plane") is one consumer of this PRD's D8/D12 gate — and this PRD does not redefine fleet invariants. The subordination rule is ratified in the frozen audit-input baseline (T2 operator freeze, 2026-08-25: "the PRD must cite and subordinate it, never fork it"). A change that would put the two in conflict must amend one of them explicitly, never fork a third document (drafting addition — see §12.1).

11. Explicit non-goals

• Hosted/SaaS operation for external customers (D9).
• A webUI that writes to the database or filesystem around the tooling (D12).
• A second writable task store beside PostgreSQL (native-kanban-sot invariants).
• Fully-designed federation in v1 (D3 — roadmap placeholder only; the shipped M1–M3 code is frozen, not a v1 feature).

D15 — Tiered containerized deployment (2026-08-30, containerization lane)

The stack ships a tiered deployment target, additive to the architecture gate (D8): (1) Standalone tier — docker compose is the canonical single-host deployment: postgres, valkey, openbao, gateway, appservice and the served webUI in one composition, with migrations, health checks, and a documented install/upgrade path; the registry (CI-published images) is the only deployment source. (2) Enterprise tier — Kubernetes manifests for the same service set, phase-gated on the standalone tier holding its acceptance bar. The v1 acceptance bar for the standalone tier: compose-up healthy; webUI hosts agent chat; an in-stack agent can open a PR to this repo; CI validates it; the running deployment adopts the merged change (pull + restart). Federation (D3 clause) remains deferred and unforeclosed. Implementation plan: docs/plans/2026-08-30_containerization.md.

---

rev1 annotations (2026-08-31)

• §8's architecture gate (webUI over official tooling, CLI primary) is elaborated for the control plane by UI.1-webui-surfaces and CLI.1-parity; register decision OD-53 confirms all interfaces share one CLI-backed engine.
• §4's RBAC and §5's identity are joined by the agent-side authority model in AUTHZ.1-capability-authority: role capability ceilings enforced at the harness by mosaic-core, composed by pure intersection.
• The fleet north star subordination (§10) gains a control-plane consequence: the WebUI workstream consumes this PRD's surface specifications (UI.1-webui-surfaces) rather than defining its own.