> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace admin: build navigation workspaces

> Create, edit, reorder, and disable navigation workspaces for your organization, or accept AI-recommended workspaces grounded in real usage.

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

<Steps>
  <Step title="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.</Step>
  <Step title="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.</Step>
  <Step title="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.</Step>
  <Step title="Save">Save the workspace. It appears in the sidebar switcher for every member of your org on their next load.</Step>
</Steps>

### 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.

```json theme={null}
{
  "workspace_key": "intake-coordinator",
  "label": "Intake coordinator",
  "description": "Front-door intake, screening, and admission queue.",
  "icon": "ClipboardList",
  "sections": [
    { "core": "clinical", "groupIds": ["intake", "assessments"] },
    { "core": "practice", "groupIds": ["scheduling", "verification"] }
  ],
  "enabled": true,
  "sort_order": 10,
  "origin": "custom"
}
```

## 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.

## Accept AI-recommended workspaces

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.

<Steps>
  <Step title="Generate proposals">Select **Suggest workspaces**. The call typically takes 5–15 seconds. Cost and token usage are logged.</Step>
  <Step title="Review and edit">Edit any field on a draft card — label, description, icon, or sections. Validation is the same as the manual builder.</Step>
  <Step title="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.</Step>
</Steps>

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.

## Related

<Columns cols={2}>
  <Card title="Navigation telemetry" icon="chart-line" href="/pf/navigation-telemetry">
    Org-scoped analytics over `nav_events`.
  </Card>

  <Card title="Settings hub" icon="gear" href="/pf/settings">
    Where the workspace builder is linked from.
  </Card>
</Columns>

<Note>
  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.
</Note>

<Accordion title="Documentation sources">
  * 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
</Accordion>