fix(assets): remove semi-white background artifacts from logo SVG and PNGs

Stripped 8 near-white path layers (brightness > 200) from the traced SVG, leaving only amber/gold tones. Regenerated all PNG variants from the cleaned SVG. Validated on dark and red backgrounds with zero artifacts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
feat(assets): add high-detail cameleer3-logo.svg traced from PNG via Inkscape
2026-04-06 23:19:39 +02:00 · 2026-04-06 22:58:44 +02:00 · 2026-04-06 22:43:01 +02:00 · 2026-04-06 22:14:50 +02:00 · 2026-04-06 17:17:36 +02:00 · 2026-04-04 15:59:00 +02:00
46 changed files with 3933 additions and 1218 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -40,6 +40,10 @@ import { Button, Input } from '../design-system/primitives'
 import { Modal, DataTable, KpiStrip, SplitPane, EntityList, LogViewer } from '../design-system/composites'
 import type { Column, KpiItem, LogEntry } from '../design-system/composites'
 import { AppShell } from '../design-system/layout/AppShell'
+import { Sidebar } from '../design-system/layout/Sidebar/Sidebar'
+import { SidebarTree } from '../design-system/layout/Sidebar/SidebarTree'
+import type { SidebarTreeNode } from '../design-system/layout/Sidebar/SidebarTree'
+import { useStarred } from '../design-system/layout/Sidebar/useStarred'
 import { ThemeProvider } from '../design-system/providers/ThemeProvider'
 ```

@@ -93,6 +97,10 @@ import { Button, AppShell, ThemeProvider } from '@cameleer/design-system'
 // All components from single entry
 import { Button, Input, Modal, DataTable, KpiStrip, SplitPane, EntityList, LogViewer, StatusText, AppShell } from '@cameleer/design-system'

+// Sidebar (compound component — compose your own navigation)
+import { Sidebar, SidebarTree, useStarred } from '@cameleer/design-system'
+import type { SidebarTreeNode } from '@cameleer/design-system'
+
 // Types
 import type { Column, DataTableProps, SearchResult, KpiItem, LogEntry } from '@cameleer/design-system'

@@ -110,4 +118,13 @@ import type { ChartSeries, DataPoint } from '@cameleer/design-system'

 // Styles (once, at app root)
 import '@cameleer/design-system/style.css'
+
+// Brand assets (static files via ./assets/* export)
+import logo from '@cameleer/design-system/assets/cameleer3-logo.png'     // full resolution
+import logo32 from '@cameleer/design-system/assets/cameleer3-32.png'     // 32×32 favicon
+import logo180 from '@cameleer/design-system/assets/cameleer3-180.png'   // Apple touch icon
+import logo192 from '@cameleer/design-system/assets/cameleer3-192.png'   // Android/PWA icon
+import logo512 from '@cameleer/design-system/assets/cameleer3-512.png'   // PWA splash, og:image
+import logoSvg from '@cameleer/design-system/assets/cameleer3-logo.svg'   // high-detail SVG logo
+import camelSvg from '@cameleer/design-system/assets/camel-logo.svg'     // simplified camel SVG
 ```
--- a/COMPONENT_GUIDE.md
+++ b/COMPONENT_GUIDE.md
@@ -38,10 +38,12 @@
 - Removable label → **Tag**

 ### "I need navigation"
- App-level sidebar nav → **Sidebar** (via AppShell) — hierarchical trees with starring
+- App-level sidebar nav → **Sidebar** (compound component — compose sections, trees, footer links)
+- Sidebar tree section → **SidebarTree** (data-driven tree with expand/collapse, starring, keyboard nav)
+- Starred items persistence → **useStarred** hook (localStorage-backed)
 - Breadcrumb trail → **Breadcrumb**
 - Paginated data → **Pagination** (standalone) or **DataTable** (built-in pagination)
- Hierarchical tree navigation → **TreeView** (generic) or **SidebarTree** (sidebar-specific, internal)
+- Hierarchical tree navigation → **TreeView** (generic)

 ### "I need floating content"
 - Tooltip on hover → **Tooltip**
@@ -99,7 +101,24 @@

 ### Standard page layout
 ```
-AppShell → Sidebar + TopBar + main content + optional DetailPanel
+AppShell → Sidebar (compound) + TopBar + main content + optional DetailPanel
+
+Sidebar compound API:
+  <Sidebar collapsed={bool} onCollapseToggle={fn} searchValue={str} onSearchChange={fn}>
+    <Sidebar.Header logo={node} title="str" version="str" />
+    <Sidebar.Section label="str" icon={node} open={bool} onToggle={fn} active={bool}>
+      <SidebarTree nodes={[...]} selectedPath="..." filterQuery="..." ... />
+    </Sidebar.Section>
+    <Sidebar.Footer>
+      <Sidebar.FooterLink icon={node} label="str" onClick={fn} active={bool} />
+    </Sidebar.Footer>
+  </Sidebar>
+
+Notes:
+- Search input auto-renders between Header and first Section (not above Header)
+- Section headers have no chevron — the entire row is clickable to toggle
+- The app controls all content — sections, order, tree data, collapse state
+- Sidebar provides the frame, search input, and icon-rail collapse mode
 ```

 ### Data page pattern
