Custom Workspaces

## Overview

A **custom workspace** is a tenant-defined workspace whose entire route tree, nav, and data-fetching shape lives inside the tenant module (or in DB rows installed via the bundle pipeline). The platform renders it through three existing primitives:

- `customPageRegistry` — code-resident page renderers keyed by `<workspaceSlug>/<pageSlug>`
- `custom_pages` — workspace-scoped per-route rows in the DB (4-tier scope resolver)
- `EntityDataSource` — the same named data-source mechanism used by blocks and views

No per-tenant code in `app/(app)/`. No new platform routes. One `TenantModule.workspaces` declaration installs a complete multi-page surface.

The **DOC360 Clinic** (`features/custom/tenants/docs/clinic/workspace.ts`) is the canonical reference: four surfaces (Floor, Daily Wrap, Protocol Board, Mobile Floor) reachable at `/t/docs/w/clinic/p/{floor,wrap,board,mobile}`.

The **OCI AI Retainer Command Center**
(`features/custom/tenants/oci/command-center/workspace.ts`) is the reference
for client-retainer modules: five protected workspace pages reachable at
`/t/oci/w/command-center/p/{portfolio,process,opportunity,loop,weekly}`. It
uses code-resident fixtures today and keeps every product-specific component
under the OCI tenant module.

## The pattern in 30 seconds

```
TenantModule.workspaces
  └─ registerWorkspaceModule (boot-time)
       ├─ customPageRegistry entries (keyed "clinic/floor", etc.)
       │    └─ matches: src => src.workspaceSlug === "clinic" && src.tenantSlug === "docs"
       └─ BundleManifest (workspace + custom_pages + workspace_nav_overlay sections)

installWorkspaceFromTemplate("docs/clinic") ──►  DB rows
  ├─ workspaces row (slug="clinic", tenant_id=<docs-uuid>)
  ├─ custom_pages rows (slug="floor", "daily-wrap", "mobile", "board")
  └─ workspace nav overlay

Request: /t/docs/w/clinic/p/floor
  └─ app/(app)/p/[[...slug]]/page.tsx (catchall)
       ├─ getCustomPageBySlug("floor")  →  custom_pages row
       ├─ getCustomPageRendererEntry(page)  →  registry entry
       ├─ resolveCustomPageDataSources(page, entry, ctx)  →  ResolvedDataSources
       └─ <ClinicFloorSurface page={page} data={data} />
```

## Authoring a custom workspace

Create a `workspace.ts` file under `features/custom/tenants/<tenant>/` and use the provided helpers:

```ts
// features/custom/tenants/acme/clinic/workspace.ts
import { defineCustomWorkspace } from "../../lib/define-custom-workspace";
import type { PageModule } from "@/features/custom/lib/tenant-module";
import { AcmeFloorSurface } from "./surfaces/floor";
import { getAcmeDataSource } from "./data-sources";

const floorPage: PageModule = {
  title: "Floor",
  component: AcmeFloorSurface as unknown as PageModule["component"],
  layout: "wide",
  dataSourcesSchema: floorDataSourcesSchema,
  // Factory: ctx.nowISO is the REQUEST date, not server boot date.
  dataSources: (ctx) => ({
    todaysItems: getAcmeDataSource({ name: "todays-items", dateISO: ctx.nowISO }),
    activePatients: getAcmeDataSource({ name: "active-patients" }), // time-independent
  }),
};

export const acmeClinicWorkspace = defineCustomWorkspace({
  slug: "clinic",
  title: "ACME Clinic",
  description: "Daily clinical ops for ACME coaches",
  nav: [
    { slug: "floor", label: "Floor", icon: "activity", path: "/p/floor", order: 10 },
  ],
  pages: { floor: floorPage },
});
```

Wire it into the tenant module:

```ts
// features/custom/tenants/acme/index.ts
export const acmeTenantModule: TenantModule = {
  tenantSlug: "acme",
  entityTypes: { ... },
  workspaces: { clinic: acmeClinicWorkspace },
};
```

At boot, `registerWorkspaceModule` processes each entry in `workspaces` and populates the registry + manifest store. Call `installWorkspaceFromTemplate("acme/clinic")` during tenant provisioning to write the DB rows.

## AI Retainer command-center pattern

Use this shape when a tenant needs a weekly retainer review cockpit rather than
a generic workspace:

| Page | Purpose |
|------|---------|
| `portfolio` | AI opportunity portfolio, value proof, SOP coverage, human decisions, and agent work in flight |
| `process` | Process map with living SOP extraction, lineage, owner, and pending agent drafts |
| `opportunity` | Ranked AI opportunities with scoring dimensions, required records, gates, and next actions |
| `loop` | Live agent loop health, trace, lessons, metrics, and promotion evidence |
| `weekly` | Client-ready summary of proof, deliverables, asks/decisions, and next-cycle goals |

