oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b20b138fe485817e8d69d0c60e376e3c53af149a
waggle-os/docs/ux-refactor/gap-cards/S10-team-workspace.md
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
Details
moving
2026-09-02 10:10:29 +02:00

18 KiB
Raw Blame History

Gap Card — S10 · Team Workspace

Screen S10 of the Waggle OS UX-refactor. Execution model is the LOCKED in-place incremental refactor of apps/web + targeted backend extensions. Mockups are directional; PRD acceptance criteria win. Every claim below is grounded in real files.

Sources: PRD §12.11 (lines 613-626), §16.11 (1152-1158), §17 RBAC (1162-1187), §10.5 (329-338), §18 (1191-1218); blueprint _blueprint_extracted.txt lines 346-349, 470-473, 509, 514, 531-540, 542-545, J18/J19/J20/J21 (227-242); mockup screen_10_team_workspace.png.

1. Screen & purpose

Purpose (PRD §12.11): "Shared intelligence for teams." Team mode must feel like shared knowledge and shared outcomes, not just a member list + chat (explicit acceptance criterion, PRD line 626). It is the surface for the Team layer of the IA (PRD §10.5): team workspace, members, roles/permissions, shared memory, shared artifacts, shared skills, shared MCPs, and activity/audit.

This is a Teams/Enterprise-tier surface (PRD tier table; current placeholder gates it to "Teams ($49/mo per seat) and Enterprise"). It is the UI home for RBAC (PRD §17) and the team-governance API contract (PRD §16.11).

The mockup shows: workspace header with a team switcher + Invite/+ buttons; a metrics strip (memory frames, agents, automations, tasks); a "Team Activity" feed; "Pinned" items; "Team Members" panel with avatars/roles; a "Team Intelligence" summary card; "Upcoming" events; and a "Team Goals" progress section. Treat as visual direction only.

2. Required states (PRD / Blueprint)

Tabs (PRD §12.11, line 619): Overview · Shared Memory · Shared Artifacts · Skills · Agents · MCPs · Automations · Settings.

Overview content (PRD line 620): team spaces, metrics, members, activity, pinned items, team goals, upcoming events, team intelligence summary.

Sharing (PRD line 621): share memory / artifact / skill / MCP / automation into team scope subject to role. Journeys: J19 share memory → choose scope → audit → appears in team memory; J20 share artifact → team/workspace/member → permissions → activity feed (blueprint 234-239).

Member management + RBAC (PRD line 622): invite/member management (J18: invite → role selected → accept → permissions applied, blueprint 227-228).

RBAC roles (conflict to resolve — see §6):

  • PRD §17.2 table: Owner / Admin / Contributor / Viewer.
  • Blueprint §RBAC model + role table: Owner / Admin / Member / Viewer / Guest (lines 156, 536-540, 603).
  • Live substrate (teams.db): owner / admin / member / viewer (no contributor, no guest).

Empty / loading / permission states (blueprint 470-473): Loading, empty, populated, permission denied; Invite pending, role conflict, shared/private, audit event. Member actions: request access, change role, resend invite, export audit. J21: permission denied → permission message → request access (no silent failures or data leakage, blueprint 240-242).

Cache invalidation triggers (blueprint 514): memory import, artifact update, agent run completion, connector sync, automation completion, RBAC change — the Team Workspace must re-fetch on any of these.

Solo/offline behavior: RBAC must be enforced at both API and UI layers (blueprint 162). Local team CRUD already works in solo mode with a local userId (see §3).

3. Current state in repo (disposition: rework)

Frontend — apps/web/src/components/os/apps/TeamGovernanceApp.tsx (45 lines): a pure static placeholder. It renders three hardcoded info cards (Role-Based Access / Tool Governance / Audit Trail) + a tier-gate banner. Zero data fetching, zero adapter calls, no tabs, no members, no activity. Registered as appId governance in Desktop.tsx/Dock.tsx (see frontend inventory §a, line 47). The mockup's entire surface is unbuilt.