@@ -227,7 +246,7 @@ import {
 | Checkbox | primitive | Boolean input with label |
 | CodeBlock | primitive | Syntax-highlighted code/JSON display |
 | Collapsible | primitive | Single expand/collapse section |
-| CommandPalette | composite | Full-screen search and command interface |
+| CommandPalette | composite | Full-screen search and command interface. `SearchCategory` is an open `string` type — known categories (application, exchange, attribute, route, agent) have built-in labels; custom categories render with title-cased labels and appear as dynamic tabs. |
 | ConfirmDialog | composite | Type-to-confirm destructive action dialog built on Modal. Props: open, onClose, onConfirm, title, message, confirmText, confirmLabel, cancelLabel, variant, loading, className |
 | DataTable | composite | Sortable, paginated data table with row actions. Use `flush` prop when embedded inside a container that provides its own border/radius |
 | DateRangePicker | primitive | Date range selection with presets |
@@ -284,8 +303,10 @@ import {
 | Component | Purpose |
 |-----------|---------|
 | AppShell | Page shell: sidebar + topbar + main + optional detail panel |
-| Sidebar | Hierarchical navigation with Applications/Agents/Routes trees, starring, search filter, bottom links. Props: `apps: SidebarApp[]` (hierarchical — apps contain routes and agents) |
-| TopBar | Header bar with breadcrumb, search trigger, ButtonGroup status filters, time range selector, theme toggle, environment badge, user avatar |
+| Sidebar | Composable compound sidebar shell with icon-rail collapse mode. Sub-components: `Sidebar.Header`, `Sidebar.Section`, `Sidebar.Footer`, `Sidebar.FooterLink`. The app controls all content via children — the DS provides the frame. |
+| SidebarTree | Data-driven tree for sidebar sections. Accepts `nodes: SidebarTreeNode[]` with expand/collapse, starring, keyboard nav, search filter, and path-based selection highlighting. |
+| useStarred | Hook for localStorage-backed starred item IDs. Returns `{ starredIds, isStarred, toggleStar }`. |
+| TopBar | Header bar with breadcrumb, search trigger, ButtonGroup status filters, time range selector, theme toggle, environment slot (`ReactNode` — pass a string for a static label or a custom dropdown for interactive selection), user avatar |

 ## Import Paths

@@ -296,6 +317,10 @@ import { Button, Input, Badge } from './design-system/primitives'
 import { DataTable, Modal, Toast } from './design-system/composites'
 import type { Column, SearchResult, FeedEvent } from './design-system/composites'
 import { AppShell } from './design-system/layout/AppShell'
+import { Sidebar } from './design-system/layout/Sidebar/Sidebar'
+import { SidebarTree } from './design-system/layout/Sidebar/SidebarTree'
+import type { SidebarTreeNode } from './design-system/layout/Sidebar/SidebarTree'
+import { useStarred } from './design-system/layout/Sidebar/useStarred'
 import { ThemeProvider, useTheme } from './design-system/providers/ThemeProvider'
 ```

@@ -309,6 +334,35 @@ import type { Column, DataTableProps, SearchResult } from '@cameleer/design-syst

 See `CLAUDE.md` "Using This Design System in Other Apps" for full setup instructions.

+## Brand Assets
+
+The design system ships logo assets as static files via the `./assets/*` package export. These are not React components — they resolve to file URLs when imported via a bundler. All PNGs have transparent backgrounds.
+
+| File | Size | Use case |
+|------|------|----------|
+| `cameleer3-logo.png` | Original | Full resolution for print/marketing |
+| `cameleer3-16.png` | 16×16 | Browser tab favicon |
+| `cameleer3-32.png` | 32×32 | Standard favicon, bookmarks |
+| `cameleer3-48.png` | 48×48 | Windows taskbar |
+| `cameleer3-180.png` | 180×180 | Apple touch icon |
+| `cameleer3-192.png` | 192×192 | Android/PWA icon |
+| `cameleer3-512.png` | 512×512 | PWA splash, og:image |
+| `cameleer3-logo.svg` | Vector | High-detail SVG logo (traced from PNG, transparent) |
+| `camel-logo.svg` | Vector | Simplified camel SVG logo |
+
+### Usage
+
+```tsx
+import logo from '@cameleer/design-system/assets/cameleer3-512.png'
+<img src={logo} alt="Cameleer3" />
+```
+
+```html
+<!-- Favicons in index.html -->
+<link rel="icon" type="image/png" sizes="32x32" href="/cameleer3-32.png">
+<link rel="apple-touch-icon" sizes="180x180" href="/cameleer3-180.png">
+```
+
 ## Styling Rules

 - **CSS Modules only** — no inline styles except dynamic values (width, color from props)
--- a/assets/camel-logo.svg
+++ b/assets/camel-logo.svg
--- a/assets/cameleer3-16.png
+++ b/assets/cameleer3-16.png
--- a/assets/cameleer3-180.png
+++ b/assets/cameleer3-180.png
--- a/assets/cameleer3-192.png
+++ b/assets/cameleer3-192.png
--- a/assets/cameleer3-32.png
+++ b/assets/cameleer3-32.png
--- a/assets/cameleer3-48.png
+++ b/assets/cameleer3-48.png
--- a/assets/cameleer3-512.png
+++ b/assets/cameleer3-512.png
--- a/assets/cameleer3-logo.png
+++ b/assets/cameleer3-logo.png
--- a/assets/cameleer3-logo.svg
+++ b/assets/cameleer3-logo.svg
--- a/docs/superpowers/plans/2026-04-02-composable-sidebar.md
+++ b/docs/superpowers/plans/2026-04-02-composable-sidebar.md
--- a/docs/superpowers/specs/2026-04-02-composable-sidebar-design.md
+++ b/docs/superpowers/specs/2026-04-02-composable-sidebar-design.md
@@ -0,0 +1,399 @@
+# Composable Sidebar Refactor
+
+**Date:** 2026-04-02
+**Upstream issue:** cameleer3-server #112
+
+## Why
+
+The current `Sidebar` component is monolithic. It hardcodes three navigation sections (Applications, Agents, Routes), a starred items section, bottom links (Admin, API Docs), and all tree-building logic (`buildAppTreeNodes`, `buildRouteTreeNodes`, `buildAgentTreeNodes`). The consuming application can only pass `SidebarApp[]` data — it cannot control what sections exist, what order they appear in, or add new sections without modifying this package.
+
+This blocks two features the consuming application needs:
+1. **Admin accordion** — when the user enters admin context, the sidebar should expand an Admin section and collapse operational sections, all controlled by the application
+2. **Icon-rail collapse** — the sidebar should collapse to a narrow icon strip, like modern app sidebars (Linear, VS Code, etc.)
+
+## Goal
+
+Refactor `Sidebar` into a composable compound component. The DS provides the frame and building blocks. The consuming application controls all content.
+
+## Current Exports (to be replaced)
+
+```typescript
+// Current — monolithic
+export { Sidebar } from './Sidebar/Sidebar'
+export type { SidebarApp, SidebarRoute, SidebarAgent } from './Sidebar/Sidebar'
+```
+
+## New Exports
+
+```typescript
+// New — composable
+export { Sidebar } from './Sidebar/Sidebar'
+export { SidebarTree } from './Sidebar/SidebarTree'
+export type { SidebarTreeNode } from './Sidebar/SidebarTree'
+export { useStarred } from './Sidebar/useStarred'
+```
+
+`SidebarApp`, `SidebarRoute`, `SidebarAgent` types are removed — they are application-domain types that move to the consuming app.
+
+## Compound Component API
+
+### `<Sidebar>`
+
+The outer shell. Renders the sidebar frame with an optional search input and collapse toggle.
+
+```tsx
+<Sidebar
+  collapsed={false}
+  onCollapseToggle={() => {}}
+  searchValue=""
+  onSearchChange={(query) => {}}
+  className=""
+>
+  <Sidebar.Header ... />
+  <Sidebar.Section ... />
+  <Sidebar.Section ... />
+  <Sidebar.Footer ... />
+</Sidebar>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `collapsed` | `boolean` | `false` | Render as ~48px icon rail |
+| `onCollapseToggle` | `() => void` | - | Collapse/expand toggle clicked |
+| `onSearchChange` | `(query: string) => void` | - | Search input changed. Omit to hide search. |
+| `searchValue` | `string` | `''` | Controlled value for the search input |
+| `children` | `ReactNode` | - | Sidebar.Header, Sidebar.Section, Sidebar.Footer |
+| `className` | `string` | - | Additional CSS class |
+
+**Search state ownership:** The DS renders the search input as a dumb controlled input and calls `onSearchChange` on every keystroke. The consuming application owns the search state and passes it to each `SidebarTree` as `filterQuery`. This lets the app control filtering behavior (e.g., clear search when switching sections, filter only certain sections). The DS does not hold any search state internally.
+
+**Rendering rules:**
+- Expanded: full width (~260px), all content visible
+- Collapsed: ~48px wide, only icons visible, tooltips on hover
+- Width transition: `transition: width 200ms ease`
+- Collapse toggle button (`<<` / `>>` chevron) in top-right corner
+- Search input hidden when collapsed
+- Search input auto-positioned between `Sidebar.Header` and first `Sidebar.Section` (not above Header)
+
+### `<Sidebar.Header>`
+
+Logo, title, and version. In collapsed mode, renders only the logo centered.
+
+```tsx
+<Sidebar.Header
+  logo={<img src="..." />}
+  title="cameleer"
+  version="v3.2.1"
+/>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `logo` | `ReactNode` | - | Logo element |
+| `title` | `string` | - | App name (hidden when collapsed) |
+| `version` | `string` | - | Version text (hidden when collapsed) |
+
+### `<Sidebar.Section>`
+
+An accordion section with a collapsible header and content area.
+
+```tsx
+<Sidebar.Section
+  label="APPLICATIONS"
+  icon={<Box size={14} />}
+  collapsed={false}
+  onToggle={() => {}}
+  active={false}
+>
+  <SidebarTree nodes={nodes} ... />
+</Sidebar.Section>
+```
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | - | Section header text (rendered uppercase via CSS) |
+| `icon` | `ReactNode` | - | Icon for header and collapsed rail |
+| `collapsed` | `boolean` | `false` | Whether children are hidden |
+| `onToggle` | `() => void` | - | Header clicked |
+| `children` | `ReactNode` | - | Content when expanded |
+| `active` | `boolean` | - | Override active highlight. If omitted, not highlighted. |
+
+**Expanded rendering:**
+```
+[icon] APPLICATIONS
+  (children rendered here)
+```
+
+**Collapsed rendering:**
+```
+[icon] APPLICATIONS
+```
+
+**In sidebar icon-rail mode:**
+```
+[icon]     <- centered, tooltip shows label on hover
+```
+
+Header has: icon and label (no chevron — the entire row is clickable). Active section gets the amber left-border accent (existing pattern). Clicking anywhere on the header row calls `onToggle`.
+
+**Implementation detail:** `Sidebar.Section` and `Sidebar.Header` need to know the parent's `collapsed` state to switch between expanded and icon-rail rendering. The `<Sidebar>` component provides `collapsed` and `onCollapseToggle` via React context (`SidebarContext`). Sub-components read from context — no prop drilling needed.
+
+**Icon-rail click behavior:** In collapsed mode, clicking a section icon fires both `onCollapseToggle` and `onToggle` simultaneously on the same click. The sidebar expands and the section opens in one motion. No navigation occurs — the user is expanding the sidebar to see what's inside, not committing to a destination. They click a tree item after the section is visible to navigate.
+
+### `<Sidebar.Footer>`
+
+Pinned to the bottom of the sidebar. Container for `Sidebar.FooterLink` items.
+
+```tsx
+<Sidebar.Footer>
+  <Sidebar.FooterLink icon={<FileText size={14} />} label="API Docs" onClick={() => {}} />
+</Sidebar.Footer>
+```
+
+In collapsed mode, footer links render as centered icons with tooltips.
+
+### `<Sidebar.FooterLink>`
+
+A single bottom link.
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `icon` | `ReactNode` | - | Link icon |
+| `label` | `string` | - | Link text (hidden when collapsed, shown as tooltip) |
+| `onClick` | `() => void` | - | Click handler |
+| `active` | `boolean` | `false` | Active state highlight |
+
+### `<SidebarTree>` (no changes, newly exported)
+
+Already exists at `Sidebar/SidebarTree.tsx`. No modifications needed — it already accepts all data via props. Just export it from the package.
+
+**Current props (unchanged):**
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `nodes` | `SidebarTreeNode[]` | Tree data |
+| `selectedPath` | `string` | Currently active path for highlighting |
+| `filterQuery` | `string` | Search filter text |
+| `onNavigate` | `(path: string) => void` | Navigation callback |
+| `persistKey` | `string` | localStorage key for expand state |
+| `autoRevealPath` | `string \| null` | Path to auto-expand to |
+| `isStarred` | `(id: string) => boolean` | Star state checker |
+| `onToggleStar` | `(id: string) => void` | Star toggle callback |
+
+### `useStarred` hook (no changes, newly exported)
+
+Already exists at `Sidebar/useStarred.ts`. Export as-is.
+
+**Returns:** `{ starredIds, isStarred, toggleStar }`
+
+## What Gets Removed
+
+All of this application-specific logic is deleted from the DS:
+
+1. **`buildAppTreeNodes()`** (~30 lines) — transforms `SidebarApp[]` into `SidebarTreeNode[]`
+2. **`buildRouteTreeNodes()`** (~20 lines) — transforms apps into route tree nodes
+3. **`buildAgentTreeNodes()`** (~25 lines) — transforms apps into agent tree nodes with live-count badges
+4. **`collectStarredItems()`** (~20 lines) — gathers starred items across types
+5. **`StarredGroup`** sub-component (~30 lines) — renders grouped starred items
+6. **Hardcoded sections** (~100 lines) — Applications, Agents, Routes section rendering with localStorage persistence
+7. **Hardcoded bottom links** (~30 lines) — Admin and API Docs links
+8. **Auto-reveal effect** (~20 lines) — `sidebarRevealPath` effect
+9. **`SidebarApp`, `SidebarRoute`, `SidebarAgent` types** — domain types, not DS types
+10. **`formatCount()` helper** — number formatting, moves to consuming app
+
+Total: ~300 lines of application logic removed, replaced by ~150 lines of compound component shell.
+
+## CSS Changes
+
+### New styles needed
+
+- `.sidebarCollapsed` — narrow width (48px), centered icons
+- `.collapseToggle` — `<<` / `>>` button positioning
+- `.sectionIcon` — icon rendering in section headers
+- `.tooltip` — hover tooltips for collapsed mode
+- Width transition: `transition: width 200ms ease` on `.sidebar`
+
+### Styles that stay
+
+- `.sidebar` (modified: width becomes conditional)
+- `.searchWrap`, `.searchInput` (unchanged)
+- `.navArea` (unchanged)
+- All tree styles in `SidebarTree` (unchanged)
+
+### Styles removed
+
+- `.bottom`, `.bottomItem`, `.bottomItemActive` — replaced by `Sidebar.Footer` / `Sidebar.FooterLink` styles
+- `.starredSection`, `.starredGroup`, `.starredItem`, `.starredRemove` — starred rendering moves to app
+- `.section` — replaced by `Sidebar.Section` styles
+
+## File Structure After Refactor
+
+```
+Sidebar/
+├── Sidebar.tsx              # Compound component: Sidebar, Sidebar.Header,
+│                            # Sidebar.Section, Sidebar.Footer, Sidebar.FooterLink
+├── Sidebar.module.css       # Updated styles (shell + section + footer + collapsed)
+├── SidebarTree.tsx           # Unchanged
+├── SidebarTree.module.css    # Unchanged (if separate, otherwise stays in Sidebar.module.css)
+├── useStarred.ts             # Unchanged
+├── useStarred.test.ts        # Unchanged
+└── Sidebar.test.tsx          # Updated for new compound API
+```
+
+## Testing
+
+Update `Sidebar.test.tsx` to test the compound component API:
+
+- Renders Header with logo, title, version
+- Renders Sections with labels and icons
+- Section toggle calls `onToggle`
+- Collapsed sections hide children
+- Sidebar collapsed mode renders icon rail
+- Collapse toggle calls `onCollapseToggle`
+- Footer links render with icons and labels
+- Collapsed mode hides labels, shows tooltips
+- Search input calls `onSearchChange`
+- Search hidden when sidebar collapsed
+- Section icon click in collapsed mode calls both `onCollapseToggle` and `onToggle`
+
+`SidebarTree` tests are unaffected.
+
+## Usage Example (for reference)
+
+This is how the consuming application (cameleer3-server) will use the new API. This code does NOT live in the design system — it's shown for context only.
+
+```tsx
+// In LayoutShell.tsx (consuming app)
+const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+const [filterQuery, setFilterQuery] = useState('');
+const [appsCollapsed, setAppsCollapsed] = useState(false);
+const [agentsCollapsed, setAgentsCollapsed] = useState(false);
+const [routesCollapsed, setRoutesCollapsed] = useState(true);
+const [adminCollapsed, setAdminCollapsed] = useState(true);
+
+// Accordion: entering admin expands admin, collapses others
+useEffect(() => {
+  if (isAdminPage) {
+    setAdminCollapsed(false);
+    setAppsCollapsed(true);
+    setAgentsCollapsed(true);
+    setRoutesCollapsed(true);
+  } else {
+    setAdminCollapsed(true);
+    // restore previous operational states
+  }
+}, [isAdminPage]);
+
+<Sidebar
+  collapsed={sidebarCollapsed}
+  onCollapseToggle={() => setSidebarCollapsed(v => !v)}
+  searchValue={filterQuery}
+  onSearchChange={setFilterQuery}
+>
+  <Sidebar.Header logo={<CameleerLogo />} title="cameleer" version="v3.2.1" />
+
+  {isAdminPage && (
+    <Sidebar.Section label="ADMIN" icon={<Settings size={14} />}
+      collapsed={adminCollapsed} onToggle={() => setAdminCollapsed(v => !v)}>
+      <SidebarTree nodes={adminNodes} ... filterQuery={filterQuery} />
+    </Sidebar.Section>
+  )}
+
+  <Sidebar.Section label="APPLICATIONS" icon={<Box size={14} />}
+    collapsed={appsCollapsed} onToggle={() => { setAppsCollapsed(v => !v); if (isAdminPage) nav('/exchanges'); }}>
+    <SidebarTree nodes={appNodes} ... filterQuery={filterQuery} />
+  </Sidebar.Section>
+
+  <Sidebar.Section label="AGENTS" icon={<Cpu size={14} />}
+    collapsed={agentsCollapsed} onToggle={() => { setAgentsCollapsed(v => !v); if (isAdminPage) nav('/exchanges'); }}>
+    <SidebarTree nodes={agentNodes} ... filterQuery={filterQuery} />
+  </Sidebar.Section>
+
+  <Sidebar.Section label="ROUTES" icon={<GitBranch size={14} />}
+    collapsed={routesCollapsed} onToggle={() => { setRoutesCollapsed(v => !v); if (isAdminPage) nav('/exchanges'); }}>
+    <SidebarTree nodes={routeNodes} ... filterQuery={filterQuery} />
+  </Sidebar.Section>
+
+  <Sidebar.Footer>
+    <Sidebar.FooterLink icon={<FileText size={14} />} label="API Docs" onClick={() => nav('/api-docs')} />
+  </Sidebar.Footer>
+</Sidebar>
+```
+
+## Mock App Migration — LayoutShell
+
+The 11 page files currently duplicating `<AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>` will be consolidated into a single `LayoutShell` component.
+
+### `src/layout/LayoutShell.tsx`
+
+Composes the sidebar once using the new compound API. All page-specific content is rendered via `<Outlet />`.
+
+```tsx
+// src/layout/LayoutShell.tsx
+export function LayoutShell() {
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false)
+  const [filterQuery, setFilterQuery] = useState('')
+  const [appsCollapsed, setAppsCollapsed] = useState(false)
+  const [agentsCollapsed, setAgentsCollapsed] = useState(false)
+  const [routesCollapsed, setRoutesCollapsed] = useState(false)
+  const { starredIds, isStarred, toggleStar } = useStarred()
+  const location = useLocation()
+  // ... build tree nodes from SIDEBAR_APPS, starred section, etc.
+
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar
+          collapsed={sidebarCollapsed}
+          onCollapseToggle={() => setSidebarCollapsed(v => !v)}
+          searchValue={filterQuery}
+          onSearchChange={setFilterQuery}
+        >
+          <Sidebar.Header logo={...} title="cameleer" version="v3.2.1" />
+          <Sidebar.Section label="Applications" icon={...}
+            collapsed={appsCollapsed} onToggle={() => setAppsCollapsed(v => !v)}>
+            <SidebarTree nodes={appNodes} filterQuery={filterQuery} ... />
+          </Sidebar.Section>
+          <Sidebar.Section label="Agents" icon={...}
+            collapsed={agentsCollapsed} onToggle={() => setAgentsCollapsed(v => !v)}>
+            <SidebarTree nodes={agentNodes} filterQuery={filterQuery} ... />
+          </Sidebar.Section>
+          <Sidebar.Section label="Routes" icon={...}
+            collapsed={routesCollapsed} onToggle={() => setRoutesCollapsed(v => !v)}>
+            <SidebarTree nodes={routeNodes} filterQuery={filterQuery} ... />
+          </Sidebar.Section>
+          {/* Starred section built from useStarred + SIDEBAR_APPS */}
+          <Sidebar.Footer>
+            <Sidebar.FooterLink icon={...} label="Admin" ... />
+            <Sidebar.FooterLink icon={...} label="API Docs" ... />
+          </Sidebar.Footer>
+        </Sidebar>
+      }
+    >
+      <Outlet />
+    </AppShell>
+  )
+}
+```
+
+### Route structure change
+
+`App.tsx` switches from per-page `<Route element={<Page />}>` to a layout route:
+
+```tsx
+<Route element={<LayoutShell />}>
+  <Route path="/apps" element={<Dashboard />} />
+  <Route path="/apps/:id" element={<Dashboard />} />
+  ...all existing routes...
+</Route>
+```
+
+All tree-building helpers (`buildAppTreeNodes`, `buildRouteTreeNodes`, `buildAgentTreeNodes`), starred section logic (`collectStarredItems`, `StarredGroup`), `formatCount`, and `sidebarRevealPath` handling move from `Sidebar.tsx` into `LayoutShell.tsx`. Each page file loses its `<AppShell sidebar={...}>` wrapper and becomes just the page content.
+
+The Inventory page's `LayoutSection` keeps its own inline `<Sidebar>` demo with `SAMPLE_APPS` data — it's a showcase, not a navigation shell.
+
+## Breaking Change
+
+This is a **breaking change** to the `Sidebar` API. The old `<Sidebar apps={[...]} onNavigate={...} />` signature is removed entirely. The consuming application must migrate to the compound component API in the same release cycle.
+
+Coordinate: bump DS version, update server UI, deploy together.
--- a/package.json
+++ b/package.json
@@ -10,10 +10,12 @@
      "types": "./dist/index.es.d.ts",
      "import": "./dist/index.es.js"
    },
-    "./style.css": "./dist/style.css"
+    "./style.css": "./dist/style.css",
+    "./assets/*": "./assets/*"
  },
  "files": [
-    "dist"
+    "dist",
+    "assets"
  ],
  "sideEffects": [
    "*.css"
--- a/src/App.tsx
+++ b/src/App.tsx
@@ -19,7 +19,8 @@ import { buildSearchData } from './mocks/searchData'
 import { exchanges } from './mocks/exchanges'
 import { routes } from './mocks/routes'
 import { agents } from './mocks/agents'
-import { SIDEBAR_APPS, buildRouteToAppMap } from './mocks/sidebar'
+import { buildRouteToAppMap } from './mocks/sidebar'
+import { LayoutShell } from './layout/LayoutShell'

 const routeToApp = buildRouteToAppMap()

@@ -78,21 +79,23 @@ export default function App() {
  return (
    <>
      <Routes>
-        <Route path="/" element={<Navigate to="/apps" replace />} />
-        <Route path="/apps" element={<Dashboard />} />
-        <Route path="/apps/:id" element={<Dashboard />} />
-        <Route path="/apps/:id/:routeId" element={<Dashboard />} />
-        <Route path="/routes" element={<RoutesPage />} />
-        <Route path="/routes/:appId" element={<RoutesPage />} />
-        <Route path="/routes/:appId/:routeId" element={<RoutesPage />} />
-        <Route path="/exchanges/:id" element={<ExchangeDetail />} />
-        <Route path="/agents/:appId/:instanceId" element={<AgentInstance />} />
-        <Route path="/agents/*" element={<AgentHealth />} />
-        <Route path="/admin" element={<Navigate to="/admin/rbac" replace />} />
-        <Route path="/admin/audit" element={<AuditLog />} />
-        <Route path="/admin/oidc" element={<OidcConfig />} />
-        <Route path="/admin/rbac" element={<UserManagement />} />
-        <Route path="/api-docs" element={<ApiDocs />} />
+        <Route element={<LayoutShell />}>
+          <Route path="/" element={<Navigate to="/apps" replace />} />
+          <Route path="/apps" element={<Dashboard />} />
+          <Route path="/apps/:id" element={<Dashboard />} />
+          <Route path="/apps/:id/:routeId" element={<Dashboard />} />
+          <Route path="/routes" element={<RoutesPage />} />
+          <Route path="/routes/:appId" element={<RoutesPage />} />
+          <Route path="/routes/:appId/:routeId" element={<RoutesPage />} />
+          <Route path="/exchanges/:id" element={<ExchangeDetail />} />
+          <Route path="/agents/:appId/:instanceId" element={<AgentInstance />} />
+          <Route path="/agents/*" element={<AgentHealth />} />
+          <Route path="/admin" element={<Navigate to="/admin/rbac" replace />} />
+          <Route path="/admin/audit" element={<AuditLog />} />
+          <Route path="/admin/oidc" element={<OidcConfig />} />
+          <Route path="/admin/rbac" element={<UserManagement />} />
+          <Route path="/api-docs" element={<ApiDocs />} />
+        </Route>
        <Route path="/inventory" element={<Inventory />} />
      </Routes>
      <CommandPalette
--- a/src/assets/cameleer3-logo.png
+++ b/src/assets/cameleer3-logo.png
--- a/src/assets/cameleer3-logo.svg
+++ b/src/assets/cameleer3-logo.svg
--- a/src/design-system/composites/BarChart/BarChart.tsx
+++ b/src/design-system/composites/BarChart/BarChart.tsx
@@ -83,6 +83,20 @@ export function BarChart({
    setTooltip({ x: mx, y: my, label: catLabel, values })
  }

+  function showBarTooltip(e: React.MouseEvent<SVGRectElement>, cat: string) {
+    const rect = e.currentTarget.closest('svg')!.getBoundingClientRect()
+    handleMouseEnter(
+      cat,
+      e.clientX - rect.left,
+      e.clientY - rect.top,
+      series.map((ss, ssi) => ({
+        series: ss.label,
+        value: ss.data.find((d) => d.x === cat)?.y ?? 0,
+        color: ss.color ?? CHART_COLORS[ssi % CHART_COLORS.length],
+      })),
+    )
+  }
+
  return (
    <div className={`${styles.wrapper} ${className ?? ''}`}>
      {yLabel && <div className={styles.yLabel}>{yLabel}</div>}
@@ -138,19 +152,7 @@ export function BarChart({
                      height={barH}
                      fill={color}
                      className={styles.bar}
-                      onMouseEnter={(e) => {
-                        const rect = e.currentTarget.closest('svg')!.getBoundingClientRect()
-                        handleMouseEnter(
-                          cat,
-                          e.clientX - rect.left,
-                          e.clientY - rect.top,
-                          series.map((ss, ssi) => ({
-                            series: ss.label,
-                            value: ss.data.find((d) => d.x === cat)?.y ?? 0,
-                            color: ss.color ?? CHART_COLORS[ssi % CHART_COLORS.length],
-                          })),
-                        )
-                      }}
+                      onMouseEnter={(e) => showBarTooltip(e, cat)}
                    />
                  )
                })}
@@ -184,19 +186,7 @@ export function BarChart({
                    height={barH}
                    fill={color}
                    className={styles.bar}
-                    onMouseEnter={(e) => {
-                      const svgEl = e.currentTarget.closest('svg')!.getBoundingClientRect()
-                      handleMouseEnter(
-                        cat,
-                        e.clientX - svgEl.left,
-                        e.clientY - svgEl.top,
-                        series.map((ss, ssi) => ({
-                          series: ss.label,
-                          value: ss.data.find((d) => d.x === cat)?.y ?? 0,
-                          color: ss.color ?? CHART_COLORS[ssi % CHART_COLORS.length],
-                        })),
-                      )
-                    }}
+                    onMouseEnter={(e) => showBarTooltip(e, cat)}
                  />
                )
              })}
--- a/src/design-system/composites/CommandPalette/CommandPalette.tsx
+++ b/src/design-system/composites/CommandPalette/CommandPalette.tsx
@@ -19,8 +19,7 @@ interface CommandPaletteProps {
  onSubmit?: (query: string) => void
 }

-const CATEGORY_LABELS: Record<SearchCategory | 'all', string> = {
-  all: 'All',
+const KNOWN_CATEGORY_LABELS: Record<string, string> = {
  application: 'Applications',
  exchange: 'Exchanges',
  attribute: 'Attributes',
@@ -28,8 +27,8 @@ const CATEGORY_LABELS: Record<SearchCategory | 'all', string> = {
  agent: 'Agents',
 }

-const ALL_CATEGORIES: Array<SearchCategory | 'all'> = [
-  'all',
+/** Preferred display order for known categories */
+const KNOWN_CATEGORY_ORDER: string[] = [
  'application',
  'exchange',
  'attribute',
@@ -37,6 +36,13 @@ const ALL_CATEGORIES: Array<SearchCategory | 'all'> = [
  'agent',
 ]

+function categoryLabel(cat: string): string {
+  if (cat === 'all') return 'All'
+  if (KNOWN_CATEGORY_LABELS[cat]) return KNOWN_CATEGORY_LABELS[cat]
+  // Title-case unknown categories: "my-thing" → "My Thing", "foo_bar" → "Foo Bar"
+  return cat.replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase())
+}
+
 function highlightText(text: string, query: string, matchRanges?: [number, number][]): ReactNode {
  if (!query && (!matchRanges || matchRanges.length === 0)) return text

@@ -69,7 +75,7 @@ function highlightText(text: string, query: string, matchRanges?: [number, numbe

 export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryChange, onSubmit }: CommandPaletteProps) {
  const [query, setQuery] = useState('')
-  const [activeCategory, setActiveCategory] = useState<SearchCategory | 'all'>('all')
+  const [activeCategory, setActiveCategory] = useState<string>('all')
  const [scopeFilters, setScopeFilters] = useState<ScopeFilter[]>([])
  const [focusedIdx, setFocusedIdx] = useState(0)
  const [expandedId, setExpandedId] = useState<string | null>(null)
@@ -128,7 +134,7 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC

  // Group results by category
  const grouped = useMemo(() => {
-    const map = new Map<SearchCategory, SearchResult[]>()
+    const map = new Map<string, SearchResult[]>()
    for (const r of filtered) {
      if (!map.has(r.category)) map.set(r.category, [])
      map.get(r.category)!.push(r)
@@ -148,6 +154,19 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC
    return counts
  }, [queryFiltered])

+  // Build tab list dynamically: 'all' + known categories (in order) + any unknown categories found in data
+  const visibleCategories = useMemo(() => {
+    const dataCategories = new Set(data.map((r) => r.category))
+    const tabs: string[] = ['all']
+    for (const cat of KNOWN_CATEGORY_ORDER) {
+      if (dataCategories.has(cat)) tabs.push(cat)
+    }
+    for (const cat of dataCategories) {
+      if (!tabs.includes(cat)) tabs.push(cat)
+    }
+    return tabs
+  }, [data])
+
  function handleKeyDown(e: React.KeyboardEvent) {
    switch (e.key) {
      case 'Escape':
@@ -186,10 +205,23 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC
    setScopeFilters((prev) => prev.filter((_, i) => i !== idx))
  }

+  function toggleExpanded(e: React.MouseEvent, id: string) {
+    e.stopPropagation()
+    setExpandedId((prev) => (prev === id ? null : id))
+  }
+
  if (!open) return null

  return createPortal(
-    <div className={styles.overlay} onClick={onClose} data-testid="command-palette-overlay">
+    <div
+      className={styles.overlay}
+      onClick={onClose}
+      onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') onClose() }}
+      role="button"
+      tabIndex={0}
+      aria-label="Close command palette"
+      data-testid="command-palette-overlay"
+    >
      <div
        className={styles.panel}
        onClick={(e) => e.stopPropagation()}
@@ -233,7 +265,7 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC

        {/* Category tabs */}
        <div className={styles.tabs} role="tablist">
-          {ALL_CATEGORIES.map((cat) => (
+          {visibleCategories.map((cat) => (
            <button
              key={cat}
              role="tab"
@@ -249,7 +281,7 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC
                setFocusedIdx(0)
              }}
            >
-              {CATEGORY_LABELS[cat]}
+              {categoryLabel(cat)}
              {categoryCounts[cat] != null && (
                <span className={styles.tabCount}>{categoryCounts[cat]}</span>
              )}
@@ -270,7 +302,7 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC
            Array.from(grouped.entries()).map(([category, items]) => (
              <div key={category} className={styles.group}>
                <div className={styles.groupHeader}>
-                  <SectionHeader>{CATEGORY_LABELS[category]}</SectionHeader>
+                  <SectionHeader>{categoryLabel(category)}</SectionHeader>
                </div>
                {items.map((result) => {
                  const flatIdx = flatResults.indexOf(result)
@@ -293,6 +325,12 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC
                        onSelect(result)
                        onClose()
                      }}
+                      onKeyDown={(e) => {
+                        if (e.key === 'Enter' || e.key === ' ') {
+                          onSelect(result)
+                          onClose()
+                        }
+                      }}
                      onMouseEnter={() => { userNavigated.current = true; setFocusedIdx(flatIdx) }}
                    >
                      <div className={styles.itemMain}>
@@ -328,10 +366,7 @@ export function CommandPalette({ open, onClose, onSelect, data, onOpen, onQueryC
                        {result.expandedContent && (
                          <button
                            className={styles.expandBtn}
-                            onClick={(e) => {
-                              e.stopPropagation()
-                              setExpandedId((prev) => (prev === result.id ? null : result.id))
-                            }}
+                            onClick={(e) => toggleExpanded(e, result.id)}
                            aria-expanded={isExpanded}
                            aria-label="Toggle detail"
                          >
--- a/src/design-system/composites/CommandPalette/types.ts
+++ b/src/design-system/composites/CommandPalette/types.ts
@@ -1,6 +1,7 @@
 import type { ReactNode } from 'react'

-export type SearchCategory = 'application' | 'exchange' | 'attribute' | 'route' | 'agent'
+/** Known categories: 'application' | 'exchange' | 'attribute' | 'route' | 'agent'. Custom categories are rendered with title-cased labels and a default icon. */
+export type SearchCategory = string

 export interface SearchResult {
  id: string
--- a/src/design-system/composites/Toast/Toast.tsx
+++ b/src/design-system/composites/Toast/Toast.tsx
@@ -57,6 +57,10 @@ export function ToastProvider({ children }: { children: ReactNode }) {
  const [toasts, setToasts] = useState<ToastItem[]>([])
  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map())

+  const removeToast = useCallback((id: string) => {
+    setToasts((prev) => prev.filter((t) => t.id !== id))
+  }, [])
+
  const dismiss = useCallback((id: string) => {
    // Clear auto-dismiss timer if running
    const timer = timersRef.current.get(id)
@@ -71,10 +75,8 @@ export function ToastProvider({ children }: { children: ReactNode }) {
    )

    // Remove after animation completes
-    setTimeout(() => {
-      setToasts((prev) => prev.filter((t) => t.id !== id))
-    }, EXIT_ANIMATION_MS)
-  }, [])
+    setTimeout(() => removeToast(id), EXIT_ANIMATION_MS)
+  }, [removeToast])

  const toast = useCallback(
    (options: ToastOptions): string => {
--- a/src/design-system/composites/TreeView/TreeView.tsx
+++ b/src/design-system/composites/TreeView/TreeView.tsx
@@ -31,6 +31,52 @@ function flattenVisibleNodes(
  return result
 }

+// ── Keyboard nav helpers ─────────────────────────────────────────────────────
+
+function handleArrowDown(visibleNodes: FlatNode[], currentIndex: number, focusNode: (id: string) => void) {
+  const next = visibleNodes[currentIndex + 1]
+  if (next) focusNode(next.node.id)
+}
+
+function handleArrowUp(visibleNodes: FlatNode[], currentIndex: number, focusNode: (id: string) => void) {
+  const prev = visibleNodes[currentIndex - 1]
+  if (prev) focusNode(prev.node.id)
+}
+
+function handleArrowRight(
+  current: FlatNode | undefined,
+  currentIndex: number,
+  expandedSet: Set<string>,
+  visibleNodes: FlatNode[],
+  handleToggle: (id: string) => void,
+  focusNode: (id: string) => void,
+) {
+  if (!current) return
+  const hasChildren = current.node.children && current.node.children.length > 0
+  if (!hasChildren) return
+  if (!expandedSet.has(current.node.id)) {
+    handleToggle(current.node.id)
+  } else {
+    const next = visibleNodes[currentIndex + 1]
+    if (next) focusNode(next.node.id)
+  }
+}
+
+function handleArrowLeft(
+  current: FlatNode | undefined,
+  expandedSet: Set<string>,
+  handleToggle: (id: string) => void,
+  focusNode: (id: string) => void,
+) {
+  if (!current) return
+  const hasChildren = current.node.children && current.node.children.length > 0
+  if (hasChildren && expandedSet.has(current.node.id)) {
+    handleToggle(current.node.id)
+  } else if (current.parentId !== null) {
+    focusNode(current.parentId)
+  }
+}
+
 interface TreeViewProps {
  nodes: TreeNode[]
  onSelect?: (id: string) => void
@@ -105,68 +151,13 @@ export function TreeView({
      const current = visibleNodes[currentIndex]

      switch (e.key) {
-        case 'ArrowDown': {
-          e.preventDefault()
-          const next = visibleNodes[currentIndex + 1]
-          if (next) focusNode(next.node.id)
-          break
-        }
-        case 'ArrowUp': {
-          e.preventDefault()
-          const prev = visibleNodes[currentIndex - 1]
-          if (prev) focusNode(prev.node.id)
-          break
-        }
-        case 'ArrowRight': {
-          e.preventDefault()
-          if (!current) break
-          const hasChildren = current.node.children && current.node.children.length > 0
-          if (hasChildren) {
-            if (!expandedSet.has(current.node.id)) {
-              // Expand it
-              handleToggle(current.node.id)
-            } else {
-              // Move to first child (it will be the next visible node)
-              const next = visibleNodes[currentIndex + 1]
-              if (next) focusNode(next.node.id)
-            }
-          }
-          break
-        }
-        case 'ArrowLeft': {
-          e.preventDefault()
-          if (!current) break
-          const hasChildren = current.node.children && current.node.children.length > 0
-          if (hasChildren && expandedSet.has(current.node.id)) {
-            // Collapse
-            handleToggle(current.node.id)
-          } else if (current.parentId !== null) {
-            // Move to parent
-            focusNode(current.parentId)
-          }
-          break
-        }
-        case 'Enter': {
-          e.preventDefault()
-          if (current) {
-            onSelect?.(current.node.id)
-          }
-          break
-        }
-        case 'Home': {
-          e.preventDefault()
-          if (visibleNodes.length > 0) {
-            focusNode(visibleNodes[0].node.id)
-          }
-          break
-        }
-        case 'End': {
-          e.preventDefault()
-          if (visibleNodes.length > 0) {
-            focusNode(visibleNodes[visibleNodes.length - 1].node.id)
-          }
-          break
-        }
+        case 'ArrowDown': { e.preventDefault(); handleArrowDown(visibleNodes, currentIndex, focusNode); break }
+        case 'ArrowUp': { e.preventDefault(); handleArrowUp(visibleNodes, currentIndex, focusNode); break }
+        case 'ArrowRight': { e.preventDefault(); handleArrowRight(current, currentIndex, expandedSet, visibleNodes, handleToggle, focusNode); break }
+        case 'ArrowLeft': { e.preventDefault(); handleArrowLeft(current, expandedSet, handleToggle, focusNode); break }
+        case 'Enter': { e.preventDefault(); if (current) onSelect?.(current.node.id); break }
+        case 'Home': { e.preventDefault(); if (visibleNodes.length > 0) focusNode(visibleNodes[0].node.id); break }
+        case 'End': { e.preventDefault(); if (visibleNodes.length > 0) focusNode(visibleNodes[visibleNodes.length - 1].node.id); break }
      }
    },
    // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -239,6 +230,10 @@ function TreeNodeRow({

  return (
    <li role="none">
+      {/* S1082: No onKeyDown here by design — the parent <ul role="tree"> carries
+          onKeyDown={handleKeyDown} which handles Enter (select) and all arrow keys
+          per the WAI-ARIA tree widget pattern. Adding a duplicate handler here would
+          fire the action twice. */}
      <div
        role="treeitem"
        aria-expanded={hasChildren ? isExpanded : undefined}
--- a/src/design-system/layout/Sidebar/Sidebar.module.css
+++ b/src/design-system/layout/Sidebar/Sidebar.module.css
@@ -5,6 +5,36 @@
  display: flex;
  flex-direction: column;
  overflow: hidden;
+  position: relative;
+  transition: width 200ms ease;
+}
+
+.sidebarCollapsed {
+  width: 48px;
+}
+
+/* Collapse toggle */
+.collapseToggle {
+  position: absolute;
+  top: 8px;
+  right: 4px;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: none;
+  border: none;
+  color: var(--sidebar-muted);
+  cursor: pointer;
+  border-radius: var(--radius-sm);
+  padding: 0;
+  z-index: 1;
+  transition: color 0.12s;
+}
+
+.collapseToggle:hover {
+  color: var(--sidebar-text);
 }

 /* Logo */
@@ -15,6 +45,12 @@
  gap: 10px;
  border-bottom: 1px solid rgba(255, 255, 255, 0.06);
  flex-shrink: 0;
+  overflow: hidden;
+}
+
+.sidebarCollapsed .logo {
+  padding: 16px 0;
+  justify-content: center;
 }

 .logoImg {
@@ -106,71 +142,40 @@
  background: rgba(255, 255, 255, 0.08);
 }

-/* Scrollable nav area */
-.navArea {
-  flex: 1;
-  overflow-y: auto;
-  min-height: 0;
-}
-
-/* Section headers */
-.section {
-  padding: 14px 12px 5px;
-  font-size: 10px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 1.2px;
+/* Section icon (collapsed rail) */
+.sectionIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
  color: var(--sidebar-muted);
 }

-/* Items container */
-.items {
-  padding: 0 6px;
-}
-
-/* Nav item (flat links like Dashboards) */
-.item {
+/* Rail item (collapsed sidebar section) */
+.sectionRailItem {
  display: flex;
  align-items: center;
-  gap: 10px;
-  padding: 7px 12px;
-  border-radius: var(--radius-sm);
-  color: var(--sidebar-text);
-  font-size: 13px;
+  justify-content: center;
+  padding: 10px 0;
  cursor: pointer;
-  transition: all 0.12s;
  border-left: 3px solid transparent;
-  margin-bottom: 1px;
-  user-select: none;
+  transition: background 0.12s;
 }

-.item:hover {
+.sectionRailItem:hover {
  background: var(--sidebar-hover);
-  color: #e8dfd4;
 }

-.item.active {
-  background: var(--sidebar-active);
-  color: var(--amber);
+.sectionRailItemActive {
  border-left-color: var(--amber);
 }

-.navIcon {
-  font-size: 14px;
-  width: 18px;
-  text-align: center;
-  color: var(--sidebar-muted);
-  flex-shrink: 0;
-}
-
-.item.active .navIcon {
+.sectionRailItemActive .sectionIcon {
  color: var(--amber);
 }

-.routeArrow {
-  color: var(--sidebar-muted);
-  font-size: 10px;
-  flex-shrink: 0;
+.treeSectionActive {
+  border-left-color: var(--amber);
 }

 /* Item sub-elements */
@@ -200,15 +205,7 @@
  padding: 0 6px 6px;
  margin-bottom: 2px;
  border-bottom: 1px solid rgba(255, 255, 255, 0.12);
-}
-
-.treeSectionLabel {
-  padding: 10px 12px 4px;
-  font-size: 10px;
-  font-weight: 600;
-  text-transform: uppercase;
-  letter-spacing: 1px;
-  color: var(--sidebar-muted);
+  border-left: 3px solid transparent;
 }

 /* Collapsible section toggle */
@@ -218,6 +215,8 @@
  gap: 2px;
  width: 100%;
  padding: 8px 0 4px;
+  cursor: pointer;
+  user-select: none;
 }

 .treeSectionChevronBtn {
@@ -383,100 +382,13 @@
  color: var(--amber);
 }

-/* ── Starred section ─────────────────────────────────────────────────────── */
-
-.starredSection {
-  border-top: 1px solid rgba(255, 255, 255, 0.06);
-  margin-top: 4px;
-}
-
-.starredHeader {
-  color: var(--amber);
-}
-
-.starredList {
-  padding: 0 6px 6px;
-}
-
-.starredGroup {
-  margin-bottom: 4px;
-}
-
-.starredGroupLabel {
-  padding: 4px 12px 2px;
-  font-size: 10px;
-  color: var(--sidebar-muted);
-  font-weight: 500;
-}
-
-.starredItem {
-  display: flex;
-  align-items: center;
-  gap: 8px;
-  padding: 4px 12px;
-  border-radius: var(--radius-sm);
-  color: var(--sidebar-text);
-  font-size: 12px;
-  cursor: pointer;
-  transition: background 0.12s;
-  user-select: none;
-}
-
-.starredItem:hover {
-  background: var(--sidebar-hover);
-}
-
-.starredItemInfo {
-  flex: 1;
-  min-width: 0;
-  display: flex;
-  flex-direction: column;
-}
-
-.starredItemName {
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  font-weight: 500;
-}
-
-.starredItemContext {
-  font-size: 10px;
-  color: var(--sidebar-muted);
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
-}
-
-/* Remove button */
-.starredRemove {
-  background: none;
-  border: none;
-  padding: 2px;
-  margin: 0;
-  color: var(--sidebar-muted);
-  cursor: pointer;
-  opacity: 0;
-  transition: opacity 0.15s, color 0.15s;
-  display: flex;
-  align-items: center;
-  flex-shrink: 0;
-}
-
-.starredItem:hover .starredRemove {
-  opacity: 1;
-}
-
-.starredRemove:hover {
-  color: var(--error);
-}
-
 /* ── Bottom links ────────────────────────────────────────────────────────── */

 .bottom {
  border-top: 1px solid rgba(255, 255, 255, 0.06);
  padding: 6px;
  flex-shrink: 0;
+  margin-top: auto;
 }

 .bottomItem {
--- a/src/design-system/layout/Sidebar/Sidebar.test.tsx
+++ b/src/design-system/layout/Sidebar/Sidebar.test.tsx
@@ -1,172 +1,327 @@
-import { describe, it, expect, beforeEach } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import userEvent from '@testing-library/user-event'
 import { MemoryRouter } from 'react-router-dom'
-import { Sidebar, type SidebarApp } from './Sidebar'
+import { Sidebar } from './Sidebar'
 import { ThemeProvider } from '../../providers/ThemeProvider'

-const TEST_APPS: SidebarApp[] = [
-  {
-    id: 'order-service',
-    name: 'order-service',
-    health: 'live',
-    exchangeCount: 1433,
-    routes: [
-      { id: 'order-intake', name: 'order-intake', exchangeCount: 892 },
-      { id: 'order-enrichment', name: 'order-enrichment', exchangeCount: 541 },
-    ],
-    agents: [
-      { id: 'prod-1', name: 'prod-1', status: 'live', tps: 14.2 },
-      { id: 'prod-2', name: 'prod-2', status: 'live', tps: 11.8 },
-    ],
-  },
-  {
-    id: 'payment-svc',
-    name: 'payment-svc',
-    health: 'live',
-    exchangeCount: 912,
-    routes: [
-      { id: 'payment-process', name: 'payment-process', exchangeCount: 414 },
-    ],
-    agents: [],
-  },
-]
+// ── Helpers ─────────────────────────────────────────────────────────────────

-function renderSidebar(props: Partial<Parameters<typeof Sidebar>[0]> = {}) {
-  return render(
+const LogoIcon = () => <svg data-testid="logo-icon" />
+
+function Wrapper({ children }: { children: React.ReactNode }) {
+  return (
    <ThemeProvider>
-      <MemoryRouter>
-        <Sidebar apps={TEST_APPS} {...props} />
-      </MemoryRouter>
-    </ThemeProvider>,
+      <MemoryRouter>{children}</MemoryRouter>
+    </ThemeProvider>
  )
 }

-describe('Sidebar', () => {
-  beforeEach(() => {
-    localStorage.clear()
-    sessionStorage.clear()
+// ── Tests ────────────────────────────────────────────────────────────────────
+
+describe('Sidebar compound component', () => {
+  // 1. renders Header with logo, title, version
+  it('renders Header with logo, title, and version', () => {
+    render(
+      <Wrapper>
+        <Sidebar>
+          <Sidebar.Header logo={<LogoIcon />} title="MyApp" version="v1.2.3" />
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.getByTestId('logo-icon')).toBeInTheDocument()
+    expect(screen.getByText('MyApp')).toBeInTheDocument()
+    expect(screen.getByText('v1.2.3')).toBeInTheDocument()
  })

-  it('renders the logo and brand name', () => {
-    renderSidebar()
-    expect(screen.getByText('cameleer')).toBeInTheDocument()
-    expect(screen.getByText('v3.2.1')).toBeInTheDocument()
+  // 2. hides Header title and version when collapsed
+  it('hides Header title and version when sidebar is collapsed', () => {
+    render(
+      <Wrapper>
+        <Sidebar collapsed>
+          <Sidebar.Header logo={<LogoIcon />} title="MyApp" version="v1.2.3" />
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.queryByText('MyApp')).not.toBeInTheDocument()
+    expect(screen.queryByText('v1.2.3')).not.toBeInTheDocument()
+    // Logo should still be visible
+    expect(screen.getByTestId('logo-icon')).toBeInTheDocument()
  })

-  it('renders the search input', () => {
-    renderSidebar()
-    expect(screen.getByPlaceholderText('Filter...')).toBeInTheDocument()
+  // 3. renders Section with label and children
+  it('renders Section with label and children when open', () => {
+    render(
+      <Wrapper>
+        <Sidebar>
+          <Sidebar.Section
+            icon={<span>icon</span>}
+            label="Settings"
+            open
+            onToggle={vi.fn()}
+          >
+            <div>Section Child</div>
+          </Sidebar.Section>
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.getByText('Settings')).toBeInTheDocument()
+    expect(screen.getByText('Section Child')).toBeInTheDocument()
  })

-  it('renders Navigation section header', () => {
-    renderSidebar()
-    expect(screen.getByText('Navigation')).toBeInTheDocument()
+  // 4. hides Section children when section collapsed (open=false)
+  it('hides Section children when section is not open', () => {
+    render(
+      <Wrapper>
+        <Sidebar>
+          <Sidebar.Section
+            icon={<span>icon</span>}
+            label="Settings"
+            open={false}
+            onToggle={vi.fn()}
+          >
+            <div>Section Child</div>
+          </Sidebar.Section>
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.getByText('Settings')).toBeInTheDocument()
+    expect(screen.queryByText('Section Child')).not.toBeInTheDocument()
  })

-  it('renders Applications tree section', () => {
-    renderSidebar()
-    expect(screen.getByText('Applications')).toBeInTheDocument()
+  // 5. calls onToggle when Section header clicked
+  it('calls onToggle when Section chevron button is clicked', async () => {
+    const user = userEvent.setup()
+    const onToggle = vi.fn()
+
+    render(
+      <Wrapper>
+        <Sidebar>
+          <Sidebar.Section
+            icon={<span>icon</span>}
+            label="Settings"
+            open
+            onToggle={onToggle}
+          >
+            <div>child</div>
+          </Sidebar.Section>
+        </Sidebar>
+      </Wrapper>,
+    )
+
+    const btn = screen.getByRole('button', { name: /collapse settings/i })
+    await user.click(btn)
+    expect(onToggle).toHaveBeenCalledTimes(1)
  })

-  it('renders Agents tree section', () => {
-    renderSidebar()
-    expect(screen.getByText('Agents')).toBeInTheDocument()
+  // 6. renders collapse toggle and calls onCollapseToggle
+  it('renders collapse toggle button and calls onCollapseToggle when clicked', async () => {
+    const user = userEvent.setup()
+    const onCollapseToggle = vi.fn()
+
+    render(
+      <Wrapper>
+        <Sidebar onCollapseToggle={onCollapseToggle}>
+          <Sidebar.Header logo={<LogoIcon />} title="App" />
+        </Sidebar>
+      </Wrapper>,
+    )
+
+    const toggleBtn = screen.getByRole('button', { name: /collapse sidebar/i })
+    await user.click(toggleBtn)
+    expect(onCollapseToggle).toHaveBeenCalledTimes(1)
  })

-  it('renders Routes nav link', () => {
-    renderSidebar()
-    expect(screen.getByText('Routes')).toBeInTheDocument()
+  // 7. renders expand toggle label when collapsed
+  it('renders expand toggle when sidebar is collapsed', () => {
+    render(
+      <Wrapper>
+        <Sidebar collapsed onCollapseToggle={vi.fn()}>
+          <Sidebar.Header logo={<LogoIcon />} title="App" />
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.getByRole('button', { name: /expand sidebar/i })).toBeInTheDocument()
  })

-  it('renders bottom links', () => {
-    renderSidebar()
+  // 8. renders search input and calls onSearchChange
+  it('renders search input and calls onSearchChange on input', async () => {
+    const user = userEvent.setup()
+    const onSearchChange = vi.fn()
+
+    render(
+      <Wrapper>
+        <Sidebar searchValue="" onSearchChange={onSearchChange}>
+          <Sidebar.Header logo={<LogoIcon />} title="App" />
+        </Sidebar>
+      </Wrapper>,
+    )
+
+    const input = screen.getByPlaceholderText('Filter...')
+    expect(input).toBeInTheDocument()
+
+    await user.type(input, 'hello')
+    expect(onSearchChange).toHaveBeenCalled()
+    // Each keystroke fires once
+    expect(onSearchChange.mock.calls[0][0]).toBe('h')
+  })
+
+  // 9. hides search when collapsed
+  it('hides search input when sidebar is collapsed', () => {
+    render(
+      <Wrapper>
+        <Sidebar collapsed searchValue="" onSearchChange={vi.fn()}>
+          <Sidebar.Header logo={<LogoIcon />} title="App" />
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.queryByPlaceholderText('Filter...')).not.toBeInTheDocument()
+  })
+
+  // 10. hides search when onSearchChange not provided
+  it('hides search input when onSearchChange is not provided', () => {
+    render(
+      <Wrapper>
+        <Sidebar searchValue="">
+          <Sidebar.Header logo={<LogoIcon />} title="App" />
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.queryByPlaceholderText('Filter...')).not.toBeInTheDocument()
+  })
+
+  // 11. renders FooterLinks with icons and labels
+  it('renders FooterLinks with icon and label', () => {
+    render(
+      <Wrapper>
+        <Sidebar>
+          <Sidebar.Footer>
+            <Sidebar.FooterLink
+              icon={<span data-testid="footer-icon">ic</span>}
+              label="Admin"
+            />
+          </Sidebar.Footer>
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.getByTestId('footer-icon')).toBeInTheDocument()
    expect(screen.getByText('Admin')).toBeInTheDocument()
-    expect(screen.getByText('API Docs')).toBeInTheDocument()
  })

-  it('renders app names in the Applications tree', () => {
-    renderSidebar()
-    // order-service appears in Applications, Routes, and Agents trees
-    expect(screen.getAllByText('order-service').length).toBeGreaterThanOrEqual(1)
-    expect(screen.getAllByText('payment-svc').length).toBeGreaterThanOrEqual(1)
+  // 12. hides FooterLink labels when collapsed and sets title tooltip
+  it('hides FooterLink label when collapsed and exposes title tooltip', () => {
+    render(
+      <Wrapper>
+        <Sidebar collapsed>
+          <Sidebar.Footer>
+            <Sidebar.FooterLink
+              icon={<span>ic</span>}
+              label="Admin"
+            />
+          </Sidebar.Footer>
+        </Sidebar>
+      </Wrapper>,
+    )
+    expect(screen.queryByText('Admin')).not.toBeInTheDocument()
+
+    // The clickable element should carry a title attribute for tooltip
+    // (accessible name comes from icon content when label is hidden)
+    const item = screen.getByTitle('Admin')
+    expect(item).toHaveAttribute('title', 'Admin')
  })

-  it('renders exchange count badges', () => {
-    renderSidebar()
-    expect(screen.getByText('1.4k')).toBeInTheDocument()
-  })
-
-  it('renders agent live count badge in Agents tree', () => {
-    renderSidebar()
-    expect(screen.getByText('2/2 live')).toBeInTheDocument()
-  })
-
-  it('does not show starred section when nothing is starred', () => {
-    renderSidebar()
-    expect(screen.queryByText('★ Starred')).not.toBeInTheDocument()
-  })
-
-  it('shows starred section after starring an item', async () => {
+  // 13. calls FooterLink onClick
+  it('calls FooterLink onClick when clicked', async () => {
    const user = userEvent.setup()
-    renderSidebar()
+    const onClick = vi.fn()

-    // Find the first app row (order-service in Applications tree) and hover to reveal star
-    const appRows = screen.getAllByText('order-service')
-    const appRow = appRows[0].closest('[role="treeitem"]')!
-    await user.hover(appRow)
+    render(
+      <Wrapper>
+        <Sidebar>
+          <Sidebar.Footer>
+            <Sidebar.FooterLink icon={<span>ic</span>} label="Admin" onClick={onClick} />
+          </Sidebar.Footer>
+        </Sidebar>
+      </Wrapper>,
+    )

-    // Click the star button
-    const starBtn = appRow.querySelector('button[aria-label="Add to starred"]')!
-    await user.click(starBtn)
-
-    expect(screen.getByText('★ Starred')).toBeInTheDocument()
+    await user.click(screen.getByText('Admin'))
+    expect(onClick).toHaveBeenCalledTimes(1)
  })

-  it('filters tree items by search', async () => {
+  // 14. renders Section as icon-rail item when sidebar collapsed
+  it('renders Section as icon-rail item when sidebar is collapsed', () => {
+    render(
+      <Wrapper>
+        <Sidebar collapsed>
+          <Sidebar.Section
+            icon={<span data-testid="section-icon">ic</span>}
+            label="Settings"
+            open={false}
+            onToggle={vi.fn()}
+          >
+            <div>child</div>
+          </Sidebar.Section>
+        </Sidebar>
+      </Wrapper>,
+    )
+
+    // Label text should not be visible (only as tooltip via title attr)
+    expect(screen.queryByText('Settings')).not.toBeInTheDocument()
+
+    // Rail item carries title attribute for tooltip
+    // (accessible name comes from icon content when label is hidden)
+    const railItem = screen.getByTitle('Settings')
+    expect(railItem).toHaveAttribute('title', 'Settings')
+
+    // Icon should still render
+    expect(screen.getByTestId('section-icon')).toBeInTheDocument()
+
+    // Section children should not be rendered
+    expect(screen.queryByText('child')).not.toBeInTheDocument()
+  })
+
+  // 15. fires both onCollapseToggle and onToggle when icon-rail section clicked
+  it('fires both onCollapseToggle and onToggle when icon-rail section is clicked', async () => {
    const user = userEvent.setup()
-    renderSidebar()
+    const onCollapseToggle = vi.fn()
+    const onToggle = vi.fn()

-    const searchInput = screen.getByPlaceholderText('Filter...')
-    await user.type(searchInput, 'payment')
+    render(
+      <Wrapper>
+        <Sidebar collapsed onCollapseToggle={onCollapseToggle}>
+          <Sidebar.Section
+            icon={<span>ic</span>}
+            label="Settings"
+            open={false}
+            onToggle={onToggle}
+          >
+            <div>child</div>
+          </Sidebar.Section>
+        </Sidebar>
+      </Wrapper>,
+    )

-    // payment-svc should still be visible (may appear in multiple trees)
-    expect(screen.getAllByText('payment-svc').length).toBeGreaterThanOrEqual(1)
+    const railItem = screen.getByTitle('Settings')
+    await user.click(railItem)
+
+    expect(onCollapseToggle).toHaveBeenCalledTimes(1)
+    expect(onToggle).toHaveBeenCalledTimes(1)
  })

-  it('expands tree to show children when chevron is clicked', async () => {
-    const user = userEvent.setup()
-    renderSidebar()
+  // 16. applies active highlight to FooterLink
+  it('applies active highlight class to FooterLink when active', () => {
+    render(
+      <Wrapper>
+        <Sidebar>
+          <Sidebar.Footer>
+            <Sidebar.FooterLink icon={<span>ic</span>} label="Admin" active />
+          </Sidebar.Footer>
+        </Sidebar>
+      </Wrapper>,
+    )

-    // Find the expand button for order-service in Applications tree
-    const expandBtns = screen.getAllByLabelText('Expand')
-    await user.click(expandBtns[0])
-
-    // Routes should now be visible
-    expect(screen.getByText('order-intake')).toBeInTheDocument()
-    expect(screen.getByText('order-enrichment')).toBeInTheDocument()
-  })
-
-  it('collapses expanded tree when chevron is clicked again', async () => {
-    const user = userEvent.setup()
-    renderSidebar()
-
-    const expandBtns = screen.getAllByLabelText('Expand')
-    await user.click(expandBtns[0])
-    expect(screen.getByText('order-intake')).toBeInTheDocument()
-
-    const collapseBtn = screen.getByLabelText('Collapse')
-    await user.click(collapseBtn)
-    expect(screen.queryByText('order-intake')).not.toBeInTheDocument()
-  })
-
-  it('does not render apps with no agents in the Agents tree', () => {
-    renderSidebar()
-    // payment-svc has no agents, so it shouldn't appear under the Agents section header
-    // But it still appears under Applications. Let's check the agent tree specifically.
-    const agentBadges = screen.queryAllByText(/\/.*live/)
-    // Only order-service should have an agent badge
-    expect(agentBadges).toHaveLength(1)
-    expect(agentBadges[0].textContent).toBe('2/2 live')
+    const item = screen.getByText('Admin').closest('[role="button"]')!
+    expect(item.className).toMatch(/bottomItemActive/)
  })
 })
--- a/src/design-system/layout/Sidebar/Sidebar.tsx
+++ b/src/design-system/layout/Sidebar/Sidebar.tsx
@@ -1,563 +1,253 @@
-import { useState, useEffect, useMemo } from 'react'
-import { useNavigate, useLocation } from 'react-router-dom'
-import { Search, X, ChevronRight, ChevronDown, Settings, FileText } from 'lucide-react'
+import { type ReactNode, Children, isValidElement } from 'react'
+import {
+  Search,
+  X,
+  ChevronsLeft,
+  ChevronsRight,
+} from 'lucide-react'
 import styles from './Sidebar.module.css'
-import camelLogoUrl from '../../../assets/camel-logo.svg'
-import { SidebarTree, type SidebarTreeNode } from './SidebarTree'
-import { useStarred } from './useStarred'
-import { StatusDot } from '../../primitives/StatusDot/StatusDot'
+import { SidebarContext, useSidebarContext } from './SidebarContext'

-// ── Types ────────────────────────────────────────────────────────────────────
+// ── Sub-component props ─────────────────────────────────────────────────────

-export interface SidebarApp {
-  id: string
-  name: string
-  health: 'live' | 'stale' | 'dead'
-  exchangeCount: number
-  routes: SidebarRoute[]
-  agents: SidebarAgent[]
-}
-
-export interface SidebarRoute {
-  id: string
-  name: string
-  exchangeCount: number
-}
-
-export interface SidebarAgent {
-  id: string
-  name: string
-  status: 'live' | 'stale' | 'dead'
-  tps: number
-}
-
-interface SidebarProps {
-  apps: SidebarApp[]
+interface SidebarHeaderProps {
+  logo: ReactNode
+  title: string
+  version?: string
+  onClick?: () => void
  className?: string
-  onNavigate?: (path: string) => void
 }

-// ── Helpers ──────────────────────────────────────────────────────────────────
-
-function formatCount(n: number): string {
-  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`
-  return String(n)
-}
-
-function buildAppTreeNodes(apps: SidebarApp[]): SidebarTreeNode[] {
-  return apps.map((app) => ({
-    id: `app:${app.id}`,
-    label: app.name,
-    icon: <StatusDot variant={app.health} />,
-    badge: formatCount(app.exchangeCount),
-    path: `/apps/${app.id}`,
-    starrable: true,
-    starKey: app.id,
-    children: app.routes.map((route) => ({
-      id: `route:${app.id}:${route.id}`,
-      starKey: `${app.id}:${route.id}`,
-      label: route.name,
-      icon: <ChevronRight size={12} />,
-      badge: formatCount(route.exchangeCount),
-      path: `/apps/${app.id}/${route.id}`,
-      starrable: true,
-    })),
-  }))
-}
-
-function buildRouteTreeNodes(apps: SidebarApp[]): SidebarTreeNode[] {
-  return apps
-    .filter((app) => app.routes.length > 0)
-    .map((app) => ({
-      id: `routes:${app.id}`,
-      label: app.name,
-      icon: <StatusDot variant={app.health} />,
-      badge: `${app.routes.length} routes`,
-      path: `/routes/${app.id}`,
-      starrable: true,
-      starKey: `routes:${app.id}`,
-      children: app.routes.map((route) => ({
-        id: `routestat:${app.id}:${route.id}`,
-        starKey: `routes:${app.id}:${route.id}`,
-        label: route.name,
-        icon: <ChevronRight size={12} />,
-        badge: formatCount(route.exchangeCount),
-        path: `/routes/${app.id}/${route.id}`,
-        starrable: true,
-      })),
-    }))
-}
-
-function buildAgentTreeNodes(apps: SidebarApp[]): SidebarTreeNode[] {
-  return apps
-    .filter((app) => app.agents.length > 0)
-    .map((app) => {
-      const liveCount = app.agents.filter((a) => a.status === 'live').length
-      return {
-        id: `agents:${app.id}`,
-        label: app.name,
-        icon: <StatusDot variant={app.health} />,
-        badge: `${liveCount}/${app.agents.length} live`,
-        path: `/agents/${app.id}`,
-        starrable: true,
-        starKey: `agents:${app.id}`,
-        children: app.agents.map((agent) => ({
-          id: `agent:${app.id}:${agent.id}`,
-          starKey: `${app.id}:${agent.id}`,
-          label: agent.name,
-          badge: `${agent.tps.toFixed(1)}/s`,
-          path: `/agents/${app.id}/${agent.id}`,
-          starrable: true,
-        })),
-      }
-    })
-}
-
-// ── Starred section helpers ──────────────────────────────────────────────────
-
-interface StarredItem {
-  starKey: string
+interface SidebarSectionProps {
+  icon: ReactNode
  label: string
-  icon?: React.ReactNode
-  path: string
-  type: 'application' | 'route' | 'agent' | 'routestat'
-  parentApp?: string
+  open: boolean
+  onToggle: () => void
+  active?: boolean
+  children: ReactNode
+  className?: string
 }

-function collectStarredItems(apps: SidebarApp[], starredIds: Set<string>): StarredItem[] {
-  const items: StarredItem[] = []
-
-  for (const app of apps) {
-    if (starredIds.has(app.id)) {
-      items.push({
-        starKey: app.id,
-        label: app.name,
-        icon: <StatusDot variant={app.health} />,
-        path: `/apps/${app.id}`,
-        type: 'application',
-      })
-    }
-    for (const route of app.routes) {
-      const key = `${app.id}:${route.id}`
-      if (starredIds.has(key)) {
-        items.push({
-          starKey: key,
-          label: route.name,
-          path: `/apps/${app.id}/${route.id}`,
-          type: 'route',
-          parentApp: app.name,
-        })
-      }
-    }
-    const agentsAppKey = `agents:${app.id}`
-    if (starredIds.has(agentsAppKey)) {
-      items.push({
-        starKey: agentsAppKey,
-        label: app.name,
-        icon: <StatusDot variant={app.health} />,
-        path: `/agents/${app.id}`,
-        type: 'agent',
-      })
-    }
-    for (const agent of app.agents) {
-      const key = `${app.id}:${agent.id}`
-      if (starredIds.has(key)) {
-        items.push({
-          starKey: key,
-          label: agent.name,
-          path: `/agents/${app.id}/${agent.id}`,
-          type: 'agent',
-          parentApp: app.name,
-        })
-      }
-    }
-    // Routes tree starred items
-    const routesAppKey = `routes:${app.id}`
-    if (starredIds.has(routesAppKey)) {
-      items.push({
-        starKey: routesAppKey,
-        label: app.name,
-        icon: <StatusDot variant={app.health} />,
-        path: `/routes/${app.id}`,
-        type: 'routestat',
-      })
-    }
-    for (const route of app.routes) {
-      const routeKey = `routes:${app.id}:${route.id}`
-      if (starredIds.has(routeKey)) {
-        items.push({
-          starKey: routeKey,
-          label: route.name,
-          path: `/routes/${app.id}/${route.id}`,
-          type: 'routestat',
-          parentApp: app.name,
-        })
-      }
-    }
-  }
-
-  return items
+interface SidebarFooterProps {
+  children: ReactNode
+  className?: string
 }

-// ── StarredGroup ─────────────────────────────────────────────────────────────
-
-function StarredGroup({
-  label,
-  items,
-  onNavigate,
-  onRemove,
-}: {
+interface SidebarFooterLinkProps {
+  icon: ReactNode
  label: string
-  items: StarredItem[]
-  onNavigate: (path: string) => void
-  onRemove: (starKey: string) => void
-}) {
+  active?: boolean
+  onClick?: () => void
+  className?: string
+}
+
+interface SidebarRootProps {
+  collapsed?: boolean
+  onCollapseToggle?: () => void
+  searchValue?: string
+  onSearchChange?: (query: string) => void
+  children: ReactNode
+  className?: string
+}
+
+// ── Sub-components ──────────────────────────────────────────────────────────
+
+function SidebarHeader({ logo, title, version, onClick, className }: SidebarHeaderProps) {
+  const { collapsed } = useSidebarContext()
+
  return (
-    <div className={styles.starredGroup}>
-      <div className={styles.starredGroupLabel}>{label}</div>
-      {items.map((item) => (
-        <div
-          key={item.starKey}
-          className={styles.starredItem}
-          onClick={() => onNavigate(item.path)}
-          role="button"
-          tabIndex={0}
-          onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') onNavigate(item.path) }}
-        >
-          {item.icon}
-          <div className={styles.starredItemInfo}>
-            <span className={styles.starredItemName}>{item.label}</span>
-            {item.parentApp && (
-              <span className={styles.starredItemContext}>{item.parentApp}</span>
-            )}
-          </div>
-          <button
-            className={styles.starredRemove}
-            onClick={(e) => { e.stopPropagation(); onRemove(item.starKey) }}
-            tabIndex={-1}
-            aria-label={`Remove ${item.label} from starred`}
-          >
-            <X size={12} />
-          </button>
+    <div
+      className={`${styles.logo} ${className ?? ''}`}
+      onClick={onClick}
+      style={onClick ? { cursor: 'pointer' } : undefined}
+      role={onClick ? 'button' : undefined}
+      tabIndex={onClick ? 0 : undefined}
+      onKeyDown={onClick ? (e) => { if (e.key === 'Enter' || e.key === ' ') onClick() } : undefined}
+    >
+      {logo}
+      {!collapsed && (
+        <div>
+          <span className={styles.brand}>{title}</span>
+          {version && <span className={styles.version}>{version}</span>}
        </div>
-      ))}
+      )}
    </div>
  )
 }

-// ── Sidebar ──────────────────────────────────────────────────────────────────
+function SidebarSection({
+  icon,
+  label,
+  open,
+  onToggle,
+  active,
+  children,
+  className,
+}: SidebarSectionProps) {
+  const { collapsed, onCollapseToggle } = useSidebarContext()

-export function Sidebar({ apps, className, onNavigate }: SidebarProps) {
-  const [search, setSearch] = useState('')
-  const [appsCollapsed, _setAppsCollapsed] = useState(() => localStorage.getItem('cameleer:sidebar:apps-collapsed') === 'true')
-  const [agentsCollapsed, _setAgentsCollapsed] = useState(() => localStorage.getItem('cameleer:sidebar:agents-collapsed') === 'true')
-  const [routesCollapsed, _setRoutesCollapsed] = useState(() => localStorage.getItem('cameleer:sidebar:routes-collapsed') === 'true')
-
-  const setAppsCollapsed = (updater: (v: boolean) => boolean) => {
-    _setAppsCollapsed((prev) => {
-      const next = updater(prev)
-      localStorage.setItem('cameleer:sidebar:apps-collapsed', String(next))
-      return next
-    })
-  }
-
-  const setAgentsCollapsed = (updater: (v: boolean) => boolean) => {
-    _setAgentsCollapsed((prev) => {
-      const next = updater(prev)
-      localStorage.setItem('cameleer:sidebar:agents-collapsed', String(next))
-      return next
-    })
-  }
-
-  const setRoutesCollapsed = (updater: (v: boolean) => boolean) => {
-    _setRoutesCollapsed((prev) => {
-      const next = updater(prev)
-      localStorage.setItem('cameleer:sidebar:routes-collapsed', String(next))
-      return next
-    })
-  }
-  const routerNavigate = useNavigate()
-  const nav = onNavigate ?? routerNavigate
-  const location = useLocation()
-  const { starredIds, isStarred, toggleStar } = useStarred()
-
-  // Build tree data
-  const appNodes = useMemo(() => buildAppTreeNodes(apps), [apps])
-  const agentNodes = useMemo(() => buildAgentTreeNodes(apps), [apps])
-  const routeNodes = useMemo(() => buildRouteTreeNodes(apps), [apps])
-
-  // Sidebar reveal from Cmd-K navigation (passed via location state)
-  const sidebarRevealPath = (location.state as { sidebarReveal?: string } | null)?.sidebarReveal ?? null
-
-  useEffect(() => {
-    if (!sidebarRevealPath) return
-
-    // Uncollapse Applications section if reveal path matches an apps tree node
-    const matchesAppTree = appNodes.some((node) =>
-      node.path === sidebarRevealPath || node.children?.some((child) => child.path === sidebarRevealPath),
+  // In icon-rail (collapsed) mode, render a centered icon with tooltip
+  if (collapsed) {
+    return (
+      <div
+        className={`${styles.sectionRailItem} ${active ? styles.sectionRailItemActive : ''} ${className ?? ''}`}
+        title={label}
+        onClick={() => {
+          // Expand sidebar and open the section
+          onCollapseToggle?.()
+          onToggle()
+        }}
+        role="button"
+        tabIndex={0}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            onCollapseToggle?.()
+            onToggle()
+          }
+        }}
+      >
+        <span className={styles.sectionIcon}>{icon}</span>
+      </div>
    )
-    if (matchesAppTree && appsCollapsed) {
-      _setAppsCollapsed(false)
-      localStorage.setItem('cameleer:sidebar:apps-collapsed', 'false')
-    }
-
-    // Uncollapse Agents section if reveal path matches an agents tree node
-    const matchesAgentTree = agentNodes.some((node) =>
-      node.path === sidebarRevealPath || node.children?.some((child) => child.path === sidebarRevealPath),
-    )
-    if (matchesAgentTree && agentsCollapsed) {
-      _setAgentsCollapsed(false)
-      localStorage.setItem('cameleer:sidebar:agents-collapsed', 'false')
-    }
-  }, [sidebarRevealPath]) // eslint-disable-line react-hooks/exhaustive-deps
-
-  // Build starred items
-  const starredItems = useMemo(
-    () => collectStarredItems(apps, starredIds),
-    [apps, starredIds],
-  )
-
-  const starredApps = starredItems.filter((i) => i.type === 'application')
-  const starredRoutes = starredItems.filter((i) => i.type === 'route')
-  const starredAgents = starredItems.filter((i) => i.type === 'agent')
-  const starredRouteStats = starredItems.filter((i) => i.type === 'routestat')
-  const hasStarred = starredItems.length > 0
-
-  // For exchange detail pages, use the reveal path for sidebar selection so
-  // the parent route is highlighted (exchanges have no sidebar entry of their own)
-  const effectiveSelectedPath = location.pathname.startsWith('/exchanges/') && sidebarRevealPath
-    ? sidebarRevealPath
-    : location.pathname
+  }

  return (
-    <aside className={`${styles.sidebar} ${className ?? ''}`}>
-      {/* Logo */}
-      <div className={styles.logo} onClick={() => nav('/apps')} style={{ cursor: 'pointer' }}>
-        <img src={camelLogoUrl} alt="" aria-hidden="true" className={styles.logoImg} />
-        <div>
-          <span className={styles.brand}>cameleer</span>
-          <span className={styles.version}>v3.2.1</span>
-        </div>
+    <div className={`${styles.treeSection} ${active ? styles.treeSectionActive : ''} ${className ?? ''}`}>
+      <div
+        className={styles.treeSectionToggle}
+        onClick={onToggle}
+        role="button"
+        tabIndex={0}
+        aria-expanded={open}
+        aria-label={open ? `Collapse ${label}` : `Expand ${label}`}
+        onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); onToggle() } }}
+      >
+        {icon && <span className={styles.sectionIcon}>{icon}</span>}
+        <span className={styles.treeSectionLabel}>{label}</span>
      </div>
