diff --git a/CLAUDE.md b/CLAUDE.md
index 18318de..6e073fe 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -42,3 +42,68 @@ import type { Column } from '../design-system/composites'
 import { AppShell } from '../design-system/layout/AppShell'
 import { ThemeProvider } from '../design-system/providers/ThemeProvider'
 ```
+
+## Using This Design System in Other Apps
+
+This design system is published as `@cameleer/design-system` to the Gitea npm registry.
+
+### Registry: `https://gitea.siegeln.net/api/packages/cameleer/npm/`
+
+### Setup in a consuming app
+
+1. Add `.npmrc` to the project root:
+
+```
+@cameleer:registry=https://gitea.siegeln.net/api/packages/cameleer/npm/
+//gitea.siegeln.net/api/packages/cameleer/npm/:_authToken=${GITEA_TOKEN}
+```
+
+Note: CI pipelines for consuming apps also need this `.npmrc` and a `GITEA_TOKEN` secret to fetch the package during `npm ci`.
+
+2. Install:
+
+```bash
+# Snapshot builds (during development)
+npm install @cameleer/design-system@dev
+
+# Stable releases
+npm install @cameleer/design-system
+```
+
+3. Add fonts to `index.html` (required — the package does not bundle fonts):
+
+```html
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=DM+Sans:ital,opsz,wght@0,9..40,300;0,9..40,400;0,9..40,500;0,9..40,600;0,9..40,700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
+```
+
+Without these, `var(--font-body)` and `var(--font-mono)` fall back to `system-ui` / `monospace`.
+
+4. Import styles once at app root, then use components:
+
+```tsx
+import '@cameleer/design-system/style.css'
+import { Button, AppShell, ThemeProvider } from '@cameleer/design-system'
+```
+
+### Import Paths (Consumer)
+
+```tsx
+// All components from single entry
+import { Button, Input, Modal, DataTable, AppShell } from '@cameleer/design-system'
+
+// Types
+import type { Column, DataTableProps, SearchResult } from '@cameleer/design-system'
+
+// Providers
+import { ThemeProvider, useTheme } from '@cameleer/design-system'
+import { CommandPaletteProvider, useCommandPalette } from '@cameleer/design-system'
+import { GlobalFilterProvider, useGlobalFilters } from '@cameleer/design-system'
+
+// Utils
+import { hashColor } from '@cameleer/design-system'
+
+// Styles (once, at app root)
+import '@cameleer/design-system/style.css'
+```
diff --git a/COMPONENT_GUIDE.md b/COMPONENT_GUIDE.md
index 8eb6f7f..14f3856 100644
--- a/COMPONENT_GUIDE.md
+++ b/COMPONENT_GUIDE.md
@@ -204,23 +204,26 @@ URL-driven progressive filtering: /agents → /agents/:appId → /agents/:appId/
 
 ## Import Paths
 
+### Within this repo (design system development)
+
 ```tsx
-// Primitives
-import { Button, Input, Badge, ... } from './design-system/primitives'
-
-// Composites
-import { DataTable, Modal, Toast, ... } from './design-system/composites'
-import type { Column, SearchResult, FeedEvent, ... } from './design-system/composites'
-
-// Layout
+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'
-import { TopBar } from './design-system/layout/TopBar'
-
-// Theme
 import { ThemeProvider, useTheme } from './design-system/providers/ThemeProvider'
 ```
 
+### From consuming apps (via npm package)
+
+```tsx
+import '@cameleer/design-system/style.css'  // once at app root
+import { Button, Input, Modal, DataTable, AppShell, ThemeProvider } from '@cameleer/design-system'
+import type { Column, DataTableProps, SearchResult } from '@cameleer/design-system'
+```
+
+See `CLAUDE.md` "Using This Design System in Other Apps" for full setup instructions.
+
 ## Styling Rules
 
 - **CSS Modules only** — no inline styles except dynamic values (width, color from props)