Boundary rules:

- Product-specific UI and seed fixtures stay under
  `features/custom/tenants/<slug>/command-center`.
- The tenant module owns `workspaces: { "command-center": workspace }` and
  spreads the workspace page entries into `TenantModule.pages`.
- Page `source` metadata must include the tenant slug, workspace slug, and a
  tenant-module renderer key such as
  `tenant-module:oci:command-center:weekly`.
- Do not move helpers into `features/custom/lib/` until at least two tenants
  consume the same type or component contract.
- Live data should enter through page-local `dataSources` factories only after
  the tenant's entity graph exists. Do not persist `dataSources` into
  `custom_pages.source`.

Adoption notes:

- **Marbella:** the shared `command-center` workspace IS Marbella's operating
  surface — its pages read from Marbella's automation queue, SOP library,
  reporting pack, and the canonical entity graph (workstreams / SOPs / tasks).
  The old seed-driven operating-partner cockpit (`/p/operating-partner`) was
  retired; the only remaining Marbella-specific custom page is the
  tenant-root `context-engine` page. Only extract shared helpers after Marbella
  and OCI have the same weekly-goal or proof-summary shape.
- **IMS/Nathan:** start with `portfolio`, `process`, and `weekly` pages backed
  by IMS visualizer/product-catalog records and Nathan retainer decision asks.
  Add `opportunity` and `loop` once the first repeatable agent loop is seeded.

## Authoring a page module

Each page in `WorkspaceModule.pages` is a `PageModule`. The key fields:

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `title` | `string` | yes | Display name |
| `component` | `CustomPageRenderer` | yes | React component; `"use client"` for interactive surfaces |
| `layout` | `"default" \| "wide"` | no | Defaults to `"default"` |
| `dataSources` | `DataSourcesFactory<TSources>` | no | Factory or static value; omit for pages with no data |
| `dataSourcesSchema` | `z.ZodType<DataSourceShape>` | no | Required when `dataSources` is provided |
| `permission` | `AppPermission` | no | Reserved — defaults to workspace membership in v1 |

### `dataSources` as a factory

When any source depends on the current date, user, or workspace slug, use the factory form:

```ts
dataSources: (ctx: PageRequestContext) => ({
  todaysVisits: getClinicDataSource({
    name: "todays-visits",
    dateISO: ctx.nowISO,   // request-time date — never server boot time
  }),
}),
```

`PageRequestContext` carries `{ nowISO, tenantSlug, workspaceSlug, userId }`. The resolver calls the factory at SSR time. Time-independent sources may be a static literal but are conventionally placed inside the factory alongside date-dependent peers for visual consistency.

### Component props

Surfaces receive `{ page: CustomPage; data?: ResolvedDataSources<TSources> }`. The `data` prop is **optional** — surfaces that do not use named data sources omit it. `ResolvedDataSources<TSources>` maps each key to `{ entities, total, relationColumnDefs, entityType }`.

```tsx
// features/custom/tenants/docs/clinic/surfaces/floor.tsx
"use client";

type FloorSources = {
  todaysVisits: EntityDataSource;
  awaitingReview: EntityDataSource;
};

export function ClinicFloorSurface({
  page,
  data,
}: {
  page: CustomPage;
  data?: ResolvedDataSources<FloorSources>;
}) {
  const visits = data?.todaysVisits?.entities ?? [];
  // ... render
}
```

Read entity field values via `createEntityFieldReader(entity, data.todaysVisits.entityType)` when schema validation is needed.

## How it renders

```
GET /t/docs/w/clinic/p/floor
  │
  ├─ Middleware: sets x-tenant-slug=docs, x-workspace-slug=clinic
  │    └─ PostgREST hook: validates membership, pins app.workspace_id GUC
  │
  └─ app/(app)/p/[[...slug]]/page.tsx
       │  params.slug = ["floor"]
       │  joinedSlug  = "floor"
       │
       ├─ getCustomPageBySlug("floor")
       │    └─ custom_pages row  (workspace_id = <clinic-uuid>, tenant_id = <docs-uuid>)
       │
       ├─ Workspace-presence guard: page.workspaceId ≠ null && getActiveWorkspaceSlug() ≠ null
       │    └─ no workspace in URL → notFound()
       │
       ├─ getCustomPageRendererEntry(page)
       │    └─ customPageRegistry lookup: matches src.workspaceSlug + src.tenantSlug + src.renderer
       │
       ├─ resolveCustomPageDataSources(page, entry, await buildPageContext())
       │    ├─ dataSources factory called with { nowISO, tenantSlug, workspaceSlug, userId }
       │    └─ executeEntityDataSourceQuery() per named source, in parallel
       │
       └─ return <ClinicFloorSurface page={page} data={resolvedData} />
            └─ Server Component renders the JSX subtree;
               "use client" surface boundary handled by Next.js serialization
```

