Skip to main content
The Workspace admin page lets org admins tailor the platform sidebar to how their team actually works. You can create custom workspaces, override the built-in defaults, and accept AI-recommended workspaces grounded in your org’s navigation telemetry.

​
Overview

Encore OS ships with a built-in registry of workspaces (Clinical, Practice Management, HR, and so on) that compose cores and nav groups for the sidebar workspace switcher. The workspace admin surface adds a per-org layer on top of those defaults:
  • Custom workspaces — net-new workspaces unique to your org.
  • Seed overrides — edits to a built-in workspace (label, icon, sections, sort order, enabled state). The override only affects your organization.
  • AI-accepted workspaces — proposals generated from your org’s anonymized navigation telemetry, reviewed and accepted by an admin.
All three flavors persist to the nav_workspace_definitions table, are merged with the built-in registry at load time, and appear in the sidebar workspace switcher for every member of your org.

​
Who it’s for

Required permission: system.organizations.admin. Members without org-admin continue to use whatever workspaces the merged registry produces; they cannot reach the builder page.

​
Before you start

  • You must hold system.organizations.admin for the active organization.
  • Navigation telemetry (nav_events) must be enabled. It is on by default and PHI-safe — it records only route templates and event types, never patient or record IDs.
  • AI-recommended workspaces additionally require that the AI gateway is enabled for your tenant. Cost is logged to pf_ai_usage_logs under the navigation module.

​
Open the builder

  1. Go to Settings (/settings).
  2. Under Navigation & workspaces, select Workspace builder.
  3. The page lists every workspace currently active for your org, with its origin badge: built-in, seed-override, custom, or ai-accepted.

​
Create a custom workspace

1

Start a new workspace

Select New workspace. Give it a stable workspace_key (used in /workspace/:key), a display label, an optional description, and an icon from the allow-listed Lucide icon picker.
2

Compose sections

Add one or more sections. For each section, pick a core and the nav groups that should appear under it. The picker is validated against the live core and group registry — invalid selections are rejected.
3

Set sort order and enabled state

Lower sort_order values appear earlier in the sidebar switcher. Disable a workspace to hide it without deleting it.
4

Save

Save the workspace. It appears in the sidebar switcher for every member of your org on their next load.

​
Example workspace definition

A workspace is stored as a row with a sections JSON array. The same shape is used for custom workspaces and seed overrides.

​
Override a built-in workspace

Edit any built-in workspace from the list. Saving the change creates a seed-override row scoped to your organization — the underlying default is untouched, and other orgs are unaffected. To revert, delete the override; the built-in workspace returns automatically. Disabling a built-in workspace hides it from the sidebar switcher for your org. Members previously on a disabled workspace fall back to the next enabled workspace. The Suggest workspaces button runs the suggest-workspaces edge function on demand. It aggregates the last 30 days of nav_events for your org into route-template counts and cross-core co-navigation pairs, sends those aggregates plus the static core and group vocabulary to the AI gateway, and returns a structured set of proposed workspaces. What the AI never sees:
  • Individual nav_events rows
  • User IDs
  • Any patient, record, or PHI identifier
  • Cores or group IDs that are not in the live registry (hallucinated values are stripped before persistence)
Each proposal is persisted to nav_workspace_recommendations with status proposed and renders as an editable draft card showing the proposed label, description, icon, composed sections, and the AI’s rationale.
1

Generate proposals

Select Suggest workspaces. The call typically takes 5–15 seconds. Cost and token usage are logged.
2

Review and edit

Edit any field on a draft card — label, description, icon, or sections. Validation is the same as the manual builder.
3

Accept or dismiss

Accept writes a nav_workspace_definitions row with origin='ai-accepted' and source_recommendation_id set, and marks the recommendation accepted. Dismiss marks the recommendation dismissed without creating a workspace. Both actions are auditable.
Recommendations are never auto-applied — accepting one is always an explicit admin action.

​
Key concepts

Workspace key — Stable identifier used in /workspace/:key and the merged registry. Must be unique within your org. Changing it after creation breaks any bookmarks or saved links. Sections — A workspace is an ordered list of { core, groupIds[] }. Cores correspond to the platform’s top-level domains (clinical, practice, hr, and so on); group IDs are the registered nav groups within each core. Origin — Tracks how a workspace row was created: seed-override for edits to a built-in, custom for net-new, ai-accepted for AI suggestions an admin accepted. The origin badge is shown on each row. Merged registry — useAllWorkspaces() merges the built-in WORKSPACE_REGISTRY with your org’s DB rows by workspace_key. DB rows win on conflicts; disabled rows hide the matching built-in. The sidebar switcher and getWorkspace() both read from the merged source.

Navigation telemetry

Org-scoped analytics over nav_events.

Settings hub

Where the workspace builder is linked from.
This page documents shipped product behavior. It is not medical, legal, or billing advice. Verify against your organization’s policies and applicable regulations before using it for clinical, compliance, or billing decisions. Protected health information (PHI) shown in the product is governed by your tenant’s access controls and is never exposed in this documentation.
  • src/platform/navigation/workspaces/WorkspaceHubPage.tsx
  • src/platform/navigation/workspaces/admin/WorkspaceBuilderPage.tsx
  • src/platform/navigation/workspaces/admin/WorkspaceForm.tsx
  • src/platform/navigation/workspaces/admin/SuggestedWorkspaceCard.tsx
  • src/platform/navigation/workspaces/admin/useWorkspaceMutations.ts
  • src/platform/navigation/workspaces/admin/useWorkspaceRecommendations.ts
  • src/platform/navigation/workspaces/workspace-registry.ts
  • src/platform/navigation/workspaces/resolveWorkspaceNav.ts
  • supabase/functions/suggest-workspaces/index.ts