-
-      {/* Search */}
-      <div className={styles.searchWrap}>
-        <div className={styles.searchInner}>
-          <span className={styles.searchIcon} aria-hidden="true">
-            <Search size={12} />
-          </span>
-          <input
-            className={styles.searchInput}
-            type="text"
-            placeholder="Filter..."
-            value={search}
-            onChange={(e) => setSearch(e.target.value)}
-          />
-          {search && (
-            <button
-              type="button"
-              className={styles.searchClear}
-              onClick={() => setSearch('')}
-              aria-label="Clear search"
-            >
-              <X size={12} />
-            </button>
-          )}
-        </div>
-      </div>
-
-      {/* Navigation (scrollable) — includes starred section */}
-      <div className={styles.navArea}>
-        <div className={styles.section}>Navigation</div>
-
-        {/* Applications tree (collapsible, label navigates to /apps) */}
-        <div className={styles.treeSection}>
-          <div className={styles.treeSectionToggle}>
-            <button
-              className={styles.treeSectionChevronBtn}
-              onClick={() => setAppsCollapsed((v) => !v)}
-              aria-expanded={!appsCollapsed}
-              aria-label={appsCollapsed ? 'Expand Applications' : 'Collapse Applications'}
-            >
-              {appsCollapsed ? <ChevronRight size={12} /> : <ChevronDown size={12} />}
-            </button>
-            <span
-              className={`${styles.treeSectionLabel} ${location.pathname === '/apps' ? styles.treeSectionLabelActive : ''}`}
-              onClick={() => nav('/apps')}
-              role="button"
-              tabIndex={0}
-              onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') nav('/apps') }}
-            >
-              Applications
-            </span>
-          </div>
-          {!appsCollapsed && (
-            <SidebarTree
-              nodes={appNodes}
-              selectedPath={effectiveSelectedPath}
-              isStarred={isStarred}
-              onToggleStar={toggleStar}
-              filterQuery={search}
-              persistKey="cameleer:expanded:apps"
-              autoRevealPath={sidebarRevealPath}
-              onNavigate={onNavigate}
-            />
-          )}
-        </div>
-
-        {/* Agents tree (collapsible, label navigates to /agents) */}
-        <div className={styles.treeSection}>
-          <div className={styles.treeSectionToggle}>
-            <button
-              className={styles.treeSectionChevronBtn}
-              onClick={() => setAgentsCollapsed((v) => !v)}
-              aria-expanded={!agentsCollapsed}
-              aria-label={agentsCollapsed ? 'Expand Agents' : 'Collapse Agents'}
-            >
-              {agentsCollapsed ? <ChevronRight size={12} /> : <ChevronDown size={12} />}
-            </button>
-            <span
-              className={`${styles.treeSectionLabel} ${location.pathname.startsWith('/agents') ? styles.treeSectionLabelActive : ''}`}
-              onClick={() => nav('/agents')}
-              role="button"
-              tabIndex={0}
-              onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') nav('/agents') }}
-            >
-              Agents
-            </span>
-          </div>
-          {!agentsCollapsed && (
-            <SidebarTree
-              nodes={agentNodes}
-              selectedPath={effectiveSelectedPath}
-              isStarred={isStarred}
-              onToggleStar={toggleStar}
-              filterQuery={search}
-              persistKey="cameleer:expanded:agents"
-              autoRevealPath={sidebarRevealPath}
-              onNavigate={onNavigate}
-            />
-          )}
-        </div>
-
-        {/* Routes tree (collapsible, label navigates to /routes) */}
-        <div className={styles.treeSection}>
-          <div className={styles.treeSectionToggle}>
-            <button
-              className={styles.treeSectionChevronBtn}
-              onClick={() => setRoutesCollapsed((v) => !v)}
-              aria-expanded={!routesCollapsed}
-              aria-label={routesCollapsed ? 'Expand Routes' : 'Collapse Routes'}
-            >
-              {routesCollapsed ? <ChevronRight size={12} /> : <ChevronDown size={12} />}
-            </button>
-            <span
-              className={`${styles.treeSectionLabel} ${location.pathname === '/routes' ? styles.treeSectionLabelActive : ''}`}
-              onClick={() => nav('/routes')}
-              role="button"
-              tabIndex={0}
-              onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') nav('/routes') }}
-            >
-              Routes
-            </span>
-          </div>
-          {!routesCollapsed && (
-            <SidebarTree
-              nodes={routeNodes}
-              selectedPath={effectiveSelectedPath}
-              isStarred={isStarred}
-              onToggleStar={toggleStar}
-              filterQuery={search}
-              persistKey="cameleer:expanded:routes"
-              autoRevealPath={sidebarRevealPath}
-              onNavigate={onNavigate}
-            />
-          )}
-        </div>
-
-        {/* No results message */}
-        {search && appNodes.length === 0 && agentNodes.length === 0 && (
-          <div className={styles.noResults}>No results</div>
-        )}
-
-        {/* Starred section (inside scrollable area, hidden when empty) */}
-        {hasStarred && (
-          <div className={styles.starredSection}>
-            <div className={styles.section}>
-              <span className={styles.starredHeader}>★ Starred</span>
-            </div>
-            <div className={styles.starredList}>
-              {starredApps.length > 0 && (
-                <StarredGroup
-                  label="Applications"
-                  items={starredApps}
-                  onNavigate={nav}
-                  onRemove={toggleStar}
-                />
-              )}
-              {starredRoutes.length > 0 && (
-                <StarredGroup
-                  label="Routes"
-                  items={starredRoutes}
-                  onNavigate={nav}
-                  onRemove={toggleStar}
-                />
-              )}
-              {starredAgents.length > 0 && (
-                <StarredGroup
-                  label="Agents"
-                  items={starredAgents}
-                  onNavigate={nav}
-                  onRemove={toggleStar}
-                />
-              )}
-              {starredRouteStats.length > 0 && (
-                <StarredGroup
-                  label="Routes"
-                  items={starredRouteStats}
-                  onNavigate={nav}
-                  onRemove={toggleStar}
-                />
-              )}
-            </div>
-          </div>
-        )}
-      </div>
-
-      {/* Bottom links */}
-      <div className={styles.bottom}>
-        <div
-          className={[
-            styles.bottomItem,
-            location.pathname.startsWith('/admin') ? styles.bottomItemActive : '',
-          ].filter(Boolean).join(' ')}
-          onClick={() => nav('/admin')}
-          role="button"
-          tabIndex={0}
-          onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') nav('/admin') }}
-        >
-          <span className={styles.bottomIcon}><Settings size={14} /></span>
-          <div className={styles.itemInfo}>
-            <div className={styles.itemName}>Admin</div>
-          </div>
-        </div>
-        <div
-          className={[
-            styles.bottomItem,
-            location.pathname === '/api-docs' ? styles.bottomItemActive : '',
-          ].filter(Boolean).join(' ')}
-          onClick={() => nav('/api-docs')}
-          role="button"
-          tabIndex={0}
-          onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') nav('/api-docs') }}
-        >
-          <span className={styles.bottomIcon}><FileText size={14} /></span>
-          <div className={styles.itemInfo}>
-            <div className={styles.itemName}>API Docs</div>
-          </div>
-        </div>
-      </div>
-    </aside>
+      {open && children}
+    </div>
  )
 }

