@consciousclouds/operator-shell 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog — @consciousclouds/operator-shell
+
+Versioned on the independent frontend-SDK lifecycle (NOT `contract_version`).
+
+## [0.1.0] — 2026-07-04
+
+### Added
+
+- **Shell archetype** (Frontend Platform Layer 4): frame, header, sidebar rail,
+  permission-aware navigation (async resolvers + `RouteGuard`/`usePermission`,
+  fail-closed), first-class icon seam, command palette, inspector seam keyed by
+  entity kind, environment-switcher chrome over `frontend-runtime`.
+- **Workspace Framework**: the shell's main region is a workspace; workspace
+  types include canvas (hosted over the published `canvas-sdk` +
+  `canvas-runtime`), dashboard, table, form, and graph. Unknown workspace type
+  ⇒ unavailable state.
+- **AI Region** over `assistant-surface` with an injected `TurnAdapter`
+  (vocabulary = `conductor-sdk` event types + `conductor-react`
+  `NavigationDirective`); placement modes rail | drawer.
+- **Chief invocation parity** — the shell-owned ⌘J/Ctrl+J keybinding (the
+  palette's ⌘K twin): rail focuses the composer, drawer (declared or the
+  below-xl fallback) toggles through assistant-surface's open/close
+  lifecycle; shift/alt refuse the match (⌘⇧J stays the browser's). Exported:
+  `useChiefShortcut` · `isChiefShortcut` · `CHIEF_SHORTCUT_KEY` ·
+  `CHIEF_SHORTCUT_LABEL`.
+- **`OperatorFlavor`** consumed as inert data — zero functions/JSX, zero
+  transport URLs; everything executable is injected through shell props.
+
+### Notes
+
+- Consumes, never rebuilds, the published seams: assistant-surface,
+  canvas-sdk/runtime, conductor-sdk/react, frontend-runtime. No BFF routes,
+  gateway URLs, personality defaults, or credentials in package code.
+- Prepared-publishable per the assistant-surface packaging template. Publish
+  order at the gate: **conductor-sdk → conductor-react → operator-shell**, via
+  `bun publish` so `workspace:*` deps are rewritten to real versions.

package/LICENSE

@@ -0,0 +1,194 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship made available under
+      the License, as indicated by a copyright notice that is included in
+      or attached to the work (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean, as submitted to the Licensor for inclusion
+      in the Work by the copyright owner or by an individual or Legal Entity
+      authorized to submit on behalf of the copyright owner. For the purposes
+      of this definition, "submitted" means any form of electronic, verbal,
+      or written communication sent to the Licensor or its representatives,
+      including but not limited to communication on electronic mailing lists,
+      source code control systems, and issue tracking systems that are managed
+      by, or on behalf of, the Licensor for the purpose of discussing and
+      improving the Work, but excluding communication that is conspicuously
+      marked or designated in writing by the copyright owner as "Not a
+      Contribution."
+
+      "Contributor" shall mean Licensor and any Legal Entity on behalf of
+      whom a Contribution has been received by the Licensor and included
+      within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by the combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a cross-claim
+      or counterclaim in a lawsuit) alleging that the Work or any
+      Contribution embodied within the Work constitutes direct or contributory
+      patent infringement, then any patent licenses granted to You under
+      this License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative Works
+          a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works that
+          You distribute, all copyright, patent, trademark, and attribution
+          notices from the Source form of the Work, excluding those notices
+          that do not pertain to any part of the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, You must include a readable copy of the attribution
+          notices contained within such NOTICE file, in at least one of the
+          following places: within a NOTICE text provided as part of the
+          Derivative Works; within the Source form or documentation, if
+          provided along with the Derivative Works; or, within a display
+          generated by the Derivative Works, if and wherever such third-party
+          notices normally appear. The contents of the NOTICE file are for
+          informational purposes only and do not modify the License. You may
+          add Your own attribution notices within Derivative Works that You
+          distribute, alongside or in addition to the NOTICE text from the
+          Work, provided that such additional attribution notices cannot be
+          construed as modifying the License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work by
+      You to the Licensor shall be under the terms and conditions of this
+      License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any conditions of TITLE,
+      MERCHANTIBILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely
+      responsible for determining the appropriateness of using or
+      redistributing the Work and assume any risks associated with Your
+      exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a result
+      of this License or out of the use or inability to use the Work
+      (including but not limited to damages for loss of goodwill, work
+      stoppage, computer failure or malfunction, or all other commercial
+      damages or losses), even if such Contributor has been advised of the
+      possibility of such damages.
+
+   9. Accepting Warranty or Liability. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a fee
+      for, acceptance of support, warranty, indemnity, or other liability
+      obligations and/or rights consistent with this License. However, in
+      accepting such obligations, You may offer such obligations only on
+      Your own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend, and
+      hold each Contributor harmless for any liability incurred by, or
+      claims asserted against, such Contributor by reason of your accepting
+      any such warranty or additional liability.
+
+   Copyright 2024 Conscious Clouds
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+---
+
+Portions of this package are derived from shadcn/ui (https://ui.shadcn.com),
+Copyright (c) 2023 shadcn, licensed under the MIT License:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,319 @@
+# @consciousclouds/operator-shell
+
+The **ConsciousClouds Operator Shell** — the operator-console shell archetype,
+Layer 4 of the Frontend Platform.
+
+It ships the shared operator experience, composed from the **open MIT
+shadcn/ui registry** (sidebar-16's header-above-sidebar geometry, sidebar-07's
+icon-collapsible rail) over `@consciousclouds/ui` primitives:
+
+- **Frame** — `OperatorShell`: sticky full-width header, icon-collapsible
+  left sidebar (⌘B, mobile sheet), main content, and the AI Region
+  (Chief — invoked with **⌘J/Ctrl+J**, the palette's ⌘K twin).
+- **Header** — brand slot (rendered through the Brand Platform's
+  `BrandLogo` + `useBrand`; the shell never bakes an image or a mark string),
+  the search button that opens the command palette, notifications, theme
+  toggle (the Token System's `useTheme`), and a **profile slot** with a
+  neutral default menu.
+- **Command palette** — `CommandPalette` (mounted by the frame; ⌘K/Ctrl+K
+  and the header search button open the one instance; Chief's invocation
+  binding sits next to it — **⌘J/Ctrl+J**, see the Chief region) over the registry
+  `command`/cmdk vocabulary in `@consciousclouds/ui`. Commands are
+  **declarative**: route commands are auto-derived from `flavor.nav` (the
+  same tree the sidebar renders — no second route list), and optional
+  `flavor.commands` adds inert reference entries (id · label · icon name ·
+  `href` **or** a `command` reference — zero functions, Declarative-Flavor
+  law). Non-route execution is product-injected via the shell's `runCommand`
+  prop (the same injection pattern as icons and the resolver); a `command`
+  entry with no runner is hidden. Every entry passes the sidebar's
+  fail-closed permission gate (`derivePaletteGroups` is the pure, provable
+  derivation).
+- **Search sources** — the doctrine skeleton's **Search experience** as a
+  typed injection: the palette is also the search surface. The product
+  injects `SearchSource` values through the shell's `searchSources` prop
+  (**product code, never Flavor content** — a source's `query` is a function
+  running the product's own reads, so it cannot live in an inert Flavor; same
+  injection pattern as icons / the resolver / `inspectorViews` /
+  `runCommand`). Each source declares `id` · `label` (its palette group
+  heading) · optional `requiredPermission` · `query(text) →
+  Promise<SearchResult[]>`; results carry `label` / icon **name** / keywords
+  and a PaletteAction-shaped action — `navigate` (href) or `inspect` (open
+  the shell-owned inspector by entity kind with the ALREADY-RESOLVED entity;
+  the inspector's own fail-closed gate still applies). Sources gate through
+  the **same fail-closed permission snapshot** as the palette's commands —
+  a denied/unknown/still-resolving source is **never queried** — and an
+  erroring, in-flight, or absent source contributes **nothing** (never a
+  crash; siblings unaffected). `querySearchSources` + `useSearchResults` are
+  the pure/provable core. No transport enters this package: the wire behind
+  `query` is the product's own BFF.
+- **Nav engine** — reads an inert `OperatorFlavor`: groups → items with
+  **string icon names**, active-state (`/` exact, others by prefix), the
+  product-context block from `flavor.product`.
+- **Icon Platform** — the string-name → icon resolution seam. The Flavor
+  declares **inert string names** (`icon: "home"` — never a component,
+  Declarative-Flavor law); the shell ships the built-in operator vocabulary
+  (`OPERATOR_ICONS`: `home`, `bot`, `plug`, `activity`, `bar-chart-3`,
+  `waypoints`) and the product **extends** it through the `icons` shell prop
+  (`IconRegistry`: string name → Lucide component; extensions may
+  deliberately override built-ins). Unknown names **fail closed** to the
+  exported `UNKNOWN_ICON` — one deterministic neutral glyph for every
+  unresolved name (own-property lookup, so prototype names like `"toString"`
+  are unknown too; never a crash, never permission-bearing). The **icon
+  family** is a Brand-level declaration (`Brand.iconFamily`,
+  `@consciousclouds/brand` — inert data): the frame reads it and
+  `resolveIconFamily` read-and-defaults anything the shell doesn't ship to
+  `SHIPPED_ICON_FAMILY` (`lucide`, per the license allowlist — the only
+  family that ships today).
+- **Permission-guard seam** — the shell owns **fail-closed** gating; the
+  product injects a `PermissionResolver` (unknown ⇒ denied; the exported
+  `allowAllPermissions` is the explicit dev-open choice).
+- **Inspector** — the shell-owned detail panel: open/close/focus lifecycle
+  over the registry `sheet` primitive (Radix focus trap, Esc-to-close,
+  overlay dismiss), **keyed by entity kind**. The Flavor DECLARES the
+  entity-kind references (`flavor.inspector.entityKinds` — inert strings,
+  Declarative-Flavor law); the product INJECTS the detail views through the
+  shell's `inspectorViews` prop keyed by those references (components can't
+  live in a Flavor — same injection pattern as icons / the resolver /
+  `runCommand`). Pages open it via `useInspector().open({ kind, entity,
+  title?, description? })` with an ALREADY-RESOLVED entity — the shell never
+  fetches. Fail-closed twice over: an undeclared or view-less kind refuses to
+  open (`open` returns `false` — no panel, no crash;
+  `resolveInspectorView` is the pure, provable gate), and `useInspector`
+  outside a provider returns an inert API instead of throwing.
+- **Environment switcher** — `EnvironmentSwitcher` (mounted by the header):
+  environment chrome over the published `@consciousclouds/frontend-runtime`
+  context, **consumed as-is** (`RuntimeProvider` / `useRuntime` /
+  `resolveTarget` — never rebuilt). The PRODUCT mounts `RuntimeProvider` with
+  its targets — **target URLs and transport stay product code** (membrane:
+  this package ships no URL; it renders labels + a connection dot and hands
+  the runtime's own `NamedTarget` values back into `switchTo`). Fail-closed
+  and honest: no provider ⇒ no chrome; ONE configured environment ⇒ a
+  single-entry **indicator** (not a pretend menu); two or more named targets
+  ⇒ a dropdown switcher.
+- **Workspace-switcher seam** — typed + documented, **INERT until backend
+  PRE-1** (per-(project, environment) enrollment keying,
+  `docs/design/ccu-control-plane.md` §8 — the prerequisite for a second
+  workspace existing at all): the Flavor may declare
+  `workspaces?: OperatorFlavorWorkspace[]` (labels/refs only) and the shell
+  ships the `workspaceSwitcher` slot on `OperatorShellProps` (rendered in
+  the sidebar header). Products inject nothing today, the shell renders
+  nothing, and the static product block stays the whole context chrome — a
+  missing switcher beats a fake one.
+- **Workspace Framework** — the main-region seam (the charter's AI-native
+  correction: the shell's main region is a WORKSPACE, not a page body). A
+  deliberately **frame-free** subtree (`src/workspace/` imports nothing from
+  the shell frame — Separation Law: a later extraction is a photograph):
+  - **The vocabulary** — nine V1 type ids declared up front
+    (`WORKSPACE_TYPE_IDS`): `canvas` · `dashboard` · `table` · `form` ·
+    `graph` · `map` · `timeline` · `workflow` · `ai-session`. Later types are
+    additions, never surgery; `map`/`timeline`/`workflow`/`ai-session` are
+    typed seams that fail closed until an honest data source exists.
+  - **The registry** — `createWorkspaceRegistry([...])`: value-based and
+    immutable (no module-global state); the app composes shell built-ins +
+    product types ONCE; a duplicate id **throws** (composition-time error,
+    never a silent replacement).
+  - **The host** — `<WorkspaceHost registry typeId title? input>`: resolves
+    the type id (runtime data — any string accepted) and mounts the type's
+    component with the mount contract (`typeId` / `title` / opaque `input` —
+    the framework carries input, never interprets it). Unknown/unregistered
+    ids render the exported `WorkspaceUnavailable` state — fail-closed,
+    never a crash, never product content.
+  - **Built-in types** (each an exported `WorkspaceType` value +
+    component): `canvasWorkspaceType` — **Canvas is first-class**: hosting
+    state machine (error → loading → empty → ready) over the published
+    `@consciousclouds/canvas-runtime` `CanvasRenderer` (consumed, never
+    rebuilt; the product injects the `ComponentMap` + slot content);
+    `dashboardWorkspaceType` — StatCard grid + titled widget sections over
+    the graduated workspace components; `tableWorkspaceType` — hosts the
+    graduated `InteractiveDataTable`; `formWorkspaceType` — structured input
+    over the presentational Field vocabulary (validation judgment +
+    submission transport stay product-owned); `graphWorkspaceType` —
+    entity-relationship exploration over a typed nodes/edges contract,
+    rendered as adjacency-style traversal from registry primitives (no
+    viz dependency — react-flow/d3 sit outside the license allowlist;
+    dangling edge endpoints fail closed).
+  - **Registering a product workspace type** is data + a component, never
+    shell surgery: implement `WorkspaceType<TInput>` (`id` from the declared
+    vocabulary · `displayName` · optional `icon` by NAME · `Component`
+    receiving `WorkspaceComponentProps<TInput>`) and include it in your
+    `createWorkspaceRegistry` composition alongside the built-ins.
+- **Chief region** — the AI Region. `ChiefRegion` resolves
+  `flavor.chief.placement` (`rail` | `drawer`) to a presentation; BOTH run
+  the identical turn flow (`useChiefTurn` over the injected TurnAdapter) and
+  body (`ChiefSession`), mounted through the headless
+  `@consciousclouds/assistant-surface` hook. Turn lifecycle,
+  routed-directive handling (directive → href validated against routes
+  **derived from `flavor.nav`**), and streaming/routed/error states. Below
+  the xl breakpoint the rail placement falls back to the drawer — Chief
+  stays reachable. Placement moves the panel and NOTHING else (a Flavor can
+  move Chief's panel; it can never widen Chief's reach).
+  **Invocation parity — ⌘J/Ctrl+J** (the palette's ⌘K twin, shell-owned,
+  wired where the mounted presentation lives just as ⌘K lives with the
+  palette): on the **rail** it focuses the composer; on the **drawer**
+  (declared, or the rail's below-xl fallback) it toggles open/closed through
+  assistant-surface's one open/close lifecycle. Exactly one presentation
+  mounts at a time (single-surface rule), so exactly one listener is ever
+  attached. Shift/alt refuse the match — ⌘⇧J stays the browser's downloads
+  chord; no Flavor field is involved (placement remains the only Chief
+  decoration). `isChiefShortcut` is the exported pure match rule;
+  `CHIEF_SHORTCUT_LABEL` carries the display copy.
+
+**The shell owns the panel; the product owns the wire.** Transport is injected
+via a **TurnAdapter** typed against the published turn vocabulary
+(`ConductorEventName` / `ConductorEventDataMap` from
+`@consciousclouds/conductor-sdk`, `NavigationDirective` from
+`@consciousclouds/conductor-react`). No BFF route, gateway URL, personality
+default, or credential logic ever enters this package — enrollment and the
+verified actor authorize Chief, on the product's rail.
+
+## Adopting the shell — the second product's path
+
+A new product surface is **Brand + Flavor + pages + product BFF code**;
+everything else comes from the platform packages. From install to a rendered
+shell:
+
+**1. Install + styles.** Add `@consciousclouds/{tokens,ui,brand,operator-shell}`.
+Tailwind v4 does not scan `node_modules` — the app's Tailwind entry must
+register the platform sources:
+
+```css
+@import "tailwindcss";
+@import "@consciousclouds/tokens/styles/house.css";
+@import "@consciousclouds/ui/styles/source.css";
+@import "@consciousclouds/operator-shell/styles/source.css";
+```
+
+**2. Theme.** Mount tokens' `ThemeProvider` in the root layout (tokens is a
+runtime **peer** of this package — one theme context; the header's toggle
+reads it through tokens' `useTheme`).
+
+**3. Brand.** Declare your product's `Brand` (identity · logo renditions by
+role × mode · optional mode-aware `tokenOverrides` · `iconFamily`) as product
+data and mount `BrandProvider`. See `@consciousclouds/brand`'s README.
+
+**4. Flavor.** Write ONE inert `OperatorFlavor` per surface: the product
+block, nav groups (route strings + icon NAMES + optional permission
+references), `defaultLanding`, optional palette `commands` (references),
+`inspector.entityKinds` (references), and Chief decoration (placement/copy +
+an inert personality reference — never an endpoint).
+
+**5. The four injections.** Mount the shell from a **client component**
+(adapters/resolvers are functions — they cannot be serialized from a server
+layout):
+
+```tsx
+<ThemeProvider>            {/* @consciousclouds/tokens */}
+  <BrandProvider brand={MY_BRAND}>  {/* injection 1 — the product's Brand */}
+    <OperatorShell
+      flavor={MY_FLAVOR}            /* injection 2 — inert OperatorFlavor */
+      turnAdapter={myTurnAdapter}   /* injection 3 — product transport */
+      resolvePermission={myResolver}/* injection 4 — governance resolution */
+      icons={myIcons}               /* optional: icon-vocabulary extensions */
+      inspectorViews={myViews}      /* optional: views for declared entity kinds */
+      runCommand={myRunner}         /* optional: executes flavor command refs */
+      searchSources={mySources}     /* optional: ⌘K searchable sources */
+    >
+      {children}
+    </OperatorShell>
+  </BrandProvider>
+</ThemeProvider>
+```
+
+The **TurnAdapter** is product code wrapping YOUR transport (a same-origin
+BFF, `@consciousclouds/ai-client`, …), typed against the published vocabulary
+(`ConductorEventName`/`ConductorEventDataMap`, `NavigationDirective`) — never
+a parallel dialect. The **permission resolver** maps the Flavor's reference
+strings onto your governance rail (sync or async); unknown ⇒ denied, and
+`allowAllPermissions` is the explicit dev-open choice, never a default.
+
+**6. Pages as workspaces.** Compose your workspace registry once and mount
+pages through the host:
+
+```tsx
+const registry = createWorkspaceRegistry([
+  canvasWorkspaceType, dashboardWorkspaceType, tableWorkspaceType,
+  graphWorkspaceType, formWorkspaceType,
+  myProductWorkspaceType, // your own WorkspaceType, if any
+]);
+
+<WorkspaceHost registry={registry} typeId="canvas" title="Home" input={input} />
+```
+
+**7. Optional: searchable sources (the ⌘K Search experience).** Declare one
+`SearchSource` per searchable read as a **stable module const** in product
+code (never in the Flavor — `query` is a function) and inject the array
+through `searchSources`. A source's `query` receives the trimmed palette
+text and returns already-filtered results over reads YOUR side of the
+membrane holds (typically a same-origin BFF proxy of an existing read —
+never a new backend):
+
+```ts
+export const MY_SOURCES: SearchSource[] = [{
+  id: "personalities",
+  label: "Personalities",           // its palette group heading
+  // requiredPermission: "ai.read", // optional — same fail-closed gate as commands
+  query: async (text) => {
+    const read = await fetch("/api/search/personalities").then((r) => {
+      if (!r.ok) throw new Error("read failed"); // throwing ⇒ contributes nothing
+      return r.json();
+    });
+    return read.personalities
+      .filter((p) => p.name.toLowerCase().includes(text.toLowerCase()))
+      .map((p) => ({
+        id: p.id,
+        label: p.name,
+        icon: "bot",                // icon by NAME, through the registry
+        action: {                   // navigate by href, or open the inspector:
+          kind: "inspect", entityKind: "personality",
+          entity: p, title: p.name, description: p.id,
+        },
+      }));
+  },
+}];
+```
+
+An `inspect` action needs its entity kind declared in
+`flavor.inspector.entityKinds` **and** a view injected via `inspectorViews`
+— otherwise selecting the result fails closed (no panel, palette stays).
+
+**8. Optional chrome.** Mount `frontend-runtime`'s `RuntimeProvider` with
+your environment targets to light up the environment switcher; wire a
+favicon from your Brand's `favicon` role.
+
+The reference implementation of every step is CCU Admin
+(`platform/frontend/consciousclouds-admin/` — `app/operator-console.tsx`,
+`lib/{brand,flavor,turn-adapter,workspaces,search-sources}.ts`).
+
+## The membrane gates — what may never enter this package
+
+- **No transport meaning:** no BFF route, gateway URL, personality default,
+  or credential logic — enrollment + the verified actor authorize Chief, on
+  the product's rail (Chief-authority law). The Flavor decorates Chief; the
+  adapter carries the wire; governance authorizes.
+- **No product vocabulary:** nav trees, permission strings, entity kinds,
+  command references, workspace inputs are all injected references the
+  product implements.
+- **Declarative-Flavor law, review test verbatim:** *the Flavor file contains
+  zero functions/JSX and zero transport URLs.* Everything executable (icon
+  components, inspector views, command runners, adapters, resolvers) enters
+  through shell props instead.
+- **Fail-closed everywhere:** unknown permission ⇒ denied · unknown icon ⇒
+  `UNKNOWN_ICON` · unknown workspace type ⇒ `WorkspaceUnavailable` ·
+  undeclared/view-less inspector kind ⇒ refuses to open · runner-less
+  command ⇒ hidden · denied/erroring/in-flight search source ⇒ contributes
+  nothing.
+- **Consume, never rebuild:** assistant-surface, canvas-runtime,
+  conductor-sdk/react, frontend-runtime are published seams mounted as-is.
+
+## Dependency posture
+
+Runtime: `ui` · `brand` · `assistant-surface` · `conductor-sdk` /
+`conductor-react` (types + directive handling) · `frontend-runtime`
+(environment context — consumed, never rebuilt) · `canvas-runtime` /
+`canvas-sdk` (the canvas workspace type — consumed, never rebuilt) ·
+`lucide-react`. Peers: `react`, `next` (>=15 <17), and
+`@consciousclouds/tokens` — tokens is a peer (not a bundled dep) because
+theme state is token machinery: the app mounts tokens' `ThemeProvider`; the
+shell's theme toggle reads the same single instance through tokens'
+`useTheme`. Contracts: `docs/design/operator-platform-contracts.md`
+§2/§4/§5/§6. Platform overview: [`platform/frontend/README.md`](../README.md).

package/dist/chief/ChiefDrawer.d.ts

@@ -0,0 +1,11 @@
+import type { OperatorFlavor } from "../flavor/types.js";
+import type { TurnAdapter } from "./turn-adapter.js";
+export interface ChiefDrawerProps {
+    flavor: OperatorFlavor;
+    /** The product's transport (P1-1). The shell owns the panel, never the wire. */
+    adapter: TurnAdapter;
+    /** Extra classes on the floating trigger button. */
+    triggerClassName?: string;
+}
+export declare function ChiefDrawer({ flavor, adapter, triggerClassName }: ChiefDrawerProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ChiefDrawer.d.ts.map

package/dist/chief/ChiefDrawer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChiefDrawer.d.ts","sourceRoot":"","sources":["../../src/chief/ChiefDrawer.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,cAAc,CAAC;IACvB,gFAAgF;IAChF,OAAO,EAAE,WAAW,CAAC;IACrB,oDAAoD;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,gBAAgB,2CA0DlF"}

package/dist/chief/ChiefDrawer.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * ChiefDrawer — the AI Region's DRAWER placement: the same Chief content
+ * (useChiefTurn + ChiefSession, shared verbatim with the rail) mounted
+ * through the registry sheet primitive behind a floating trigger, with
+ * assistant-surface's open/close lifecycle driving the one open state.
+ *
+ * Division of behavior (no doubled handlers): useAssistantSurface owns the
+ * LIFECYCLE — the single-surface registration, open/close state semantics,
+ * trigger wiring (aria-haspopup/expanded), and focus restore to the trigger
+ * on close; the sheet primitive owns the modal PRESENTATION — portal,
+ * overlay, escape/outside-click dismissal, and focus containment — reporting
+ * every dismissal back through the same onOpenChange. The hook stays
+ * non-modal/non-dismissible so neither layer duplicates the other's job.
+ *
+ * The turn state lives OUTSIDE the sheet content (in this component), so
+ * closing and reopening the drawer keeps the thread — parity with the
+ * always-mounted rail. Transport is the injected TurnAdapter's — the shell
+ * never owns the wire (P1-1).
+ */
+import * as React from "react";
+import { Sparkles } from "lucide-react";
+import { useAssistantSurface } from "@consciousclouds/assistant-surface";
+import { Button, Sheet, SheetContent, SheetHeader, SheetTitle, cn } from "@consciousclouds/ui";
+import { ChiefSession } from "./ChiefSession.js";
+import { useChiefShortcut } from "./use-chief-shortcut.js";
+import { useChiefTurn } from "./use-chief-turn.js";
+export function ChiefDrawer({ flavor, adapter, triggerClassName }) {
+    const [open, setOpen] = React.useState(false);
+    const session = useChiefTurn({ flavor, adapter });
+    // The shell-owned Chief keybinding (⌘J / Ctrl+J — use-chief-shortcut.ts).
+    // Drawer invocation = toggle, through the SAME setOpen the
+    // assistant-surface lifecycle and the sheet's dismissals drive — one open
+    // state, whoever moves it.
+    useChiefShortcut(() => setOpen((o) => !o));
+    // Assistant-surface lifecycle (same surface id as the rail — one AI Region
+    // per application, whatever its placement). Defaults keep it non-modal and
+    // non-dismissible at the hook level: the sheet primitive supplies the
+    // modal presentation and reports dismissals through onOpenChange.
+    const surface = useAssistantSurface({
+        open,
+        onOpenChange: setOpen,
+        surfaceId: "operator-shell-chief",
+        "aria-label": session.title,
+    });
+    return (_jsxs(_Fragment, { children: [_jsxs(Button, { type: "button", ref: surface.triggerRef, ...surface.triggerProps, className: cn("fixed right-4 bottom-4 z-40 gap-2 rounded-full shadow-lg", triggerClassName), "aria-label": `Open ${session.title}`, children: [_jsx(Sparkles, { className: "size-4" }), session.title] }), _jsx(Sheet, { open: open, onOpenChange: setOpen, children: _jsx(SheetContent, { side: "right", "aria-describedby": undefined, className: "w-[340px] gap-0 sm:max-w-[340px]", children: _jsxs("div", { ref: surface.surfaceRef, ...surface.surfaceProps, className: "flex h-full min-h-0 flex-col", children: [_jsxs(SheetHeader, { className: "h-12 shrink-0 flex-row items-center gap-2 space-y-0 border-b border-border px-4 py-0", children: [_jsx("div", { className: "flex size-6 items-center justify-center rounded-md bg-primary/10 text-primary", children: _jsx(Sparkles, { className: "size-3.5" }) }), _jsx(SheetTitle, { className: "text-sm font-medium", children: session.title })] }), _jsx(ChiefSession, { session: session })] }) }) })] }));
+}
+//# sourceMappingURL=ChiefDrawer.js.map

package/dist/chief/ChiefDrawer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChiefDrawer.js","sourceRoot":"","sources":["../../src/chief/ChiefDrawer.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExC,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,EAAE,EAAE,MAAM,qBAAqB,CAAC;AAG/F,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAUnD,MAAM,UAAU,WAAW,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAoB;IACjF,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,MAAM,OAAO,GAAG,YAAY,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;IAElD,0EAA0E;IAC1E,2DAA2D;IAC3D,0EAA0E;IAC1E,2BAA2B;IAC3B,gBAAgB,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAE3C,2EAA2E;IAC3E,2EAA2E;IAC3E,sEAAsE;IACtE,kEAAkE;IAClE,MAAM,OAAO,GAAG,mBAAmB,CAAC;QAClC,IAAI;QACJ,YAAY,EAAE,OAAO;QACrB,SAAS,EAAE,sBAAsB;QACjC,YAAY,EAAE,OAAO,CAAC,KAAK;KAC5B,CAAC,CAAC;IAEH,OAAO,CACL,8BACE,MAAC,MAAM,IACL,IAAI,EAAC,QAAQ,EACb,GAAG,EAAE,OAAO,CAAC,UAAU,KACnB,OAAO,CAAC,YAAY,EACxB,SAAS,EAAE,EAAE,CAAC,0DAA0D,EAAE,gBAAgB,CAAC,gBAC/E,QAAQ,OAAO,CAAC,KAAK,EAAE,aAEnC,KAAC,QAAQ,IAAC,SAAS,EAAC,QAAQ,GAAG,EAC9B,OAAO,CAAC,KAAK,IACP,EAET,KAAC,KAAK,IAAC,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,YACtC,KAAC,YAAY,IACX,IAAI,EAAC,OAAO,sBACM,SAAS,EAC3B,SAAS,EAAC,kCAAkC,YAE5C,eACE,GAAG,EAAE,OAAO,CAAC,UAAU,KACnB,OAAO,CAAC,YAAY,EACxB,SAAS,EAAC,8BAA8B,aAExC,MAAC,WAAW,IAAC,SAAS,EAAC,sFAAsF,aAC3G,cAAK,SAAS,EAAC,+EAA+E,YAC5F,KAAC,QAAQ,IAAC,SAAS,EAAC,UAAU,GAAG,GAC7B,EACN,KAAC,UAAU,IAAC,SAAS,EAAC,qBAAqB,YAAE,OAAO,CAAC,KAAK,GAAc,IAC5D,EAEd,KAAC,YAAY,IAAC,OAAO,EAAE,OAAO,GAAI,IAC9B,GACO,GACT,IACP,CACJ,CAAC;AACJ,CAAC"}

package/dist/chief/ChiefPanel.d.ts

@@ -0,0 +1,10 @@
+import type { OperatorFlavor } from "../flavor/types.js";
+import type { TurnAdapter } from "./turn-adapter.js";
+export interface ChiefPanelProps {
+    flavor: OperatorFlavor;
+    /** The product's transport (P1-1). The shell owns the panel, never the wire. */
+    adapter: TurnAdapter;
+    className?: string;
+}
+export declare function ChiefPanel({ flavor, adapter, className }: ChiefPanelProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=ChiefPanel.d.ts.map

package/dist/chief/ChiefPanel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChiefPanel.d.ts","sourceRoot":"","sources":["../../src/chief/ChiefPanel.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAIrD,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,cAAc,CAAC;IACvB,gFAAgF;IAChF,OAAO,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,UAAU,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,eAAe,2CAqCzE"}