Adapter — apps/web/src/lib/adapter.ts has only the remote-proxy team methods: teamConnect (:1226), teamDisconnect, getTeamStatus (:1234), getTeamMembers (:1239), getTeamActivity (:1247), getTeamMessages (:1255), searchTeamMemory (:489). There are NO adapter methods for the local /api/teams/* CRUD (create team, get team detail, invite/add member, change role, remove member, team activity/audit). This is the single biggest frontend wiring gap.

Backend — substrate is strong and already live. packages/server/src/local/routes/team.ts exposes two prefixes:

  • /api/team/* = remote team-server proxy with local fallbacks (connect/disconnect/status/ teams/members/presence/activity/messages/governance/memory-search). /api/team/connect is requireTier('TEAMS') (:110); /api/team/governance/permissions is requireTier('ENTERPRISE') (:418).
  • /api/teams/* = local SQLite CRUD on teams.db (teams + team_members tables, DDL at team.ts:51-72), works in solo mode via getLocalUserId(dataDir) (:457). Full CRUD: POST /api/teams (:460, auto-adds creator as owner), GET /api/teams (:492), GET /api/teams/:id (:505, returns team + members), PUT /api/teams/:id (:523), DELETE /api/teams/:id (:553, owner-only), POST /api/teams/:id/members (:581, owner/admin only — this is invite/add), PUT+PATCH /api/teams/:id/members/:userId (:615/:642, role change), DELETE /api/teams/:id/members/:userId (:665), GET /api/teams/:id/activity (:690, reads audit_events via getAuditDb from events.js, :713-722).

RBAC is already enforced server-side with per-action checks: owner/admin gate add-member (:591), owner-only gate role change in PUT (:624) but owner/admin in PATCH (:649 — a real inconsistency to fix, see §9), owner-only delete-team (:558), can't remove the owner (:682), member self-removal allowed (:677). The local team_members.role CHECK constraint is ('owner','admin','member','viewer') (team.ts:64) — no contributor, no guest.

Remote/cloud governance substrate (backend-map §02b): the Postgres team layer (packages/server/src/db/schema.ts, 20 tables) has teams, team_members (composite PK (team_id,user_id), role default 'member', 02b:93-101), team_entities/team_relations/ team_resources (shared KG + assets, 02b:181-228), and the three team-capability governance tables added in migration 0001: team_capability_policies (standing policy per role, 02b:232), team_capability_overrides (one-off allow/deny, 02b:247), team_capability_requests (request→decision queue, 02b:262). These back the per-role tool allow/deny + approval surfaces the mockup/PRD imply, but only on the cloud server — the local /api/team/governance/permissions proxy (:418) is the only sidecar window into them. Note (02b:44): Postgres FKs are all ON DELETE no action — no cascades; deleting a team/user is blocked if children reference it.

Disposition rationale — rework (not create-new): the governance app slot, the dock entry, the tier-gate, and (critically) the entire local team CRUD + RBAC enforcement substrate already exist. The screen needs the placeholder component replaced with a real tabbed surface wired to existing routes + new adapter methods — not a new app and not a new backend data store.

4. Frontend work

Rework TeamGovernanceApp.tsx (rename concept to "Team Workspace"; keep appId governance to avoid touching Desktop/Dock/dock-tiers routing) into a tabbed shell. Reuse the existing tabbed-app pattern (MemoryApp.tsx 6-tab model, SettingsApp.tsx 8-tab model, ui/tabs.tsx).

Components to create (keep files small, 200-400 LOC per CLAUDE.md §coding-style):

  • apps/team/TeamWorkspaceApp.tsx (or in-place rework of TeamGovernanceApp.tsx) — tab shell: Overview · Shared Memory · Shared Artifacts · Skills · Agents · MCPs · Automations · Settings. Tier-gate stays (Teams/Enterprise) via existing LockedFeature.tsx / useFeatureGate.
  • apps/team/TeamOverviewTab.tsx — metrics strip + activity feed + pinned + team goals + upcoming + team-intelligence summary (mockup Overview).
  • apps/team/TeamMembersPanel.tsx — member list with avatars + role badges + role-change dropdown + remove (gated by current-user role). Reuse ui/avatar, ui/badge, ui/dropdown-menu.
  • overlays/InviteMemberDialog.tsx — invite by email/userId + role select (J18). Reuse ui/dialog, ui/select. POSTs to /api/teams/:id/members.
  • apps/team/TeamActivityFeed.tsx — audit/activity list (reuse TimelineApp/EventsApp row styling). Export audit action (blueprint 472).
  • apps/team/ShareToTeamDialog.tsx — scope picker (team/workspace/member) for sharing a memory/artifact/skill/MCP/automation into team scope with role check (J19/J20). Surfaced from Memory/Artifact screens too; lives here as the canonical component.
  • components/os/PermissionDenied.tsx — shared "permission denied + request access" state (J21) — reusable across Team tabs and elsewhere.

Reuse targets: MemoryApp's frame list for the Shared Memory tab (filtered to team scope via searchTeamMemory); CapabilitiesApp/AgentsApp/ScheduledJobsApp list rows for the Skills/Agents/MCPs/Automations tabs (read-only team-scoped views first). ContextMenu for row-level "Share to team".

New hook — hooks/useTeam.ts (mirror useWorkspaces shape): returns { team, members, activity, currentUserRole, createTeam, invite, changeRole, removeMember, refresh }. Drives RBAC at the UI layer (blueprint 162): compute currentUserRole from GET /api/teams/:id members + local userId, then hide/disable actions per PRD §17.2 capability matrix.

New adapter methods (add to lib/adapter.ts LocalAdapter, local /api/teams/* family — this is where new PRD §16 endpoints land per frontend inventory §c): getTeams, getTeam(id), createTeam, updateTeam, deleteTeam, inviteMember(id, {userId?, email?, displayName?, role?}), changeMemberRole(id, userId, role), removeMember(id, userId), getTeamAudit(id), and (for §16.11) shareToTeam(...).

State management (blueprint 511-514): Team Workspace re-fetches on the RBAC-change cache trigger + memory-import/artifact-update/automation-completion triggers. Use the existing QueryClient invalidation pattern.

5. Backend work (PRD §16.11)

PRD §16.11 endpoint Status Action
GET /api/teams/:id EXISTS team.ts:505 — returns team + members. Wire adapter getTeam. No backend change.
POST /api/teams/:id/invite PARTIAL → EXTEND Invite is implemented as POST /api/teams/:id/members (team.ts:581, owner/admin gated). Add a thin /invite alias that forwards to the members handler (PRD uses /invite; substrate is team_members in teams.db). No new substrate.
PATCH /api/teams/:id/members/:memberId EXISTS team.ts:642 (:userId == PRD :memberId); PUT variant at :615. Fix the PUT/PATCH role-gate inconsistency (PUT owner-only vs PATCH owner/admin — §9). Wire adapter changeMemberRole.
GET /api/teams/:id/audit PARTIAL → ALIAS Closest is GET /api/teams/:id/activity (team.ts:690, reads audit_events via events.js getAuditDb). Alias /audit → the activity handler (or add the audit-export shape). Substrate: audit_events table (events.ts). No new store.
POST /api/share MISSING → NET-NEW No /api/share route anywhere (grep-confirmed across local/routes). Sharing into team scope today is implicit (workspace teamId linkage at create + remote team-server frame sync). Net-new route accepting { kind: memory|artifact|skill|mcp|automation, id, scope: team|workspace|member, targetId }, role-checked (PRD §17.2 "Can share"), writing into the team scope and emitting an audit event (reuse emitAuditEvent, already used in team.ts:484). Touches: team_entities/team_resources (cloud, 02b) for the synced object, audit_events (local) for the trail. For solo/local mode, share = tag the frame/artifact with team scope (note the FE/DB scope is implicit per-.mind today — see §6 + substrate-types §c).

Implied additional route (not in §16.11, flag for plan): an install-audit / governance read route for the Skills/Agents/MCPs tabs. InstallAuditStore.getRecent/getByCapability exist in packages/core/src/install-audit.ts but have no HTTP endpoint (substrate-types §d). The Team Workspace governance view (who installed what / risk / trust / approval) needs e.g. GET /api/extend/audit or GET /api/teams/:id/governance surfacing team_capability_policies/ overrides/requests. The Enterprise proxy GET /api/team/governance/permissions (team.ts:418) is the only existing window and is read-only + ENTERPRISE-gated.

.mind migration: None required for the team CRUD/RBAC core — teams.db is a standalone SQLite file with its own DDL (created on demand). The Postgres team_capability_* tables already exist (migration 0001). The only schema-adjacent work is if team-scope sharing needs a structured scope/teamId on memory_frames (currently implicit per-.mind; substrate-types §c flags teamId/scope as MISSING columns) — that would be a metadata-column migration on memory_frames, deferrable behind the implicit-scope approach for v1.

6. Shared types needed (PRD §15 vs lib/types.ts)

  • No Team / TeamMember / TeamRole types exist in apps/web/src/lib/types.ts. Add them (frontend inventory §d confirms the types.ts export list has no team entities). Source of truth for the server shapes: team.ts TeamRole = 'owner'|'admin'|'member'|'viewer' (:21), MemberRow (team.ts:799-810 mapper).
  • RBAC role-union conflict — MUST be resolved before coding (decision needed, §9):
    • PRD §17.2 → Owner | Admin | Contributor | Viewer
    • Blueprint → Owner | Admin | Member | Viewer | Guest
    • Live teams.db CHECK → owner | admin | member | viewer Recommendation: keep the live 4-role union (owner/admin/member/viewer) for v1 to avoid a DB CHECK migration + RBAC-logic rewrite; treat PRD "Contributor" == "Member" and defer "Guest" as a follow-up (it needs a new role + new deny-by-default capability rules). Surface this to the founder per CLAUDE.md §3.1.
  • Scope union (personal/workspace/team/organization) — MISSING in FE types (substrate-types §e). Needed for ShareToTeamDialog. Add to lib/types.ts (PRD §15.2).
  • Capability/policy types for the governance tabs (team_capability_policies/overrides/ requests shapes from 02b) — add FE types when that read route lands.
  • Reuse existing TierCapabilities from @waggle/shared (tiers.ts) for the tier-gate; do not invent a parallel gate.

7. Dependencies (screens / phases first)

  • RBAC role-model decision (§6/§9) blocks the TeamRole type + all member-management UI — resolve first.
  • ShareToTeamDialog is cross-screen: it is invoked from S-Memory (J19) and S-Artifacts (J20). Artifacts have no backing entity at all (substrate-types §e — the single largest entity gap), so artifact-sharing depends on the Artifacts screen/entity landing first; memory- sharing can ship independently against memory_frames + searchTeamMemory.
  • Permission-denied / request-access pattern (J21) is shared with other screens — build the reusable PermissionDenied component here, reuse elsewhere.
  • Tier gating depends on useFeatureGate/LockedFeature (exist) — no new dependency.
  • The remote/cloud governance tabs (per-role capability policies) depend on the install-audit read route (§5 implied) which is itself a separate small backend task.

Phase placement: this is a later-phase screen. The foundational Work/Intelligence screens (Home, Workspace Desktop, Memory, Agents) and the Artifacts entity should land first; Team Workspace composes their list rows + shares into team scope.

8. Effort: L

The backend core is mostly EXISTS/PARTIAL (CRUD + RBAC enforcement + activity already live, only /invite alias + /audit alias + the genuinely net-new /api/share + a governance read route), but the frontend is a from-zero rework of a 45-line placeholder into an 8-tab surface with a new hook, ~8 new components, ~10 new adapter methods, UI-layer RBAC gating, the shared share/permission-denied components, and an unresolved role-model decision. Not XL because no new data store and no .mind migration is required for v1; not M because of the tab/share/RBAC breadth

  • cross-screen coupling.

9. Open questions

  1. RBAC role model (blocking): adopt PRD §17.2 (Owner/Admin/Contributor/Viewer), blueprint (+Member +Guest), or keep the live teams.db 4-role union (owner/admin/member/viewer)? Recommendation: keep live union for v1, map Contributor→Member, defer Guest. Needs founder sign-off.
  2. PUT vs PATCH role-gate inconsistency (real bug): PUT /api/teams/:id/members/:userId is owner-only (team.ts:624) but PATCH on the same path is owner/admin (:649). The PRD uses PATCH. Which gate is correct — owner-only role changes, or owner+admin? Align both.
  3. /api/share scope semantics in solo/local mode: memory frames have no structured scope/teamId column (implicit per-.mind, substrate-types §c). For v1, model team-share as (a) implicit via workspace teamId + remote sync, or (b) a memory_frames metadata migration? Recommendation: (a) for v1, defer (b).
  4. Local vs remote team source of truth on this screen: /api/teams/* (local teams.db, always works) vs /api/team/* (remote proxy, TEAMS-gated). Does Team Workspace render local teams in solo mode and switch to remote when connected, or remote-only? (Affects whether members/activity come from teams.db or the team server.)
  5. Governance tabs depth for v1: do the Skills/Agents/MCPs/Automations tabs render full per-role capability policies (team_capability_* cloud tables) now, or ship read-only shared-item lists first and defer the policy editor?
  6. Postgres no-cascade (02b:44): deleting a team is blocked by FKs if team_entities/resources/ members reference it. The local DELETE /api/teams/:id deletes members first (team.ts:563) — does the cloud delete path need an explicit child-cleanup order, and should the UI warn before delete?
Reference in New Issue View Git Blame Copy Permalink