+function SidebarFooter({ children, className }: SidebarFooterProps) {
+  return (
+    <div className={`${styles.bottom} ${className ?? ''}`}>
+      {children}
+    </div>
+  )
+}
+
+function SidebarFooterLink({ icon, label, active, onClick, className }: SidebarFooterLinkProps) {
+  const { collapsed } = useSidebarContext()
+
+  return (
+    <div
+      className={[
+        styles.bottomItem,
+        active ? styles.bottomItemActive : '',
+        className ?? '',
+      ].filter(Boolean).join(' ')}
+      onClick={onClick}
+      role="button"
+      tabIndex={0}
+      title={collapsed ? label : undefined}
+      onKeyDown={onClick ? (e) => { if (e.key === 'Enter' || e.key === ' ') onClick() } : undefined}
+    >
+      <span className={styles.bottomIcon}>{icon}</span>
+      {!collapsed && (
+        <div className={styles.itemInfo}>
+          <div className={styles.itemName}>{label}</div>
+        </div>
+      )}
+    </div>
+  )
+}
+
+// ── Root component ──────────────────────────────────────────────────────────
+
+function SidebarRoot({
+  collapsed = false,
+  onCollapseToggle,
+  searchValue,
+  onSearchChange,
+  children,
+  className,
+}: SidebarRootProps) {
+  return (
+    <SidebarContext.Provider value={{ collapsed, onCollapseToggle }}>
+      <aside
+        className={[
+          styles.sidebar,
+          collapsed ? styles.sidebarCollapsed : '',
+          className ?? '',
+        ].filter(Boolean).join(' ')}
+      >
+        {/* Collapse toggle */}
+        {onCollapseToggle && (
+          <button
+            className={styles.collapseToggle}
+            onClick={onCollapseToggle}
+            aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+          >
+            {collapsed ? <ChevronsRight size={14} /> : <ChevronsLeft size={14} />}
+          </button>
+        )}
+
+        {/* Render Header first, then search, then remaining children */}
+        {(() => {
+          const childArray = Children.toArray(children)
+          const headerIdx = childArray.findIndex(
+            (child) => isValidElement(child) && child.type === SidebarHeader,
+          )
+          const header = headerIdx >= 0 ? childArray[headerIdx] : null
+          const rest = headerIdx >= 0
+            ? [...childArray.slice(0, headerIdx), ...childArray.slice(headerIdx + 1)]
+            : childArray
+
+          return (
+            <>
+              {header}
+              {onSearchChange && !collapsed && (
+                <div className={styles.searchWrap}>
+                  <div className={styles.searchInner}>
+                    <span className={styles.searchIcon} aria-hidden="true">
+                      <Search size={12} />
+                    </span>
+                    <input
+                      className={styles.searchInput}
+                      type="text"
+                      placeholder="Filter..."
+                      value={searchValue ?? ''}
+                      onChange={(e) => onSearchChange(e.target.value)}
+                    />
+                    {searchValue && (
+                      <button
+                        type="button"
+                        className={styles.searchClear}
+                        onClick={() => onSearchChange('')}
+                        aria-label="Clear search"
+                      >
+                        <X size={12} />
+                      </button>
+                    )}
+                  </div>
+                </div>
+              )}
+              {rest}
+            </>
+          )
+        })()}
+      </aside>
+    </SidebarContext.Provider>
+  )
+}
+
+// ── Compound export ─────────────────────────────────────────────────────────
+
+export const Sidebar = Object.assign(SidebarRoot, {
+  Header: SidebarHeader,
+  Section: SidebarSection,
+  Footer: SidebarFooter,
+  FooterLink: SidebarFooterLink,
+})
--- a/src/design-system/layout/Sidebar/SidebarContext.ts
+++ b/src/design-system/layout/Sidebar/SidebarContext.ts
@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react'
+
+export interface SidebarContextValue {
+  collapsed: boolean
+  onCollapseToggle?: () => void
+}
+
+export const SidebarContext = createContext<SidebarContextValue>({
+  collapsed: false,
+})
+
+export function useSidebarContext(): SidebarContextValue {
+  return useContext(SidebarContext)
+}
--- a/src/design-system/layout/Sidebar/SidebarTree.tsx
+++ b/src/design-system/layout/Sidebar/SidebarTree.tsx
@@ -124,6 +124,52 @@ function filterNodes(
  return { filtered: walk(nodes), matchedParentIds }
 }

