From 3c2d8631e5d5685ec15af2162bf8d85bf9af2f88 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Sat, 7 Nov 2026 10:56:26 -0600 Subject: [PATCH 1/2] docs: record owner rulings for organizations --- .../2026-11-07_organizations-owner-rulings.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/plans/2026-11-07_organizations-owner-rulings.md diff --git a/docs/plans/2026-11-07_organizations-owner-rulings.md b/docs/plans/2026-11-07_organizations-owner-rulings.md new file mode 100644 index 000000000..506b932a7 --- /dev/null +++ b/docs/plans/2026-11-07_organizations-owner-rulings.md @@ -0,0 +1,47 @@ +# Organizations: owner rulings, 2026-11-07 + +Recorded by Mos (lead) from Jason's messages of 2026-11-07, around 16:39Z and +16:55Z. These bind the multi-organization design (working files under +`/mnt/storage/scratch/mosaic-lead/uidev/business-design-r*.md`). Corrections +go in a new dated file, not edits here. + +## Rulings + +1. **Name.** "Business" becomes "Organization" in labels, routes, help and new + CLI verbs now. The internal rename (package `packages/business`, the + `businesses/` config directory, `--business` flags, schema fields) is not + optional. It may wait, but it is a priority follow-up, because mixed names + cause confusion. +2. **Isolation.** Each organization runs its own bus. One Console switches + between them from Settings. +3. **No migration.** No existing business must be migrated. The full setup is + tested from scratch on a fresh instance. +4. **Test order.** An agent runs the full creation end to end with the CLI, + then with the WebUI, before Jason walks through it in the WebUI. +5. **Dev instance authority.** The dragon-lin instance is throwaway and for + development only. Agents may use it, and act as its human for these tests, + without asking. That is why it needs no sign-in. A deployed system keeps + human sign-in and the agent restrictions on actions taken for the user. +6. **WebUI creation.** The WebUI creates an organization with a WYSIWYG editor + of its JSON, starting from a template. Every WebUI action is tied to a CLI + command. +7. **Theme.** Each organization can have its own theme, stored in its file. + Themes are plugins: the choice lists whatever themes are installed. +8. **Proxy.** One model proxy per user by default; that user's organizations + share it, and an organization may opt into its own. On multi-user instances, + sharing between users is by explicit, revocable grant (time-limited, + unlimited, per key). Grants come later. +9. **Organization git.** Each organization has its own canonical git checkout + for its high-level information and queue. A remote is optional when the user + chooses "local only" and accepts the risk. +10. **Project git.** Every project uses git. The user chooses per project + whether it has a remote or is **local only** (a local repository that is + never pushed), for throwaway or temporary work that needs no durable + remote. Jason first said this on 2026-11-06; it was not recorded then. +11. **Access.** JSON access control is acceptable for the MVP. Database-backed + RBAC with tighter security comes later. +12. **Modules.** The system is modules connected through documented API calls. + Each function (for example the model proxy, the OpenMontage plugin, the + creative writing system) is a module with a declared set of calls. + Swapping or disabling a module must not break the core. Adding a module + must never require rewriting the core. -- 2.54.0 From 00ef0bd3016e3434a944aea45415fd19a5da9faa Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Mon, 9 Nov 2026 11:55:44 -0600 Subject: [PATCH 2/2] docs: record unified workspace direction and PRD 1.20 draft (#1873) --- BUILD-LOG.md | 2 + docs/plans/2026-11-09_prd-1-20-draft.md | 136 ++++++++++ ...11-09_unified-workspace-owner-direction.md | 238 ++++++++++++++++++ 3 files changed, 376 insertions(+) create mode 100644 docs/plans/2026-11-09_prd-1-20-draft.md create mode 100644 docs/plans/2026-11-09_unified-workspace-owner-direction.md diff --git a/BUILD-LOG.md b/BUILD-LOG.md index 837acac3b..9494fe9d1 100644 --- a/BUILD-LOG.md +++ b/BUILD-LOG.md @@ -6337,3 +6337,5 @@ R5 quote fallback room (#797 D3, 2026-11-06, MVP3 lead): r4 review P2 found that 2026-11-07 UTC | Organizations S1 — implementation phase | Before: ui-dev c8d6d12fe used the instance root for one bus and the Console had no scoped lifecycle commands. The S1 stream charter and boundaries are in /mnt/storage/scratch/mosaic-lead/uidev/org-release/PLAN.md. The queue refused this linked worktree; canonical checkout access was excluded. Verification and unresolved integration boundaries follow in the stream report. 2026-11-07 UTC | Organizations S1 — implementation evidence | Organization-root bus and launcher paths, guarded lifecycle and Console launch/stop were implemented locally. Focused Node 26 tests and host regressions passed; the fresh-organization notifier choice, shared-proxy S2 integration, and remaining instance-root consumers are not complete. Exact commands, inventory, failures and boundaries: /mnt/storage/scratch/mosaic-lead/uidev/org-release/report-s1.md. No push or deployment. Gitea issue creation was excluded by the no-network and no-external-communication limits. + +2026-11-09 UTC | Unified workspace (#1873) — direction recorded | Before: the 11-07 rulings had one Console switch between organizations from Settings, tasks only in each org queue, and an agent bound to one organization (REQ-USER-1). After: Jason's 11-09 direction and answers recorded in docs/plans/2026-11-09_unified-workspace-owner-direction.md (all orgs visible at once, per-org task stores with a Vikunja option and an aggregated Kanban, root/org/project agents with one cross-org assistant, system type plug-ins, self-service restart and model switch). PRD 1.20 draft 1 written for his exact-text approval; the PRD itself is unchanged. The unpushed 11-07 rulings record (ad8140065) lands with it. diff --git a/docs/plans/2026-11-09_prd-1-20-draft.md b/docs/plans/2026-11-09_prd-1-20-draft.md new file mode 100644 index 000000000..826d9aa59 --- /dev/null +++ b/docs/plans/2026-11-09_prd-1-20-draft.md @@ -0,0 +1,136 @@ +# PRD version 1.20, draft 1: unified workspace + +- Status: draft, not approved. Jason approves the exact text before it + enters `docs/prd/mosaic-stack.md` as version 1.20. +- Source: `docs/plans/2026-11-09_unified-workspace-owner-direction.md`, + Jason's direction and answers of 2026-11-09. +- Drafted by Mos (lead). + +Version 1.20 adds the unified workspace: every organization visible at once, +cross-organization views, three levels of agent configuration, per-org task +stores behind the task tracker kind, system type plug-ins and self-service +operation. It amends REQ-ASSIST-1, REQ-USER-1, REQ-TASK-1 and REQ-WEB-3. + +## Amended requirements + +Each entry gives the 1.19 text that changes and its 1.20 replacement. + +### REQ-ASSIST-1 + +1.19: "Each user has one assistant role per organization." + +1.20: Each user has one assistant across all of the organizations they +belong to. It knows the user's organizations, projects and sessions and +keeps one shared memory. It talks with the user and passes each +organization's work to that organization's chief of staff. It doesn't +direct other agents, create or assign tasks, or launch sessions. (The rest +of REQ-ASSIST-1 stands.) + +### REQ-USER-1 + +1.19: "An agent belongs to one organization and reaches only its allowed +projects and threads." + +1.20: Users and role-based access control exist at install and +organization level. An agent other than the assistant works in one +organization at a time. Its memory, files and credentials are scoped to that +organization, even when its definition comes from the user's root +configuration. It reaches only that organization's allowed projects and +threads. The assistant is the exception in REQ-ASSIST-1, and it reaches only +organizations its user belongs to. + +### REQ-TASK-1 + +1.19: "Tasks live in Vikunja..." + +1.20: Each organization stores its own tasks, through the task tracker +plug-in kind (REQ-PLUG-1). The default module is a store built into Mosaic +Stack. Vikunja is an optional module, and when an organization selects it +the 1.19 rules for Vikunja (bot tokens per role, one writing role per field, +REQ-TASK-2 polling) apply to that organization. Every task tracker module +supports create, read, update, archive and delete, ordering and grouping. +Archiving or removing an organization removes its tasks without touching +another organization's. + +### REQ-WEB-3 + +1.19: "The Console has controls to restart the bus and to reload the +organization file." + +1.20: The Console has controls to restart itself, to restart an +organization's bus, to reload the organization file, and to change the model +an agent instance runs on and apply it. Each control is a gated, trailed +action that a human takes. No agent can take it. A reload applies +`launch.instances` changes to running sessions without a manual +`systemctl restart`. On a dev instance (`--dev-local-owner`) the controls +need no sign-in. + +## New requirements + +### Workspace + +- **REQ-WS-1.** The WebUI shows every organization the user belongs to at + all times. A collapsible Organizations item in the sidebar lists them. + There is no organization switcher. +- **REQ-WS-2.** The Console reads across the buses of the user's + organizations to build shared views. Each organization keeps its own bus + as the tenant boundary (REQ-ORG-1). A shared view shows only + organizations the user belongs to. +- **REQ-WS-3.** The main dashboard sums activity, work and metrics across + all of the user's organizations and projects. +- **REQ-WS-4.** Each organization has a dashboard with its docs, every + configurable setting, its KPIs and metrics, and its active agent + sessions. +- **REQ-WS-5.** The projects list covers every organization. It sorts and + filters by organization, status, name and activity. Each project shows + its owning organization by icon, color and avatar. +- **REQ-WS-6.** One inbox holds every item that needs the user, from every + organization, project and session. +- **REQ-WS-7.** One view shows activity across all organizations and + projects. Organizations and projects can be open side by side. +- **REQ-WS-8.** The tasks view aggregates every organization's tasks, with + Kanban and list layouts, filtered by organization and project. It works + the same for every task tracker module. + +### Agent levels + +- **REQ-AGENT-1.** Agents are configured at three levels: the user's root, + the organization and the project. A project's available agents are the + union of the three. +- **REQ-AGENT-2.** The user can see and change the configuration of agents, + organizations, projects and sessions, and can override any setting at any + time, through the write path (REQ-ROLE-3). +- **REQ-AGENT-3.** The chief of staff hires and fires agents at the + organization and project levels under REQ-COS-3. Root-level agents change + only by the user. + +### System types + +- **REQ-SYS-1.** System types are a plug-in kind. Its modules include + coding, creative writing, marketing, Mosaic Montage (the OpenMontage + fork) and business management. An organization enables a list of them. +- **REQ-SYS-2.** A project may use any system type its organization + enables, and none is required. An agent working in a project gets the + toolsets of the system types that project uses. + +### Accounts + +- **REQ-ACCT-1.** A deployed system requires user sign-in (OIDC, Q203). A + user creates organizations and belongs to any number of them. +- **REQ-ACCT-2.** An organization's owner invites another user into it. + The invited user joins with the grant the owner chose (REQ-USER-3). + +### Setup + +- **REQ-SETUP-1.** Quick Setup leaves its project with its records + initialized. +- **REQ-SETUP-2.** After Quick Setup, the assistant offers an onboarding + interview. It asks for the project's outcome and limits and drafts the + north star and a first PRD. The user approves each through the existing + approval path. + +## Open questions for the approval + +1. The final name for the Mosaic Montage module. +2. REQ-AGENT-3 keeps root-level agents user-only. Should the chief of staff + also be able to propose root-level hires for the user to approve? diff --git a/docs/plans/2026-11-09_unified-workspace-owner-direction.md b/docs/plans/2026-11-09_unified-workspace-owner-direction.md new file mode 100644 index 000000000..a7833e506 --- /dev/null +++ b/docs/plans/2026-11-09_unified-workspace-owner-direction.md @@ -0,0 +1,238 @@ +# Unified workspace: owner direction, 2026-11-09 + +Recorded by Mos (lead) from Jason's T3 message of 2026-11-09, around 17:50Z, +and his answers to four clarifying questions at about 18:00Z. It binds the +next phase of the organizations work. Corrections go in a new dated file, not +edits here. + +## What prompted it + +Jason ran Quick Setup on the dragon-lin dev instance (uiorg) to create the +`test3` organization. Two things went wrong: + +- The new project showed "This project has no records yet" with an + "Initialize project records" button. Quick Setup should have done that. + The setup receipts show the org, checkout, project repository and bus + steps at 17:19:20Z. The records repository first appears at 17:21:13Z, + from the button press. The fix round reproduces it. +- After he pressed the button, the overview showed the north star template + as raw text: `# North star Describe the outcome this project should + achieve...`. The overview prints the markdown source instead of rendering + it. + +He also named a standing problem with how the dev instance is operated. + +## Owner text, verbatim + +> The Quick Setup should auto-initialize since this didn't ask any +> questions. An onboarding interview to determine the north star and PRD +> would be beneficial here. +> +> I've noticed that we have a perennial issue with needing to restart the +> console, or requiring a sign-in (model proxy), and other limiting behaviors +> that don't seem to make sense for the operating method. We are running +> this as a test instance on my dev workstation (dragon-lin), auth is not +> required for this local testing env., and we need to be capable of rapid +> iteration without undue manual intervention by the user. I also don't see +> where we can trigger any type of restart or relaunch with the available +> config from within the webui. The user should be able to change the +> running model and restart the service from within the system. +> +> Here is what I want: +> - Mosaic Stack system runs +> - Allows user to log in +> - User can create orgs, and be invited to join another user's org +> - User belongs to N organizations +> - All orgs are visible in the interface for the user to see the org, +> project, sessions within each +> - Tasks are overarching for all projects; a central store of tasks +> - Agents can be configured at the root, org, and project level +> - The user is able to see all happenings in the system from one pane +> - Projects are sortable and filterable by org, status, name, activity +> - Inbox contains all items needing the user; all orgs/projects/sessions +> with needs surface here +> - System allows for side-by-side operation of orgs and projects all +> visible in single pane +> - Rather than selecting an organization with a switch or in the settings +> menu, the user sees all orgs at all times. +> - Sidebar collapsible item for Organizations; user clicks to see all info +> about the organzation +> - The Docs are available on the org dashboard +> - All configurables are visible on the org dashboard +> - Org dashboard features KPIs/Metrics for the org +> - Active agent sessions visible on the org dashboard +> - Projects sidebar list indicates the organization owning the project via +> iconography, color, and "avatar" for org +> - Main dashboard for user surfaces sum and cumulative data for all +> orgs/projects, not just one +> - The system is configured to use plugins/modules to allow for various +> system types like coding, creative writing, Mosaic Montage (fork of +> OpenMontage) for social media production, business management +> - Each Project within an org is capable of using multiple system types +> - Example: Org. Distinctly Digital +> - enabled plugins: coding, creative writing, marketing, Mosaic +> Montage/Mosaic Studio (whatever we name this...), business management, +> - Each project within "Distinctly Digital" has access to the plugins, +> but is not required to use all of them +> - Agents configured for the user's root config are available +> - Org agents are available +> - Project agents are available +> - Agents use the toolsets for the plugin/module appropriately +> - Configuration for the agents, orgs, projects, sessions are all +> available for the user to tweak as needed +> - Chief of Staff can hire and fire agents to meet the user's system +> needs +> - User can override settings at any time via the configuration +> +> I'm thinking this information needs to be recorded for durability and we +> need to work toward this implementation. + +## Answers to the clarifying questions + +1. **Task store.** Verbatim: "We need to keep the tasks separated at an org + level. This allows for archive, instant removal of org tasks without + violating the other orgs. I'd like to see a basic config use per-org, + aggregated store with the option to use Vikunja. Not all users will use + Vikunja. Either way, we need a way to store, retrieve, archive, maintain, + organize, and view all the tasks. If we use Vikunja or a custom-rolled + solution within Mosaic Stack, they all need to surface with Kanban, etc. + for the user to see properly." +2. **Agent scope across orgs.** Verbatim: "The user's main interaction agent + needs to be aware of all orgs, projects, etc. That one interaction agent + uses a shared memory. The other agents are isolated per org." +3. **Multi-user.** Design sign-in, membership and invites now. Build them + in the second phase, after the single-user unified pane. +4. **Order.** Remove the operating friction first, then build the unified + pane. + +## Rulings that follow + +1. **All orgs at once.** The WebUI shows every organization the user + belongs to at all times. A collapsible Organizations item in the sidebar + lists them, and selecting one opens its dashboard. There is no + organization switcher, in Settings or elsewhere. +2. **Per-org isolation stays.** Each organization keeps its own bus as the + tenant boundary (REQ-ORG-1). The Console reads across the buses of the + user's organizations to build the shared views. Removing or archiving an + organization removes its data, tasks included, without touching another. +3. **Tasks.** Each organization stores its own tasks. The default store is + built into Mosaic Stack. Vikunja is an optional alternative, selected per + organization through the task tracker plug-in kind (REQ-PLUG-1). Both + support store, retrieve, archive, maintain and organize. The WebUI + aggregates every organization's tasks into one view with Kanban and list + layouts, filterable by organization and project. +4. **Agents.** Agents are configured at three levels: the user's root, + the organization and the project. A project's agents are the union of + all three. The user's main interaction agent (the assistant) is the one + exception to isolation. It knows all of the user's organizations, + projects and sessions, and it keeps one shared memory. Every other agent + is isolated to the organization it works in: its memory, files and + credentials are scoped to that organization, even when its definition + comes from the root. +5. **One pane.** One screen shows activity across every organization and + project. Organizations and projects can be open side by side. +6. **Main dashboard.** It sums across all organizations and projects, not + only one. +7. **Org dashboard.** It shows the organization's docs, every configurable + setting, KPIs and metrics, and its active agent sessions. +8. **Projects list.** It sorts and filters by organization, status, name + and activity. Each project shows its owning organization by icon, color + and avatar. +9. **Inbox.** One inbox holds everything that needs the user, from every + organization, project and session. +10. **System types are plug-ins.** Coding, creative writing, marketing, + Mosaic Montage (the OpenMontage fork; final name open) and business + management are modules. An organization enables a set of them. Each of + its projects may use any of the enabled set, and none is required. + Agents get the toolsets of the modules their project uses. +11. **Configuration.** The user can see and change the configuration of + agents, organizations, projects and sessions, and can override any + setting at any time. The chief of staff hires and fires agents to meet + the user's needs, within the existing PRD rules (REQ-ROLE, version + 1.7). +12. **Accounts.** The deployed system has user sign-in. Users create + organizations, belong to any number of them, and can be invited into + another user's organization. The dev instance keeps running with no + sign-in (ruling 5 of 2026-11-07). +13. **Operating the dev instance.** Routine operation needs no manual + intervention from the user. From the WebUI the user can restart the + Console and an organization's bus, and change the model an agent runs + on. Dev mode needs no sign-in, including for the model proxy. Agents + still cannot restart the Console; the user can, from the WebUI. +14. **Quick Setup.** Quick Setup leaves a project with its records + initialized. An onboarding interview then helps the user write the + north star and a first PRD. + +## What this supersedes or amends + +- **2026-11-07 ruling 2.** "One Console switches between them from + Settings" is superseded by ruling 1 above. The per-org bus in the same + ruling stands. +- **2026-11-07 ruling 9.** Each organization's queue lived only in its own + checkout. Ruling 3 above keeps tasks per organization, adds the Vikunja + option through the task tracker kind, and adds the aggregated view. +- **PRD 1.19, REQ-USER-1.** "An agent belongs to one organization" gains + the assistant exception in ruling 4. This needs a PRD version. The draft + is `docs/plans/2026-11-09_prd-1-20-draft.md`, and Jason approves the + exact text before it enters `docs/prd/mosaic-stack.md`. + +## Delivery plan + +Each phase follows the MVP rule: build, one review round, one fix round, an +agent E2E on a scratch instance, then a deploy to uiorg for Jason. + +### Phase F: operating friction (now) + +- **F1.** Quick Setup records: reproduce the `test3` gap on a scratch + instance and fix it, so a Quick Setup project opens with live Docs, Files + and north star. Render the north star as markdown on the project + overview. +- **F2.** Onboarding interview: after Quick Setup, the assistant opens a + conversation that asks for the outcome and limits, then drafts + `spec/north-star.md` and a first PRD. The user approves each through the + existing approval path. +- **F3.** Self-service operation: restart the Console and an org bus from + the WebUI, change an agent's model from Settings and apply it, and list + and remove every manual step the dev instance still needs, model proxy + sign-in included. + +### Phase U: unified pane + +- **U0.** Design samples first. Sample screens for the sidebar with all + orgs, the main dashboard, an org dashboard, the projects list, the inbox, + the task Kanban and side-by-side panes. Jason approves them before the + build (design samples are the acceptance target). +- **U1.** Cross-org read model in the Console: one API that reads every + organization's bus the user belongs to, for projects, sessions, inbox + items, tasks and metrics. +- **U2.** Sidebar and org dashboards. **U3.** Main dashboard, projects list + and inbox. **U4.** Task store: built-in per-org store behind the task + tracker kind, the Vikunja module, and the aggregated Kanban. **U5.** + Side-by-side panes. + +### Phase A: agent levels + +Root, organization and project agent configuration. The assistant spans +organizations with shared memory, and every other agent is isolated per +organization. The user can override settings, and the chief of staff hires +and fires at each level. + +### Phase P: system type plug-ins + +A plug-in kind for system types. Organizations enable modules, projects opt +in, and agents receive the modules' toolsets. First modules: coding (the +current behavior), creative writing, then Mosaic Montage, marketing and +business management. + +### Phase M: accounts (design now, build second) + +OIDC sign-in (OIDC-only per Q203), membership in N organizations, invites +into another user's organization, and access checks on the cross-org read +model. The design lands with Phase U so the read model has membership from +the start. + +## Open items + +- The final name for the Mosaic Montage module. +- Which "sign-in (model proxy)" step Jason hit. F3 inventories every manual + step on the dev instance and reports it. -- 2.54.0