Multi-segment paths (`/p/patients/intake/step-1`) work transparently — `params.slug` becomes `["patients", "intake", "step-1"]`, joined to `"patients/intake/step-1"`, and matched against `custom_pages.slug`. `SlugPath` validation enforces lowercase segments separated by `/` with no leading or trailing slash.

## For agents

Agents have two authoring paths for custom workspaces:

### Code-resident (compile-time)

Use when the workspace logic requires TypeScript type safety, server-only data utilities, or tightly-typed `ResolvedDataSources` props.

1. Author a `workspace.ts` in the tenant module folder.
2. Add it to `TenantModule.workspaces`.
3. Run `installWorkspaceFromTemplate("<tenant>/<workspace>")` to seed DB rows.

This is the standard path for first-party tenant modules.

### DB-resident (agent vibe-coded)

Use when authoring a one-off dashboard or insight surface without a code deployment:

```ts
// Agent calls manageBundle with a custom_pages section
await manageBundleAction({
  manifest: {
    workspaces: [{ slug: "my-dash", title: "My Dashboard", ... }],
    custom_pages: [
      {
        slug: "my-dash/overview",
        title: "Overview",
        runtime: "module",           // uses a compiled artifact
        source: {
          renderer: "artifact:<artifactId>",
          workspaceSlug: "my-dash",
          tenantSlug: "acme",
        },
        install_scope: "workspace",
      },
    ],
  },
});
```

DB-resident pages use `runtime: "module"` and reference a compiled artifact via `manageComponent`. Named data sources (`dataSources`) are NOT supported for DB-resident pages in v1 — module-kind components fetch their own data inside the iframe via `useAction("refreshData")`.

### Available tools

| Tool | Action |
|------|--------|
| `installWorkspaceFromTemplate` | Idempotent install of a code-resident workspace manifest |
| `manageBundle` | Install/update DB-resident workspace rows (custom_pages, workspace sections) |
| `manageComponent` (compile action) | Compile + publish a TSX surface for a `runtime: "module"` page |

## Design decisions

### Why bare slug in the DB, not `<workspace>/<slug>`

The `matches` predicate on the registry entry gates by `source.workspaceSlug` and `source.tenantSlug`, so a `slug = "floor"` row in workspace A cannot match the renderer registered for workspace B. The DB slug is the path segment the catchall receives (`"floor"`), not a composite key. This means `getCustomPageBySlug("floor")` returns the workspace-scoped row when the active workspace GUC is set — the 4-tier resolver handles workspace > tenant precedence automatically.

If the slug were `"clinic/floor"` in the DB, the URL would have to be `/p/clinic/floor` (the workspace is already in the URL as `/w/clinic/`). One extra redundant segment per page is not acceptable.

### Why `dataSources` is a factory

A static module-level object captures values at server boot, not at request time. `nowISO: todayISO()` evaluated at boot is correct for the first request of the day, then stale for every request thereafter. The factory pattern — `(ctx) => ({ todaysVisits: getSource({ dateISO: ctx.nowISO }) })` — is evaluated per-request. The resolver detects `typeof dataSources === "function"` and calls it with the live `PageRequestContext`. The cost is one function call per page load; the benefit is always-correct data for date-sensitive queries.

### Why `source.dataSources` is stripped on install

`dataSources` is a TypeScript value — it may be a function, a Zod-inferred type, or a closure. None of these serialize to JSON. Even if the static form were serializable, writing it to the DB creates a second source of truth that drifts from the code. The invariant is: code owns configuration, DB owns identity (tenant, workspace, slug, renderer key). The strip happens at two layers — the TS `installBundle` wrapper removes `source.dataSources` before the INSERT, and `install_bundle()` SQL function never reads it.


## Reference implementation — Structure Map

The **Structure Map** (`features/custom/workspaces/structure-map/`) is the canonical reference for a code-defined workspace that ships its own entity types, seeds, server actions, and a fully interactive canvas — all as a single installable unit.

### What it is

An Orca-style interactive ownership chart for family offices. It visualizes the full beneficial ownership and governance structure of a family group: natural persons, holding entities, and asset positions, connected by ownership edges (with % interest) and role edges (trustee, settlor, director, etc.).

### Atlas data model

Three entity types drive the chart:

| Entity type | Represents |
|---|---|
| `atlas-person` | Natural person (beneficial owner, trustee, officer) |
| `atlas-entity` | Legal entity (trust, LLC, LP, company, foundation) |
| `atlas-asset` | Asset position (real estate, investment, bank account) |

Edges are stored in `entity_relations`:

- **Ownership edge** — `relationship_type: "owns"`, `metadata: { ownershipPct, ownershipKind, shareCount, shareClass, since }`
- **Role edge** — `relationship_type: "role:<role>"` where `<role>` is one of `trustee | settlor | protector | beneficiary | director | officer | manager | member | advisor`