+// ── Keyboard nav helpers ─────────────────────────────────────────────────────
+
+function handleArrowDown(visibleNodes: FlatNode[], currentIndex: number, focusNode: (id: string) => void) {
+  const next = visibleNodes[currentIndex + 1]
+  if (next) focusNode(next.node.id)
+}
+
+function handleArrowUp(visibleNodes: FlatNode[], currentIndex: number, focusNode: (id: string) => void) {
+  const prev = visibleNodes[currentIndex - 1]
+  if (prev) focusNode(prev.node.id)
+}
+
+function handleArrowRight(
+  current: FlatNode | undefined,
+  currentIndex: number,
+  expandedSet: Set<string>,
+  visibleNodes: FlatNode[],
+  handleToggle: (id: string) => void,
+  focusNode: (id: string) => void,
+) {
+  if (!current) return
+  const hasChildren = current.node.children && current.node.children.length > 0
+  if (!hasChildren) return
+  if (!expandedSet.has(current.node.id)) {
+    handleToggle(current.node.id)
+  } else {
+    const next = visibleNodes[currentIndex + 1]
+    if (next) focusNode(next.node.id)
+  }
+}
+
+function handleArrowLeft(
+  current: FlatNode | undefined,
+  expandedSet: Set<string>,
+  handleToggle: (id: string) => void,
+  focusNode: (id: string) => void,
+) {
+  if (!current) return
+  const hasChildren = current.node.children && current.node.children.length > 0
+  if (hasChildren && expandedSet.has(current.node.id)) {
+    handleToggle(current.node.id)
+  } else if (current.parentId !== null) {
+    focusNode(current.parentId)
+  }
+}
+
 // ── SidebarTree ──────────────────────────────────────────────────────────────

 export function SidebarTree({
@@ -222,64 +268,13 @@ export function SidebarTree({
      const current = visibleNodes[currentIndex]

      switch (e.key) {
-        case 'ArrowDown': {
-          e.preventDefault()
-          const next = visibleNodes[currentIndex + 1]
-          if (next) focusNode(next.node.id)
-          break
-        }
-        case 'ArrowUp': {
-          e.preventDefault()
-          const prev = visibleNodes[currentIndex - 1]
-          if (prev) focusNode(prev.node.id)
-          break
-        }
-        case 'ArrowRight': {
-          e.preventDefault()
-          if (!current) break
-          const hasChildren = current.node.children && current.node.children.length > 0
-          if (hasChildren) {
-            if (!expandedSet.has(current.node.id)) {
-              handleToggle(current.node.id)
-            } else {
-              const next = visibleNodes[currentIndex + 1]
-              if (next) focusNode(next.node.id)
-            }
-          }
-          break
-        }
-        case 'ArrowLeft': {
-          e.preventDefault()
-          if (!current) break
-          const hasChildren = current.node.children && current.node.children.length > 0
-          if (hasChildren && expandedSet.has(current.node.id)) {
-            handleToggle(current.node.id)
-          } else if (current.parentId !== null) {
-            focusNode(current.parentId)
-          }
-          break
-        }
-        case 'Enter': {
-          e.preventDefault()
-          if (current?.node.path) {
-            navigate(current.node.path)
-          }
-          break
-        }
-        case 'Home': {
-          e.preventDefault()
-          if (visibleNodes.length > 0) {
-            focusNode(visibleNodes[0].node.id)
-          }
-          break
-        }
-        case 'End': {
-          e.preventDefault()
-          if (visibleNodes.length > 0) {
-            focusNode(visibleNodes[visibleNodes.length - 1].node.id)
-          }
-          break
-        }
+        case 'ArrowDown': { e.preventDefault(); handleArrowDown(visibleNodes, currentIndex, focusNode); break }
+        case 'ArrowUp': { e.preventDefault(); handleArrowUp(visibleNodes, currentIndex, focusNode); break }
+        case 'ArrowRight': { e.preventDefault(); handleArrowRight(current, currentIndex, expandedSet, visibleNodes, handleToggle, focusNode); break }
+        case 'ArrowLeft': { e.preventDefault(); handleArrowLeft(current, expandedSet, handleToggle, focusNode); break }
+        case 'Enter': { e.preventDefault(); if (current?.node.path) navigate(current.node.path); break }
+        case 'Home': { e.preventDefault(); if (visibleNodes.length > 0) focusNode(visibleNodes[0].node.id); break }
+        case 'End': { e.preventDefault(); if (visibleNodes.length > 0) focusNode(visibleNodes[visibleNodes.length - 1].node.id); break }
      }
    },
    // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -371,6 +366,10 @@ function SidebarTreeRow({

  return (
    <li role="none">
+      {/* S1082: No onKeyDown here by design — the parent <ul role="tree"> carries
+          onKeyDown={handleKeyDown} which handles Enter (navigate) and all arrow keys
+          per the WAI-ARIA tree widget pattern. Adding a duplicate handler here would
+          fire the action twice. */}
      <div
        role="treeitem"
        aria-expanded={hasChildren ? isExpanded : undefined}
--- a/src/design-system/layout/TopBar/TopBar.module.css
+++ b/src/design-system/layout/TopBar/TopBar.module.css
@@ -153,14 +153,17 @@
 }

 .env {
+  display: flex;
+  align-items: center;
+  height: 30px;
+  padding: 4px 10px;
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  background: var(--bg-raised);
+  color: var(--text-muted);
  font-family: var(--font-mono);
  font-size: 10px;
  font-weight: 600;
-  padding: 3px 10px;
-  border-radius: 10px;
-  background: var(--success-bg);
-  color: var(--success);
-  border: 1px solid var(--success-border);
  text-transform: uppercase;
  letter-spacing: 0.5px;
 }
--- a/src/design-system/layout/TopBar/TopBar.tsx
+++ b/src/design-system/layout/TopBar/TopBar.tsx
@@ -1,3 +1,4 @@
+import { type ReactNode } from 'react'
 import { Search, Moon, Sun, Power } from 'lucide-react'
 import styles from './TopBar.module.css'
 import { Breadcrumb } from '../../composites/Breadcrumb/Breadcrumb'
@@ -14,7 +15,7 @@ import type { BreadcrumbItem } from '../../providers/BreadcrumbProvider'

 interface TopBarProps {
  breadcrumb: BreadcrumbItem[]
-  environment?: string
+  environment?: ReactNode
  user?: { name: string }
  onLogout?: () => void
  className?: string
@@ -90,7 +91,7 @@ export function TopBar({
          title={globalFilters.autoRefresh ? 'Auto-refresh is on — click to pause' : 'Auto-refresh is paused — click to resume'}
        >
          <span className={styles.liveDot} />
-          {globalFilters.autoRefresh ? 'LIVE' : 'PAUSED'}
+          {globalFilters.autoRefresh ? 'AUTO' : 'MANUAL'}
        </button>
        <button
          className={styles.themeToggle}
@@ -102,7 +103,7 @@ export function TopBar({
          {theme === 'light' ? <Moon size={16} /> : <Sun size={16} />}
        </button>
        {environment && (
-          <span className={styles.env}>{environment}</span>
+          <div className={styles.env}>{environment}</div>
        )}
        {user && (
          <Dropdown
--- a/src/design-system/layout/index.ts
+++ b/src/design-system/layout/index.ts
@@ -1,4 +1,6 @@
 export { AppShell } from './AppShell/AppShell'
 export { Sidebar } from './Sidebar/Sidebar'
-export type { SidebarApp, SidebarRoute, SidebarAgent } from './Sidebar/Sidebar'
+export { SidebarTree } from './Sidebar/SidebarTree'
+export type { SidebarTreeNode } from './Sidebar/SidebarTree'
+export { useStarred } from './Sidebar/useStarred'
 export { TopBar } from './TopBar/TopBar'
--- a/src/design-system/primitives/InlineEdit/InlineEdit.tsx
+++ b/src/design-system/primitives/InlineEdit/InlineEdit.tsx
@@ -59,7 +59,15 @@ export function InlineEdit({ value, onSave, placeholder, disabled, className }:
    <span className={`${styles.display} ${disabled ? styles.disabled : ''} ${className ?? ''}`}>
      <span
        className={isEmpty ? styles.placeholder : styles.value}
+        role="button"
+        tabIndex={disabled ? undefined : 0}
        onClick={startEdit}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault()
+            startEdit()
+          }
+        }}
      >
        {isEmpty ? placeholder : value}
      </span>
--- a/src/design-system/providers/GlobalFilterProvider.tsx
+++ b/src/design-system/providers/GlobalFilterProvider.tsx
@@ -12,6 +12,7 @@ export type ExchangeStatus = 'completed' | 'failed' | 'running' | 'warning'
 interface GlobalFilterContextValue {
  timeRange: TimeRange
  setTimeRange: (range: TimeRange) => void
+  refreshTimeRange: () => void
  statusFilters: Set<ExchangeStatus>
  toggleStatus: (status: ExchangeStatus) => void
  clearStatusFilters: () => void
@@ -76,6 +77,14 @@ export function GlobalFilterProvider({ children }: { children: ReactNode }) {
    return () => clearInterval(id)
  }, [autoRefresh, timeRange.preset])

+  // Recompute time range from preset on demand (for manual refresh in PAUSED mode)
+  const refreshTimeRange = useCallback(() => {
+    if (timeRange.preset) {
+      const { start, end } = computePresetRange(timeRange.preset)
+      setTimeRangeState({ start, end, preset: timeRange.preset })
+    }
+  }, [timeRange.preset])
+
  const isInTimeRange = useCallback(
    (timestamp: Date) => {
      if (timeRange.preset) {
@@ -90,7 +99,7 @@ export function GlobalFilterProvider({ children }: { children: ReactNode }) {

  return (
    <GlobalFilterContext.Provider
-      value={{ timeRange, setTimeRange, statusFilters, toggleStatus, clearStatusFilters, isInTimeRange, autoRefresh, setAutoRefresh }}
+      value={{ timeRange, setTimeRange, refreshTimeRange, statusFilters, toggleStatus, clearStatusFilters, isInTimeRange, autoRefresh, setAutoRefresh }}
    >
      {children}
    </GlobalFilterContext.Provider>
--- a/src/layout/LayoutShell.tsx
+++ b/src/layout/LayoutShell.tsx
@@ -0,0 +1,451 @@
+import { useState, useEffect, useMemo, type ReactNode } from 'react'
+import { Outlet, useLocation, useNavigate } from 'react-router-dom'
+import { Box, Cpu, GitBranch, Settings, FileText, ChevronRight, X } from 'lucide-react'
+import { AppShell } from '../design-system/layout/AppShell/AppShell'
+import { Sidebar } from '../design-system/layout/Sidebar/Sidebar'
+import { SidebarTree } from '../design-system/layout/Sidebar/SidebarTree'
+import type { SidebarTreeNode } from '../design-system/layout/Sidebar/SidebarTree'
+import { useStarred } from '../design-system/layout/Sidebar/useStarred'
+import { StatusDot } from '../design-system/primitives/StatusDot/StatusDot'
+import { SIDEBAR_APPS } from '../mocks/sidebar'
+import type { SidebarApp } from '../mocks/sidebar'
+import camelLogoUrl from '../assets/camel-logo.svg'
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function formatCount(n: number): string {
+  if (n >= 1000) return `${(n / 1000).toFixed(1)}k`
+  return String(n)
+}
+
+// ── Tree node builders ──────────────────────────────────────────────────────
+
+function buildAppTreeNodes(apps: SidebarApp[]): SidebarTreeNode[] {
+  return apps.map((app) => ({
+    id: app.id,
+    label: app.name,
+    icon: <StatusDot status={app.health} />,
+    badge: formatCount(app.exchangeCount),
+    path: `/apps/${app.id}`,
+    starrable: true,
+    starKey: `app:${app.id}`,
+    children: app.routes.map((route) => ({
+      id: `${app.id}/${route.id}`,
+      label: route.name,
+      icon: <ChevronRight size={12} />,
+      badge: formatCount(route.exchangeCount),
+      path: `/apps/${app.id}/${route.id}`,
+    })),
+  }))
+}
+
+function buildRouteTreeNodes(apps: SidebarApp[]): SidebarTreeNode[] {
+  return apps
+    .filter((app) => app.routes.length > 0)
+    .map((app) => ({
+      id: `routes:${app.id}`,
+      label: app.name,
+      icon: <StatusDot status={app.health} />,
+      badge: `${app.routes.length} route${app.routes.length !== 1 ? 's' : ''}`,
+      path: `/routes/${app.id}`,
+      starrable: true,
+      starKey: `routestat:${app.id}`,
+      children: app.routes.map((route) => ({
+        id: `routes:${app.id}/${route.id}`,
+        label: route.name,
+        icon: <ChevronRight size={12} />,
+        badge: formatCount(route.exchangeCount),
+        path: `/routes/${app.id}/${route.id}`,
+      })),
+    }))
+}
+
+function buildAgentTreeNodes(apps: SidebarApp[]): SidebarTreeNode[] {
+  return apps
+    .filter((app) => app.agents.length > 0)
+    .map((app) => {
+      const liveCount = app.agents.filter((a) => a.status === 'live').length
+      return {
+        id: `agents:${app.id}`,
+        label: app.name,
+        icon: <StatusDot status={app.health} />,
+        badge: `${liveCount}/${app.agents.length} live`,
+        path: `/agents/${app.id}`,
+        starrable: true,
+        starKey: `agent:${app.id}`,
+        children: app.agents.map((agent) => ({
+          id: `agents:${app.id}/${agent.id}`,
+          label: agent.name,
+          icon: <StatusDot status={agent.status} />,
+          badge: `${agent.tps} tps`,
+          path: `/agents/${app.id}/${agent.id}`,
+        })),
+      }
+    })
+}
+
+// ── Starred items ───────────────────────────────────────────────────────────
+
+interface StarredItem {
+  starKey: string
+  label: string
+  icon?: ReactNode
+  path: string
+  type: 'application' | 'route' | 'agent' | 'routestat'
+  parentApp?: string
+}
+
+function collectStarredItems(
+  apps: SidebarApp[],
+  starredIds: Set<string>,
+): StarredItem[] {
+  const items: StarredItem[] = []
+
+  for (const app of apps) {
+    if (starredIds.has(`app:${app.id}`)) {
+      items.push({
+        starKey: `app:${app.id}`,
+        label: app.name,
+        icon: <Box size={12} />,
+        path: `/apps/${app.id}`,
+        type: 'application',
+      })
+    }
+
+    for (const route of app.routes) {
+      if (starredIds.has(`route:${app.id}/${route.id}`)) {
+        items.push({
+          starKey: `route:${app.id}/${route.id}`,
+          label: route.name,
+          icon: <ChevronRight size={12} />,
+          path: `/apps/${app.id}/${route.id}`,
+          type: 'route',
+          parentApp: app.name,
+        })
+      }
+    }
+
+    if (starredIds.has(`routestat:${app.id}`)) {
+      items.push({
+        starKey: `routestat:${app.id}`,
+        label: app.name,
+        icon: <GitBranch size={12} />,
+        path: `/routes/${app.id}`,
+        type: 'routestat',
+      })
+    }
+
+    if (starredIds.has(`agent:${app.id}`)) {
+      items.push({
+        starKey: `agent:${app.id}`,
+        label: app.name,
+        icon: <Cpu size={12} />,
+        path: `/agents/${app.id}`,
+        type: 'agent',
+      })
+    }
+  }
+
+  return items
+}
+
+// ── Starred group component ─────────────────────────────────────────────────
+
+interface StarredGroupProps {
+  label: string
+  items: StarredItem[]
+  onRemove: (starKey: string) => void
+  onNavigate: (path: string) => void
+}
+
+function StarredGroup({ label, items, onRemove, onNavigate }: StarredGroupProps) {
+  if (items.length === 0) return null
+
+  return (
+    <div style={{ marginBottom: 8 }}>
+      <div
+        style={{
+          fontSize: 10,
+          fontWeight: 600,
+          textTransform: 'uppercase',
+          letterSpacing: '0.05em',
+          color: 'var(--text-tertiary)',
+          padding: '4px 12px',
+        }}
+      >
+        {label}
+      </div>
+      {items.map((item) => (
+        <div
+          key={item.starKey}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 8,
+            padding: '4px 12px',
+            cursor: 'pointer',
+            fontSize: 12,
+            color: 'var(--text-secondary)',
+            borderRadius: 4,
+          }}
+          onClick={() => onNavigate(item.path)}
+          role="button"
+          tabIndex={0}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') onNavigate(item.path)
+          }}
+        >
+          {item.icon && (
+            <span style={{ display: 'flex', alignItems: 'center', color: 'var(--text-tertiary)' }}>
+              {item.icon}
+            </span>
+          )}
+          <span style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+            {item.label}
+            {item.parentApp && (
+              <span style={{ color: 'var(--text-tertiary)', marginLeft: 4, fontSize: 10 }}>
+                {item.parentApp}
+              </span>
+            )}
+          </span>
+          <button
+            style={{
+              background: 'none',
+              border: 'none',
+              padding: 2,
+              cursor: 'pointer',
+              color: 'var(--text-tertiary)',
+              display: 'flex',
+              alignItems: 'center',
+              opacity: 0.6,
+            }}
+            onClick={(e) => {
+              e.stopPropagation()
+              onRemove(item.starKey)
+            }}
+            aria-label={`Remove ${item.label} from starred`}
+          >
+            <X size={10} />
+          </button>
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// ── localStorage-backed section collapse ────────────────────────────────────
+
+function usePersistedCollapse(key: string, defaultValue: boolean): [boolean, () => void] {
+  const [value, setValue] = useState(() => {
+    try {
+      const raw = localStorage.getItem(key)
+      if (raw !== null) return raw === 'true'
+    } catch { /* ignore */ }
+    return defaultValue
+  })
+
+  const toggle = () => {
+    setValue((prev) => {
+      const next = !prev
+      try {
+        localStorage.setItem(key, String(next))
+      } catch { /* ignore */ }
+      return next
+    })
+  }
+
+  return [value, toggle]
+}
+
+// ── LayoutShell ─────────────────────────────────────────────────────────────
+
+export function LayoutShell() {
+  const navigate = useNavigate()
+  const location = useLocation()
+  const { starredIds, isStarred, toggleStar } = useStarred()
+
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false)
+  const [filterQuery, setFilterQuery] = useState('')
+
+  // Section collapse state — persisted to localStorage
+  const [appsCollapsed, toggleAppsCollapsed] = usePersistedCollapse('cameleer:sidebar:apps-collapsed', false)
+  const [agentsCollapsed, toggleAgentsCollapsed] = usePersistedCollapse('cameleer:sidebar:agents-collapsed', false)
+  const [routesCollapsed, toggleRoutesCollapsed] = usePersistedCollapse('cameleer:sidebar:routes-collapsed', false)
+
+  // Tree data — static, so empty deps
+  const appNodes = useMemo(() => buildAppTreeNodes(SIDEBAR_APPS), [])
+  const agentNodes = useMemo(() => buildAgentTreeNodes(SIDEBAR_APPS), [])
+  const routeNodes = useMemo(() => buildRouteTreeNodes(SIDEBAR_APPS), [])
+
+  // Sidebar reveal from Cmd-K navigation
+  const sidebarRevealPath = (location.state as { sidebarReveal?: string } | null)?.sidebarReveal ?? null
+
+  // Auto-uncollapse matching sections when sidebarRevealPath changes
+  useEffect(() => {
+    if (!sidebarRevealPath) return
+
+    if (sidebarRevealPath.startsWith('/apps') && appsCollapsed) {
+      toggleAppsCollapsed()
+    }
+    if (sidebarRevealPath.startsWith('/agents') && agentsCollapsed) {
+      toggleAgentsCollapsed()
+    }
+    if (sidebarRevealPath.startsWith('/routes') && routesCollapsed) {
+      toggleRoutesCollapsed()
+    }
+  }, [sidebarRevealPath]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  const effectiveSelectedPath = sidebarRevealPath ?? location.pathname
+
+  // Starred items — collected and grouped
+  const allStarred = useMemo(
+    () => collectStarredItems(SIDEBAR_APPS, starredIds),
+    [starredIds],
+  )
+
+  const starredApps = allStarred.filter((s) => s.type === 'application')
+  const starredRoutes = allStarred.filter((s) => s.type === 'route')
+  const starredAgents = allStarred.filter((s) => s.type === 'agent')
+  const starredRouteStats = allStarred.filter((s) => s.type === 'routestat')
+  const hasStarred = allStarred.length > 0
+
+  const camelLogo = (
+    <img
+      src={camelLogoUrl}
+      alt=""
+      aria-hidden="true"
+      style={{
+        width: 28,
+        height: 24,
+        filter:
+          'brightness(0) saturate(100%) invert(76%) sepia(30%) saturate(400%) hue-rotate(5deg) brightness(95%)',
+      }}
+    />
+  )
+
+  return (
+    <AppShell
+      sidebar={
+        <Sidebar
+          collapsed={sidebarCollapsed}
+          onCollapseToggle={() => setSidebarCollapsed((c) => !c)}
+          searchValue={filterQuery}
+          onSearchChange={setFilterQuery}
+        >
+          <Sidebar.Header
+            logo={camelLogo}
+            title="cameleer"
+            version="v3.2.1"
+            onClick={() => navigate('/apps')}
+          />
+
+          <Sidebar.Section
+            label="Applications"
+            icon={<Box size={14} />}
+            open={!appsCollapsed}
+            onToggle={toggleAppsCollapsed}
+            active={location.pathname.startsWith('/apps')}
+          >
+            <SidebarTree
+              nodes={appNodes}
+              selectedPath={effectiveSelectedPath}
+              isStarred={isStarred}
+              onToggleStar={toggleStar}
+              filterQuery={filterQuery}
+              persistKey="cameleer:expanded:apps"
+              autoRevealPath={sidebarRevealPath}
+            />
+          </Sidebar.Section>
+
+          <Sidebar.Section
+            label="Agents"
+            icon={<Cpu size={14} />}
+            open={!agentsCollapsed}
+            onToggle={toggleAgentsCollapsed}
+            active={location.pathname.startsWith('/agents')}
+          >
+            <SidebarTree
+              nodes={agentNodes}
+              selectedPath={effectiveSelectedPath}
+              isStarred={isStarred}
+              onToggleStar={toggleStar}
+              filterQuery={filterQuery}
+              persistKey="cameleer:expanded:agents"
+              autoRevealPath={sidebarRevealPath}
+            />
+          </Sidebar.Section>
+
+          <Sidebar.Section
+            label="Routes"
+            icon={<GitBranch size={14} />}
+            open={!routesCollapsed}
+            onToggle={toggleRoutesCollapsed}
+            active={location.pathname.startsWith('/routes')}
+          >
+            <SidebarTree
+              nodes={routeNodes}
+              selectedPath={effectiveSelectedPath}
+              isStarred={isStarred}
+              onToggleStar={toggleStar}
+              filterQuery={filterQuery}
+              persistKey="cameleer:expanded:routes"
+              autoRevealPath={sidebarRevealPath}
+            />
+          </Sidebar.Section>
+
+          {hasStarred && (
+            <Sidebar.Section
+              label="\u2605 Starred"
+              icon={<span />}
+              open={true}
+              onToggle={() => {}}
+              active={false}
+            >
+              <StarredGroup
+                label="Applications"
+                items={starredApps}
+                onRemove={toggleStar}
+                onNavigate={navigate}
+              />
+              <StarredGroup
+                label="Routes"
+                items={starredRoutes}
+                onRemove={toggleStar}
+                onNavigate={navigate}
+              />
+              <StarredGroup
+                label="Route Stats"
+                items={starredRouteStats}
+                onRemove={toggleStar}
+                onNavigate={navigate}
+              />
+              <StarredGroup
+                label="Agents"
+                items={starredAgents}
+                onRemove={toggleStar}
+                onNavigate={navigate}
+              />
+            </Sidebar.Section>
+          )}
+
+          <Sidebar.Footer>
+            <Sidebar.FooterLink
+              icon={<Settings size={14} />}
+              label="Admin"
+              onClick={() => navigate('/admin')}
+              active={location.pathname.startsWith('/admin')}
+            />
+            <Sidebar.FooterLink
+              icon={<FileText size={14} />}
+              label="API Docs"
+              onClick={() => navigate('/api-docs')}
+              active={location.pathname === '/api-docs'}
+            />
+          </Sidebar.Footer>
+        </Sidebar>
+      }
+    >
+      <Outlet />
+    </AppShell>
+  )
+}
--- a/src/pages/Admin/Admin.tsx
+++ b/src/pages/Admin/Admin.tsx
@@ -1,9 +1,6 @@
 import { useNavigate, useLocation } from 'react-router-dom'
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'
 import { Tabs } from '../../design-system/composites/Tabs/Tabs'
-import { SIDEBAR_APPS } from '../../mocks/sidebar'
 import styles from './Admin.module.css'
 import type { ReactNode } from 'react'

@@ -23,7 +20,7 @@ export function AdminLayout({ title, children }: AdminLayoutProps) {
  const location = useLocation()

  return (
-    <AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>
+    <>
      <TopBar
        breadcrumb={[
          { label: 'Admin', href: '/admin' },
@@ -40,6 +37,6 @@ export function AdminLayout({ title, children }: AdminLayoutProps) {
      <div className={styles.adminContent}>
        {children}
      </div>
-    </AppShell>
+    </>
  )
 }
--- a/src/pages/AgentHealth/AgentHealth.tsx
+++ b/src/pages/AgentHealth/AgentHealth.tsx
@@ -4,8 +4,6 @@ import { ChevronRight } from 'lucide-react'
 import styles from './AgentHealth.module.css'

 // Layout
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'

 // Composites
@@ -28,7 +26,6 @@ import { useGlobalFilters } from '../../design-system/providers/GlobalFilterProv

 // Mock data
 import { agents, type AgentHealth as AgentHealthData } from '../../mocks/agents'
-import { SIDEBAR_APPS } from '../../mocks/sidebar'
 import { agentEvents } from '../../mocks/agentEvents'

 // ── URL scope parsing ────────────────────────────────────────────────────────
@@ -317,19 +314,7 @@ export function AgentHealth() {
  const isFullWidth = scope.level !== 'all'

  return (
-    <AppShell
-      sidebar={<Sidebar apps={SIDEBAR_APPS} />}
-      detail={
-        selectedInstance ? (
-          <DetailPanel
-            open={panelOpen}
-            onClose={() => setPanelOpen(false)}
-            title={selectedInstance.name}
-            tabs={detailTabs}
-          />
-        ) : undefined
-      }
-    >
+    <>
      <TopBar
        breadcrumb={buildBreadcrumb(scope)}
        environment="PRODUCTION"
@@ -454,6 +439,16 @@ export function AgentHealth() {
          </div>
        )}
      </div>
-    </AppShell>
+
+      {/* Detail panel (portals itself) */}
+      {selectedInstance && (
+        <DetailPanel
+          open={panelOpen}
+          onClose={() => setPanelOpen(false)}
+          title={selectedInstance.name}
+          tabs={detailTabs}
+        />
+      )}
+    </>
  )
 }
--- a/src/pages/AgentInstance/AgentInstance.tsx
+++ b/src/pages/AgentInstance/AgentInstance.tsx
@@ -4,8 +4,6 @@ import { ChevronRight } from 'lucide-react'
 import styles from './AgentInstance.module.css'

 // Layout
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'

 // Composites
@@ -28,7 +26,6 @@ import { useGlobalFilters } from '../../design-system/providers/GlobalFilterProv

 // Data
 import { agents } from '../../mocks/agents'
-import { SIDEBAR_APPS } from '../../mocks/sidebar'
 import { agentEvents } from '../../mocks/agentEvents'

 import { useState } from 'react'
@@ -127,12 +124,12 @@ export function AgentInstance() {

  if (!agent) {
    return (
-      <AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>
+      <>
        <TopBar breadcrumb={[{ label: 'Agents', href: '/agents' }, { label: 'Not Found' }]} environment="PRODUCTION" user={{ name: 'hendrik' }} />
        <div className={styles.content}>
          <div className={styles.notFound}>Agent instance not found.</div>
        </div>
-      </AppShell>
+      </>
    )
  }

@@ -153,7 +150,7 @@ export function AgentInstance() {
  const statusColor = agent.status === 'live' ? 'success' : agent.status === 'stale' ? 'warning' : 'error'

  return (
-    <AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>
+    <>
      <TopBar
        breadcrumb={[
          { label: 'Applications', href: '/apps' },
@@ -302,6 +299,6 @@ export function AgentInstance() {
          </div>
        </div>
      </div>
-    </AppShell>
+    </>
  )
 }
--- a/src/pages/ApiDocs/ApiDocs.tsx
+++ b/src/pages/ApiDocs/ApiDocs.tsx
@@ -1,12 +1,9 @@
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'
 import { EmptyState } from '../../design-system/primitives/EmptyState/EmptyState'
-import { SIDEBAR_APPS } from '../../mocks/sidebar'

 export function ApiDocs() {
  return (
-    <AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>
+    <>
      <TopBar
        breadcrumb={[{ label: 'API Documentation' }]}
        environment="PRODUCTION"
@@ -17,6 +14,6 @@ export function ApiDocs() {
        title="API Documentation"
        description="API documentation coming soon."
      />
-    </AppShell>
+    </>
  )
 }
--- a/src/pages/AppDetail/AppDetail.tsx
+++ b/src/pages/AppDetail/AppDetail.tsx
@@ -1,15 +1,12 @@
 import { useParams } from 'react-router-dom'
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'
 import { EmptyState } from '../../design-system/primitives/EmptyState/EmptyState'
-import { SIDEBAR_APPS } from '../../mocks/sidebar'

 export function AppDetail() {
  const { id } = useParams<{ id: string }>()

  return (
-    <AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>
+    <>
      <TopBar
        breadcrumb={[
          { label: 'Applications', href: '/apps' },
@@ -23,6 +20,6 @@ export function AppDetail() {
        title="Application Detail"
        description="Application detail view coming soon."
      />
-    </AppShell>
+    </>
  )
 }
--- a/src/pages/Dashboard/Dashboard.tsx
+++ b/src/pages/Dashboard/Dashboard.tsx
@@ -4,8 +4,6 @@ import { TrendingUp, TrendingDown, ArrowRight, ExternalLink, AlertTriangle } fro
 import styles from './Dashboard.module.css'

 // Layout
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'

 // Composites
@@ -287,106 +285,7 @@ export function Dashboard() {
  const totalErrors = processorErrors.length + (hasExchangeError && processorErrors.length === 0 ? 1 : 0)

  return (
-    <AppShell
-      sidebar={
-        <Sidebar apps={SIDEBAR_APPS} />
-      }
-      detail={
-        selectedExchange ? (
-          <DetailPanel
-            open={panelOpen}
-            onClose={() => setPanelOpen(false)}
-            title={`${selectedExchange.orderId} — ${selectedExchange.route}`}
-          >
-            {/* Link to full detail page */}
-            <div className={styles.panelSection}>
-              <button
-                className={styles.openDetailLink}
-                onClick={() => navigate(`/exchanges/${selectedExchange.id}`)}
-              >
-                Open full details <ArrowRight size={14} style={{ verticalAlign: 'middle' }} />
-              </button>
-            </div>
-
-            {/* Overview */}
-            <div className={styles.panelSection}>
-              <div className={styles.panelSectionTitle}>Overview</div>
-              <div className={styles.overviewGrid}>
-                <div className={styles.overviewRow}>
-                  <span className={styles.overviewLabel}>Status</span>
-                  <span className={styles.statusCell}>
-                    <StatusDot variant={statusToVariant(selectedExchange.status)} />
-                    <span>{statusLabel(selectedExchange.status)}</span>
-                  </span>
-                </div>
-                <div className={styles.overviewRow}>
-                  <span className={styles.overviewLabel}>Duration</span>
-                  <MonoText size="sm">{formatDuration(selectedExchange.durationMs)}</MonoText>
-                </div>
-                <div className={styles.overviewRow}>
-                  <span className={styles.overviewLabel}>Route</span>
-                  <span>{selectedExchange.route}</span>
-                </div>
-                <div className={styles.overviewRow}>
-                  <span className={styles.overviewLabel}>Customer</span>
-                  <MonoText size="sm">{selectedExchange.customer}</MonoText>
-                </div>
-                <div className={styles.overviewRow}>
-                  <span className={styles.overviewLabel}>Agent</span>
-                  <MonoText size="sm">{selectedExchange.agent}</MonoText>
-                </div>
-                <div className={styles.overviewRow}>
-                  <span className={styles.overviewLabel}>Correlation</span>
-                  <MonoText size="xs">{selectedExchange.correlationId}</MonoText>
-                </div>
-                <div className={styles.overviewRow}>
-                  <span className={styles.overviewLabel}>Timestamp</span>
-                  <MonoText size="xs">{selectedExchange.timestamp.toISOString()}</MonoText>
-                </div>
-              </div>
-            </div>
-
-            {/* Errors */}
-            {totalErrors > 0 && (
-              <div className={styles.panelSection}>
-                <div className={styles.panelSectionTitle}>
-                  Errors
-                  {totalErrors > 1 && (
-                    <Badge label={`+${totalErrors - 1} more`} color="error" variant="outlined" />
-                  )}
-                </div>
-                <div className={styles.errorBlock}>
-                  <div className={styles.errorClass}>
-                    {selectedExchange.errorClass ?? processorErrors[0]?.name}
-                  </div>
-                  <div className={styles.errorMessage}>
-                    {selectedExchange.errorMessage ?? `Failed at processor: ${processorErrors[0]?.name}`}
-                  </div>
-                </div>
-              </div>
-            )}
-
-            {/* Route Flow */}
-            <div className={styles.panelSection}>
-              <div className={styles.panelSectionTitle}>Route Flow</div>
-              <RouteFlow nodes={routeNodes} />
-            </div>
-
-            {/* Processor Timeline */}
-            <div className={styles.panelSection}>
-              <div className={styles.panelSectionTitle}>
-                Processor Timeline
-                <span className={styles.panelSectionMeta}>{formatDuration(selectedExchange.durationMs)}</span>
-              </div>
-              <ProcessorTimeline
-                processors={selectedExchange.processors}
-                totalMs={selectedExchange.durationMs}
-              />
-            </div>
-          </DetailPanel>
-        ) : undefined
-      }
-    >
+    <>
      {/* Top bar */}
      <TopBar
        breadcrumb={
@@ -444,6 +343,101 @@ export function Dashboard() {

      {/* Shortcuts bar */}
      <ShortcutsBar shortcuts={SHORTCUTS} />
-    </AppShell>
+
+      {/* Detail panel (portals itself) */}
+      {selectedExchange && (
+        <DetailPanel
+          open={panelOpen}
+          onClose={() => setPanelOpen(false)}
+          title={`${selectedExchange.orderId} — ${selectedExchange.route}`}
+        >
+          {/* Link to full detail page */}
+          <div className={styles.panelSection}>
+            <button
+              className={styles.openDetailLink}
+              onClick={() => navigate(`/exchanges/${selectedExchange.id}`)}
+            >
+              Open full details <ArrowRight size={14} style={{ verticalAlign: 'middle' }} />
+            </button>
+          </div>
+
+          {/* Overview */}
+          <div className={styles.panelSection}>
+            <div className={styles.panelSectionTitle}>Overview</div>
+            <div className={styles.overviewGrid}>
+              <div className={styles.overviewRow}>
+                <span className={styles.overviewLabel}>Status</span>
+                <span className={styles.statusCell}>
+                  <StatusDot variant={statusToVariant(selectedExchange.status)} />
+                  <span>{statusLabel(selectedExchange.status)}</span>
+                </span>
+              </div>
+              <div className={styles.overviewRow}>
+                <span className={styles.overviewLabel}>Duration</span>
+                <MonoText size="sm">{formatDuration(selectedExchange.durationMs)}</MonoText>
+              </div>
+              <div className={styles.overviewRow}>
+                <span className={styles.overviewLabel}>Route</span>
+                <span>{selectedExchange.route}</span>
+              </div>
+              <div className={styles.overviewRow}>
+                <span className={styles.overviewLabel}>Customer</span>
+                <MonoText size="sm">{selectedExchange.customer}</MonoText>
+              </div>
+              <div className={styles.overviewRow}>
+                <span className={styles.overviewLabel}>Agent</span>
+                <MonoText size="sm">{selectedExchange.agent}</MonoText>
+              </div>
+              <div className={styles.overviewRow}>
+                <span className={styles.overviewLabel}>Correlation</span>
+                <MonoText size="xs">{selectedExchange.correlationId}</MonoText>
+              </div>
+              <div className={styles.overviewRow}>
+                <span className={styles.overviewLabel}>Timestamp</span>
+                <MonoText size="xs">{selectedExchange.timestamp.toISOString()}</MonoText>
+              </div>
+            </div>
+          </div>
+
+          {/* Errors */}
+          {totalErrors > 0 && (
+            <div className={styles.panelSection}>
+              <div className={styles.panelSectionTitle}>
+                Errors
+                {totalErrors > 1 && (
+                  <Badge label={`+${totalErrors - 1} more`} color="error" variant="outlined" />
+                )}
+              </div>
+              <div className={styles.errorBlock}>
+                <div className={styles.errorClass}>
+                  {selectedExchange.errorClass ?? processorErrors[0]?.name}
+                </div>
+                <div className={styles.errorMessage}>
+                  {selectedExchange.errorMessage ?? `Failed at processor: ${processorErrors[0]?.name}`}
+                </div>
+              </div>
+            </div>
+          )}
+
+          {/* Route Flow */}
+          <div className={styles.panelSection}>
+            <div className={styles.panelSectionTitle}>Route Flow</div>
+            <RouteFlow nodes={routeNodes} />
+          </div>
+
+          {/* Processor Timeline */}
+          <div className={styles.panelSection}>
+            <div className={styles.panelSectionTitle}>
+              Processor Timeline
+              <span className={styles.panelSectionMeta}>{formatDuration(selectedExchange.durationMs)}</span>
+            </div>
+            <ProcessorTimeline
+              processors={selectedExchange.processors}
+              totalMs={selectedExchange.durationMs}
+            />
+          </div>
+        </DetailPanel>
+      )}
+    </>
  )
 }
--- a/src/pages/ExchangeDetail/ExchangeDetail.tsx
+++ b/src/pages/ExchangeDetail/ExchangeDetail.tsx
@@ -3,8 +3,6 @@ import { useParams, useNavigate } from 'react-router-dom'
 import styles from './ExchangeDetail.module.css'

 // Layout
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'

 // Composites
@@ -22,7 +20,7 @@ import { InfoCallout } from '../../design-system/primitives/InfoCallout/InfoCall

 // Mock data
 import { exchanges } from '../../mocks/exchanges'
-import { SIDEBAR_APPS, buildRouteToAppMap } from '../../mocks/sidebar'
+import { buildRouteToAppMap } from '../../mocks/sidebar'

 const ROUTE_TO_APP = buildRouteToAppMap()

@@ -196,11 +194,7 @@ export function ExchangeDetail() {
  // Not found state
  if (!exchange) {
    return (
-      <AppShell
-        sidebar={
-          <Sidebar apps={SIDEBAR_APPS} />
-        }
-      >
+      <>
        <TopBar
          breadcrumb={[
            { label: 'Applications', href: '/apps' },
@@ -213,7 +207,7 @@ export function ExchangeDetail() {
        <div className={styles.content}>
          <InfoCallout variant="warning">Exchange "{id}" not found in mock data.</InfoCallout>
        </div>
-      </AppShell>
+      </>
    )
  }

@@ -229,11 +223,7 @@ export function ExchangeDetail() {
  const isSelectedFailed = selectedProc?.status === 'fail'

  return (
-    <AppShell
-      sidebar={
-        <Sidebar apps={SIDEBAR_APPS} />
-      }
-    >
+    <>
      {/* Top bar */}
      <TopBar
        breadcrumb={[
@@ -454,6 +444,6 @@ export function ExchangeDetail() {
        )}

      </div>
-    </AppShell>
+    </>
  )
 }
--- a/src/pages/Inventory/Inventory.tsx
+++ b/src/pages/Inventory/Inventory.tsx
@@ -3,6 +3,7 @@ import styles from './Inventory.module.css'
 import { PrimitivesSection } from './sections/PrimitivesSection'
 import { CompositesSection } from './sections/CompositesSection'
 import { LayoutSection } from './sections/LayoutSection'
+import { BrandAssetsSection } from './sections/BrandAssetsSection'

 const NAV_SECTIONS = [
  {
@@ -93,6 +94,13 @@ const NAV_SECTIONS = [
      { label: 'TopBar', href: '#topbar' },
    ],
  },
+  {
+    label: 'Brand Assets',
+    href: '#brand-assets',
+    components: [
+      { label: 'Cameleer3 Logo', href: '#brand-assets' },
+    ],
+  },
 ]

 export function Inventory() {
@@ -121,6 +129,7 @@ export function Inventory() {
          <PrimitivesSection />
          <CompositesSection />
          <LayoutSection />
+          <BrandAssetsSection />
        </main>
      </div>
    </div>
--- a/src/pages/Inventory/sections/BrandAssetsSection.module.css
+++ b/src/pages/Inventory/sections/BrandAssetsSection.module.css
@@ -0,0 +1,86 @@
+.section {
+  margin-bottom: 40px;
+}
+
+.sectionTitle {
+  font-size: 22px;
+  font-weight: 700;
+  color: var(--text-primary);
+  margin: 0 0 24px;
+}
+
+.componentCard {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-md);
+  padding: 20px;
+  margin-bottom: 16px;
+  box-shadow: var(--shadow-sm);
+}
+
+.componentTitle {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--text-primary);
+  margin: 0 0 4px;
+}
+
+.componentDesc {
+  font-size: 12px;
+  color: var(--text-muted);
+  margin: 0 0 16px;
+}
+
+.demoArea {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 12px;
+  align-items: flex-start;
+}
+
+.logoGrid {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 20px;
+  align-items: flex-end;
+}
+
+.logoItem {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+}
+
+.logoPreview {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--bg-body);
+  border: 1px solid var(--border);
+  border-radius: var(--radius-sm);
+  padding: 12px;
+  min-width: 48px;
+  min-height: 48px;
+}
+
+.logoPreview img {
+  display: block;
+  image-rendering: auto;
+}
+
+.logoLabel {
+  font-size: 12px;
+  font-weight: 600;
+  color: var(--text-primary);
+}
+
+.logoExport {
+  font-size: 10px;
+  font-family: var(--font-mono);
+  color: var(--text-muted);
+  background: var(--bg-body);
+  padding: 2px 6px;
+  border-radius: var(--radius-sm);
+  white-space: nowrap;
+}
--- a/src/pages/Inventory/sections/BrandAssetsSection.tsx
+++ b/src/pages/Inventory/sections/BrandAssetsSection.tsx
@@ -0,0 +1,77 @@
+import styles from './BrandAssetsSection.module.css'
+import camelLogoSvg from '../../../assets/camel-logo.svg'
+import cameleer3Logo from '../../../assets/cameleer3-logo.png'
+import cameleer3LogoSvg from '../../../assets/cameleer3-logo.svg'
+
+const LOGO_SIZES = [16, 32, 48, 180, 192, 512] as const
+
+export function BrandAssetsSection() {
+  return (
+    <section id="brand-assets" className={styles.section}>
+      <h2 className={styles.sectionTitle}>Brand Assets</h2>
+
+      <div className={styles.componentCard}>
+        <h3 className={styles.componentTitle}>Cameleer3 Logo (PNG)</h3>
+        <p className={styles.componentDesc}>
+          Full-resolution logo and pre-generated size variants for favicons, PWA icons, and social images.
+          Shipped as static assets via <code>@cameleer/design-system/assets/*</code> export.
+        </p>
+        <div className={styles.demoArea}>
+          <div className={styles.logoGrid}>
+            {LOGO_SIZES.map((size) => (
+              <div key={size} className={styles.logoItem}>
+                <div className={styles.logoPreview}>
+                  <img
+                    src={cameleer3Logo}
+                    alt={`Logo ${size}×${size}`}
+                    width={Math.min(size, 96)}
+                    height={Math.min(size, 96)}
+                  />
+                </div>
+                <span className={styles.logoLabel}>{size}×{size}</span>
+                <code className={styles.logoExport}>assets/cameleer3-{size}.png</code>
+              </div>
+            ))}
+            <div className={styles.logoItem}>
+              <div className={styles.logoPreview}>
+                <img
+                  src={cameleer3Logo}
+                  alt="Full resolution logo"
+                  width={96}
+                  height={96}
+                />
+              </div>
+              <span className={styles.logoLabel}>Original</span>
+              <code className={styles.logoExport}>assets/cameleer3-logo.png</code>
+            </div>
+          </div>
+        </div>
+      </div>
+
+      <div className={styles.componentCard}>
+        <h3 className={styles.componentTitle}>SVG Logos</h3>
+        <p className={styles.componentDesc}>
+          Vector logos for scalable usage. Transparent backgrounds, infinitely scalable.
+        </p>
+        <div className={styles.demoArea}>
+          <div className={styles.logoGrid}>
+            <div className={styles.logoItem}>
+              <div className={styles.logoPreview}>
+                <img src={cameleer3LogoSvg} alt="Cameleer3 SVG logo" width={96} height={96} />
+              </div>
+              <span className={styles.logoLabel}>Cameleer3 SVG</span>
+              <code className={styles.logoExport}>assets/cameleer3-logo.svg</code>
+            </div>
+            <div className={styles.logoItem}>
+              <div className={styles.logoPreview}>
+                <img src={camelLogoSvg} alt="Camel SVG logo" width={96} height={96} />
+              </div>
+              <span className={styles.logoLabel}>Camel SVG</span>
+              <code className={styles.logoExport}>assets/camel-logo.svg</code>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+  )
+}
--- a/src/pages/Inventory/sections/LayoutSection.tsx
+++ b/src/pages/Inventory/sections/LayoutSection.tsx
@@ -1,6 +1,9 @@
 import styles from './LayoutSection.module.css'
 import { Sidebar } from '../../../design-system/layout/Sidebar/Sidebar'
-import type { SidebarApp } from '../../../design-system/layout/Sidebar/Sidebar'
+import { SidebarTree } from '../../../design-system/layout/Sidebar/SidebarTree'
+import type { SidebarTreeNode } from '../../../design-system/layout/Sidebar/SidebarTree'
+import { StatusDot } from '../../../design-system/primitives/StatusDot/StatusDot'
+import { Box, Settings, FileText, ChevronRight } from 'lucide-react'
 import { TopBar } from '../../../design-system/layout/TopBar/TopBar'

 // ── DemoCard helper ──────────────────────────────────────────────────────────
@@ -22,42 +25,42 @@ function DemoCard({ id, title, description, children }: DemoCardProps) {
  )
 }

-// ── Sample data (hierarchical) ───────────────────────────────────────────────
+// ── Sample tree nodes ────────────────────────────────────────────────────────

-const SAMPLE_APPS: SidebarApp[] = [
+const SAMPLE_APP_NODES: SidebarTreeNode[] = [
  {
    id: 'app1',
-    name: 'cameleer-prod',
-    health: 'live' as const,
-    exchangeCount: 14320,
-    routes: [
-      { id: 'r1', name: 'order-ingest', exchangeCount: 5421 },
-      { id: 'r2', name: 'payment-validate', exchangeCount: 3102 },
-    ],
-    agents: [
-      { id: 'ag1', name: 'agent-prod-1', status: 'live' as const, tps: 42 },
-      { id: 'ag2', name: 'agent-prod-2', status: 'live' as const, tps: 38 },
+    label: 'cameleer-prod',
+    icon: <StatusDot variant="live" />,
+    badge: '14.3k',
+    path: '/apps/app1',
+    starrable: true,
+    starKey: 'app:app1',
+    children: [
+      { id: 'app1/r1', label: 'order-ingest', icon: <ChevronRight size={12} />, badge: '5,421', path: '/apps/app1/r1' },
+      { id: 'app1/r2', label: 'payment-validate', icon: <ChevronRight size={12} />, badge: '3,102', path: '/apps/app1/r2' },
    ],
  },
  {
    id: 'app2',
-    name: 'cameleer-staging',
-    health: 'stale' as const,
-    exchangeCount: 871,
-    routes: [
-      { id: 'r3', name: 'notify-customer', exchangeCount: 2201 },
-    ],
-    agents: [
-      { id: 'ag3', name: 'agent-staging-1', status: 'stale' as const, tps: 5 },
+    label: 'cameleer-staging',
+    icon: <StatusDot variant="stale" />,
+    badge: '871',
+    path: '/apps/app2',
+    starrable: true,
+    starKey: 'app:app2',
+    children: [
+      { id: 'app2/r3', label: 'notify-customer', icon: <ChevronRight size={12} />, badge: '2,201', path: '/apps/app2/r3' },
    ],
  },
  {
    id: 'app3',
-    name: 'cameleer-dev',
-    health: 'dead' as const,
-    exchangeCount: 42,
-    routes: [],
-    agents: [],
+    label: 'cameleer-dev',
+    icon: <StatusDot variant="dead" />,
+    badge: '42',
+    path: '/apps/app3',
+    starrable: true,
+    starKey: 'app:app3',
  },
 ]

@@ -99,10 +102,19 @@ export function LayoutSection() {
      <DemoCard
        id="sidebar"
        title="Sidebar"
-        description="Navigation sidebar with hierarchical app/route/agent trees, starring, search filter, and bottom links."
+        description="Composable navigation sidebar with sections, tree navigation, and icon-rail collapse mode."
      >
        <div className={styles.sidebarPreview}>
-          <Sidebar apps={SAMPLE_APPS} />
+          <Sidebar>
+            <Sidebar.Header logo={<span style={{ fontSize: 20 }}>&#x1F42A;</span>} title="cameleer" version="v3.2.1" />
+            <Sidebar.Section label="Applications" icon={<Box size={14} />} open={true} onToggle={() => {}} active={false}>
+              <SidebarTree nodes={SAMPLE_APP_NODES} isStarred={() => false} onToggleStar={() => {}} />
+            </Sidebar.Section>
+            <Sidebar.Footer>
+              <Sidebar.FooterLink icon={<Settings size={14} />} label="Admin" />
+              <Sidebar.FooterLink icon={<FileText size={14} />} label="API Docs" />
+            </Sidebar.Footer>
+          </Sidebar>
        </div>
      </DemoCard>

--- a/src/pages/RouteDetail/RouteDetail.tsx
+++ b/src/pages/RouteDetail/RouteDetail.tsx
@@ -4,8 +4,6 @@ import { AlertTriangle } from 'lucide-react'
 import styles from './RouteDetail.module.css'

 // Layout
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'

 // Composites
@@ -22,7 +20,6 @@ import { InfoCallout } from '../../design-system/primitives/InfoCallout/InfoCall
 // Mock data
 import { routes } from '../../mocks/routes'
 import { exchanges, type Exchange } from '../../mocks/exchanges'
-import { SIDEBAR_APPS } from '../../mocks/sidebar'

 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function formatDuration(ms: number): string {
@@ -199,11 +196,7 @@ export function RouteDetail() {
  // Not found state
  if (!route) {
    return (
-      <AppShell
-        sidebar={
-          <Sidebar apps={SIDEBAR_APPS} />
-        }
-      >
+      <>
        <TopBar
          breadcrumb={[
            { label: 'Applications', href: '/apps' },
@@ -211,24 +204,19 @@ export function RouteDetail() {
            { label: id ?? 'Unknown' },
          ]}
          environment="PRODUCTION"
-  
          user={{ name: 'hendrik' }}
        />
        <div className={styles.content}>
          <InfoCallout variant="warning">Route "{id}" not found in mock data.</InfoCallout>
        </div>
-      </AppShell>
+      </>
    )
  }

  const statusVariant = routeStatusVariant(route.status)

  return (
-    <AppShell
-      sidebar={
-        <Sidebar apps={SIDEBAR_APPS} />
-      }
-    >
+    <>
      {/* Top bar */}
      <TopBar
        breadcrumb={[
@@ -375,6 +363,6 @@ export function RouteDetail() {
        )}

      </div>
-    </AppShell>
+    </>
  )
 }
--- a/src/pages/Routes/Routes.tsx
+++ b/src/pages/Routes/Routes.tsx
@@ -3,8 +3,6 @@ import { useNavigate, useParams } from 'react-router-dom'
 import styles from './Routes.module.css'

 // Layout
-import { AppShell } from '../../design-system/layout/AppShell/AppShell'
-import { Sidebar } from '../../design-system/layout/Sidebar/Sidebar'
 import { TopBar } from '../../design-system/layout/TopBar/TopBar'

 // Composites
@@ -33,7 +31,7 @@ import {
  type RouteMetricRow,
 } from '../../mocks/metrics'
 import { routes } from '../../mocks/routes'
-import { SIDEBAR_APPS, buildRouteToAppMap } from '../../mocks/sidebar'
+import { buildRouteToAppMap } from '../../mocks/sidebar'

 const ROUTE_TO_APP = buildRouteToAppMap()

@@ -410,7 +408,7 @@ export function Routes() {
  // ── Route detail view ───────────────────────────────────────────────────────
  if (routeId && appId && routeDef) {
    return (
-      <AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>
+      <>
        <TopBar
          breadcrumb={breadcrumb}
          environment="PRODUCTION"
@@ -448,13 +446,13 @@ export function Routes() {
            <RouteFlow nodes={routeFlowNodes} />
          </div>
        </div>
-      </AppShell>
+      </>
    )
  }

  // ── Top level / Application level view ──────────────────────────────────────
  return (
-    <AppShell sidebar={<Sidebar apps={SIDEBAR_APPS} />}>
+    <>
      <TopBar
        breadcrumb={breadcrumb}
        environment="PRODUCTION"
@@ -533,6 +531,6 @@ export function Routes() {
          </Card>
        </div>
      </div>
-    </AppShell>
+    </>
  )
 }
Author	SHA1	Message	Date
hsiegeln	e572df8558	fix(assets): remove semi-white background artifacts from logo SVG and PNGs All checks were successful Build & Publish / publish (push) Successful in 1m4s Details SonarQube Analysis / sonarqube (push) Successful in 2m27s Details Stripped 8 near-white path layers (brightness > 200) from the traced SVG, leaving only amber/gold tones. Regenerated all PNG variants from the cleaned SVG. Validated on dark and red backgrounds with zero artifacts. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-06 23:19:39 +02:00
hsiegeln	a3afe3cb1b	feat(assets): add high-detail cameleer3-logo.svg traced from PNG via Inkscape All checks were successful Build & Publish / publish (push) Successful in 1m4s Details 32-scan potrace vector trace with transparent background. Added to brand assets inventory, documentation, and package exports. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-06 22:58:44 +02:00
hsiegeln	4841a7ad7c	refactor(assets): replace named exports with wildcard ./assets/* export All checks were successful Build & Publish / publish (push) Successful in 1m10s Details Consumers now import via @cameleer/design-system/assets/<filename> instead of named aliases like /logo-32. Simpler, more flexible, and supports any future assets without adding new export entries. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-06 22:43:01 +02:00
hsiegeln	32a49690fa	style(assets): make all logo PNGs transparent using Inkscape trace All checks were successful Build & Publish / publish (push) Successful in 1m7s Details Traced the original logo with Inkscape (16-scan potrace, background removal) and re-exported all PNG variants with transparent backgrounds. Also reduces total asset size from ~1.7MB to ~630KB. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-06 22:14:50 +02:00
hsiegeln	20f7b2f5aa	feat(assets): ship Cameleer3 logo and favicon variants with the design system All checks were successful Build & Publish / publish (push) Successful in 1m5s Details Add brand assets as static package exports (logo, logo-16 through logo-512, logo-svg) with pre-generated PNG sizes for favicons, PWA icons, Apple touch icons, and social images. Includes inventory showcase section and updated documentation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-06 17:17:36 +02:00
hsiegeln	5cb51e65be	style(topbar): make .env badge match neutral button style of liveToggle/themeToggle All checks were successful Build & Publish / publish (push) Successful in 1m42s Details SonarQube Analysis / sonarqube (push) Successful in 2m26s Details Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-04 15:59:00 +02:00
hsiegeln	4dcd4aaa27	feat(topbar): change environment prop from string to ReactNode All checks were successful Build & Publish / publish (push) Successful in 1m21s Details Allows consuming apps to pass a custom dropdown or any interactive element instead of a static string label. Rendering changed from <span> to <div> to support block-level children. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-04 15:25:20 +02:00
hsiegeln	58320b9762	fix(topbar): rename refresh toggle labels from LIVE/PAUSED to AUTO/MANUAL All checks were successful Build & Publish / publish (push) Successful in 54s Details SonarQube Analysis / sonarqube (push) Successful in 3m3s Details Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-03 18:30:17 +02:00
hsiegeln	c48dffaef2	feat(global-filter): add refreshTimeRange() for manual refresh in paused mode All checks were successful Build & Publish / publish (push) Successful in 55s Details Revert auto-sliding when paused — time range only advances with auto-refresh on. Add refreshTimeRange() to useGlobalFilters for on-demand recomputation from the active preset. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-03 14:01:47 +02:00
hsiegeln	3ef4c5686e	fix(global-filter): keep time range sliding when auto-refresh is paused All checks were successful Build & Publish / publish (push) Successful in 1m6s Details The preset time window now advances on a 10s interval regardless of auto-refresh state. Pausing only stops query polling — the window stays current so manual refreshes see up-to-date data. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-03 13:16:11 +02:00
hsiegeln	78e28789a5	docs: update CommandPalette entry for open SearchCategory type All checks were successful Build & Publish / publish (push) Successful in 1m36s Details SonarQube Analysis / sonarqube (push) Successful in 2m52s Details Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 23:23:32 +02:00
hsiegeln	03ec34bb5c	feat(command-palette): open SearchCategory to arbitrary strings All checks were successful Build & Publish / publish (push) Successful in 1m33s Details Widen SearchCategory from a closed union to string. Known categories (application, exchange, attribute, route, agent) keep their labels. Unknown categories render with title-cased labels and appear as dynamic tabs derived from the data. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 23:21:28 +02:00
hsiegeln	2f1df869db	docs: update spec and guide for search position and chevron removal All checks were successful Build & Publish / publish (push) Successful in 1m7s Details - COMPONENT_GUIDE: note search renders between Header and Sections, no chevrons on section headers - Spec: update rendering diagrams and description to match implemented behavior Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 22:43:00 +02:00
hsiegeln	0cf696cded	fix(sidebar): move search below Header, remove section chevrons All checks were successful Build & Publish / publish (push) Successful in 1m3s Details - Search input now renders between Sidebar.Header and first Section instead of above Header (fixes cameleer3-server#120) - Remove ChevronRight/ChevronDown from section headers — the entire row is already clickable, chevrons added visual noise Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 22:40:18 +02:00
hsiegeln	50a1296a9d	fix(sidebar): make entire section header row clickable All checks were successful Build & Publish / publish (push) Successful in 2m1s Details The toggle was only on the chevron button. Now the full row (chevron + icon + label) triggers onToggle on click or Enter/Space. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 21:59:47 +02:00
hsiegeln	9b8739b5d8	fix(a11y): add keyboard listeners to clickable elements (S1082) All checks were successful Build & Publish / publish (push) Successful in 1m2s Details Add onKeyDown (Enter/Space) to the CommandPalette overlay backdrop div and result item divs to satisfy SonarQube S1082. RouteFlow and ProcessorTimeline already had the fixes in place. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-02 18:41:11 +02:00
hsiegeln	ba6028c2ea	refactor: extract nested handlers to fix function depth violations (S2004) All checks were successful Build & Publish / publish (push) Successful in 1m52s Details Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-02 18:35:46 +02:00
hsiegeln	93776944b9	refactor: extract keyboard handlers to reduce cognitive complexity (S3776) Extract per-key arrow handler logic into standalone functions outside the component in SidebarTree.tsx and TreeView.tsx, reducing handleKeyDown cognitive complexity from 31 to below the 15-unit maximum. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-02 18:35:27 +02:00
hsiegeln	9240acddb6	docs: update CLAUDE.md and COMPONENT_GUIDE.md for composable Sidebar All checks were successful Build & Publish / publish (push) Successful in 1m26s Details - Add Sidebar, SidebarTree, useStarred to import paths - Update navigation decision tree with compound component entries - Replace old Sidebar props description with compound API - Add standard page layout composition pattern for new Sidebar Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 18:30:27 +02:00
hsiegeln	912adb1070	feat: composable sidebar refactor All checks were successful Build & Publish / publish (push) Successful in 57s Details Replaces monolithic Sidebar with compound component API: Sidebar, Sidebar.Header, Sidebar.Section, Sidebar.Footer, Sidebar.FooterLink. Exports SidebarTree, useStarred publicly. Migrates mock app to LayoutShell with React Router layout routes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 18:16:30 +02:00
hsiegeln	eeb2713612	fix: strip Sidebar wrapper from RouteDetail + fix StatusDot prop in LayoutSection - RouteDetail.tsx was missed in page stripping pass — remove AppShell + Sidebar wrapper, replace with fragment - LayoutSection.tsx used StatusDot status= instead of variant= Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 18:13:03 +02:00
hsiegeln	18bf644040	refactor(inventory): update Sidebar demo to compound API Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 18:10:09 +02:00
hsiegeln	9fa7eb129d	refactor: strip AppShell+Sidebar wrappers from all page components Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 18:09:16 +02:00
hsiegeln	8cd3c3a99d	refactor: wrap routes in LayoutShell layout route Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 18:05:49 +02:00
hsiegeln	36999941c0	feat(layout): create LayoutShell with compound Sidebar composition Move all application-specific sidebar logic (tree builders, starred items, section collapse state, sidebarReveal handling) out of the DS Sidebar into a shared LayoutShell that wraps Outlet for route-level layout sharing. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 18:04:08 +02:00
hsiegeln	5a91875723	test(sidebar): rewrite Sidebar tests for compound component API Replace legacy monolithic Sidebar test suite with 16 tests covering the new compound component API (Sidebar.Header, Section, Footer, FooterLink) including icon-rail collapsed mode, search input visibility, and active state highlighting. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-02 18:01:39 +02:00
hsiegeln	c401516b2d	fix(sidebar): add icon to expanded section, fix icon-rail callbacks, fix active border - Render icon between chevron and label in expanded SidebarSection - Remove !open guard from icon-rail click — always fire both callbacks - Add border-left: 3px solid transparent to .treeSection so .treeSectionActive border-left-color takes effect - Remove duplicate .treeSectionLabel CSS declaration Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:59:25 +02:00
hsiegeln	d2c2b92183	feat(sidebar): update barrel exports for composable sidebar Export SidebarTree, SidebarTreeNode, and useStarred from the layout barrel. Remove old app-domain type exports (SidebarApp, SidebarRoute, SidebarAgent) that no longer exist in the rewritten Sidebar. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:55:29 +02:00
hsiegeln	357e497220	feat(sidebar): update CSS for composable compound component Add collapsed state styles (sidebarCollapsed, collapseToggle), icon-rail mode (sectionRailItem, sectionIcon), and width transition. Remove old monolithic classes (navArea, section, items, item, navIcon, routeArrow, all starred-section styles). Pin footer with margin-top: auto. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:55:20 +02:00
hsiegeln	1173b3e363	feat(sidebar): rewrite Sidebar as composable compound component Replace the monolithic Sidebar (560 lines of app-specific logic) with a composable shell exposing Sidebar.Header, Sidebar.Section, Sidebar.Footer, and Sidebar.FooterLink sub-components. Application logic (tree builders, starred items, domain types) is removed — those responsibilities move to the consuming app layer. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:54:18 +02:00
hsiegeln	7092271fdc	feat(sidebar): add SidebarContext for composable sidebar Create context and hook to share collapsed state and toggle callback between compound component sub-components. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:53:49 +02:00
hsiegeln	3561147b42	docs: add composable sidebar implementation plan 10-task plan covering compound component, CSS, exports, tests, LayoutShell, route migration, and page wrapper stripping. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:50:56 +02:00
hsiegeln	9afe626a58	docs: update composable sidebar spec with clarified decisions Add searchValue prop for controlled input, SidebarContext for collapsed state propagation, LayoutShell migration plan, and icon-rail simultaneous callback behavior. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:42:09 +02:00
hsiegeln	7758962564	docs: clarify search ownership and icon-rail click behavior Search: DS renders dumb controlled input, app owns state and passes filterQuery to SidebarTree instances. Icon-rail click: fires both onCollapseToggle and onToggle simultaneously, no navigation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:41:36 +02:00
hsiegeln	4e2d5b2b2f	docs: composable sidebar refactor spec Compound component API replacing monolithic Sidebar. DS provides shell (Sidebar, Sidebar.Header, Sidebar.Section, Sidebar.Footer, Sidebar.FooterLink) + standalone SidebarTree and useStarred exports. Application controls all content, icons, sections. Adds icon-rail collapse mode. Breaking change — coordinate with server UI migration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-02 17:38:04 +02:00
hsiegeln	af48bd2fa0	fix: sidebar highlighting works on all tabs, not just exchanges All checks were successful Build & Publish / publish (push) Successful in 1m0s Details SonarQube Analysis / sonarqube (push) Successful in 2m17s Details Remove the /exchanges/ path guard so sidebarRevealPath is used whenever available, enabling correct sidebar selection on dashboard, runtime, and all other tabs when navigating via Cmd-K. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-01 20:59:15 +02:00