Server-side invariants (`lib/atlas-invariants.ts`) enforce structural correctness at write time: no self-links, assets cannot own, people cannot be owned, roles are person→entity only, duplicate and ownership-cycle detection.

### Canvas components

The workspace ships a `@xyflow/react` canvas with:

- Dagre top-down layout with collapsible subtrees (hidden-count badge)
- Orthogonal ownership edges with circular %-pill labels; dashed role edges
- Re-root ("view from here"), node picker, search + kind/role filters
- Detail rail — fields, holdings with %, roles, valuation roll-ups, and **effective (look-through) ownership** for indirect holders
- **"As of" point-in-time toolbar control** — filters the chart to edges in effect on a chosen date
- Sentence-builder add bar — natural-language quick-add with inline node picker
- PNG export via `components/lib/export-png.ts`

### Effective (look-through) ownership

`computeEffectiveOwnership` (`components/lib/atlas-effective-ownership.ts`) computes each upstream holder's true economic interest in a selected record by walking the ownership graph upward from the target. For each distinct directed path the fraction is the product of the per-edge ownership percentages; contributions from multiple paths to the same holder are summed.

```
Trust → 70% → Holdings → 85% → OpCo
  effective ownership of OpCo by Trust = 0.70 × 0.85 = 59.5%
```

The detail rail surfaces this section only for indirect holders (chains of 2 or more edges). Direct ownership is already visible on the chart edge itself. When any edge on a contributing path has a missing or invalid `ownershipPct`, the holder is flagged `incomplete: true` and the figure is annotated — the implementation never silently understates a holding.

Key types:

```ts
interface EffectiveOwner {
  holderId: string;
  pct: number;        // 0–100
  incomplete: boolean; // true when a contributing path crossed an invalid edge
  minDepth: number;   // 1 = direct, 2+ = indirect
}
```

Cycle-safe: a path-local visited set prevents the walker from re-entering any node already on the current path.

### "As of" point-in-time filter

`filterGraphAsOf` (`components/lib/atlas-as-of.ts`) accepts an ISO date string and returns a new graph containing only edges in effect on that date. Nodes are never removed — only edges.

| Edge kind | Exclusion rule |
|-----------|----------------|
| `owns` | excluded when `startDate` (the "since" date) is **after** the cutoff |
| role | excluded when `startDate > cutoff` (not yet started) **or** `endDate < cutoff` (already ended) |

Edges without the relevant date field are kept — absence of a date means the edge cannot be proved absent. An unparseable cutoff string returns the original graph unchanged.

The toolbar control renders as a clearable date badge and composes downstream with re-root, collapse, and kind filters. Dagre re-runs the layout against the filtered edge set so the chart correctly reflects the point-in-time structure.

### Installing on a tenant

```bash
# During tenant provisioning or via agent tool:
installWorkspaceFromTemplate("marbella/structure-map")
```

This is idempotent — re-running skips already-installed rows. The marbella seed ships 13 nodes and 16 edges as a worked example.

### Authoring pattern

Structure Map follows the same four-file pattern as the DOC360 Clinic:

```
features/custom/workspaces/structure-map/
  manifest.ts      ← BundleManifest (entity types + seeds)
  workspace.ts     ← WorkspaceModule (pages, nav)
  types.ts         ← shared TypeScript types (AtlasNode, AtlasEdge, AtlasGraph)
  seeds.ts         ← marbella demo seed (13 nodes, 16 edges)
  register.ts      ← registers workspace + bundle at boot
  server/
    atlas-data.ts  ← fetchAtlasGraph (use server, tenant-scoped)
    atlas-actions.ts ← createAtlasPerson, createOwnershipEdge, etc.
  components/      ← canvas, toolbar, detail-rail, node-picker, etc.
  pages/
    structure-map.tsx ← client-slot page component (React Query)
```

The page is a **client slot** (not a server component): `fetchAtlasGraph` is a `"use server"` action, so the page fetches via the client slot registry and React Query to support optimistic mutations.

## Related modules

- `content/docs/features/workspaces.mdx` — workspace mechanics, URL-as-truth, `workspace_memberships`, scope resolver
- `content/docs/features/custom-pages.mdx` — `custom_pages` table, 4-tier resolver, `customPageRegistry`, `EntityDataSource`
- `content/docs/features/bundles.mdx` — `BundleManifest` schema, `installBundle`, pgTAP auth boundary
- `content/docs/features/agent-system.mdx` — agent authoring tools including `manageComponent` and `manageBundle`
- `.claude/rules/custom-workspaces.md` — invariants, anti-patterns, PR regression checklist
- `.claude/rules/tenant-modules.md` — general tenant module authoring rules