@withmata/blueprints 0.3.1 → 0.3.2

package/.claude/skills/blueprint-catalog/SKILL.md

@@ -3,7 +3,8 @@ name: blueprint-catalog
 description: >
   Background knowledge about available project blueprints for scaffolding.
   Invoke when user discusses: databases, authentication, project setup,
-  monorepo, product ideas, scaffolding, or asks "what should I do next?"
+  monorepo, product ideas, scaffolding, environment variables, UI components,
+  design systems, Tailwind, or asks "what should I do next?"
 user-invocable: false
 ---
 
@@ -15,6 +16,9 @@ user-invocable: false
 | Monorepo Foundation | Foundation | Turborepo + pnpm monorepo with Next.js, Biome, TypeScript strict, Tailwind v4. | None | `/scaffold-foundation` |
 | Database | Feature | Drizzle ORM + PostgreSQL: schema groups, per-group migrations, seed scripts. | None | `/scaffold-db` |
 | Authentication | Feature | Better Auth + Drizzle + PostgreSQL: social login, email/password, organizations, role-based permissions. | Database | `/scaffold-auth` |
+| Environment Variables | Feature | T3 Env + Zod: validated, type-safe env vars for Next.js (client/server split) and backend apps. | None | `/scaffold-env` |
+| Tailwind v4 Design System | Feature | Full design system: shadcn tokens, animations, typography, sidebar/chart tokens, dark mode. | Foundation (recommended) | `/scaffold-tailwind` |
+| UI Shared Components | Feature | Shared UI package: shadcn/ui, path-based exports, cn utility, component generation. | Tailwind v4 | `/scaffold-ui` |
 
 ## Project Context
 
@@ -32,6 +36,12 @@ Suggest a blueprint when you observe these signals. Be helpful, not pushy — me
 
 **`/scaffold-auth`** — User mentions login, signup, users, accounts, teams, organizations, permissions, or authentication. Or is implementing auth from scratch. Recommend `/scaffold-db` first if not already installed.
 
+**`/scaffold-env`** — User mentions environment variables, `.env` files, env validation, type-safe config, T3 Env, or is accessing `process.env` directly. Or a Next.js app has no env validation. Standalone — works with any project.
+
+**`/scaffold-tailwind`** — User mentions design system, shadcn setup, animations, typography plugin, dark mode theming, or the Tailwind config is missing shadcn integration. Best after foundation.
+
+**`/scaffold-ui`** — User mentions shared components, UI package, component library, shadcn in monorepo, or needs to share components across apps. Recommend `/scaffold-tailwind` first if not installed.
+
 **`/audit`** — User asks "what should I do next?", wants to understand their project's state, or has hand-rolled infrastructure that a blueprint could improve.
 
 ## Lifecycle & Dependencies
@@ -42,7 +52,8 @@ Discovery → Foundation → Features is the recommended flow, but blueprints ca
 - **Single-repo project:** Skip foundation — go directly to feature blueprints (`/scaffold-db`, `/scaffold-auth`)
 - **Has monorepo, missing features:** Suggest specific feature blueprints
 - **Existing project:** Feature blueprints adapt to existing structures — no foundation required
-- **Dependencies:** `/scaffold-auth` works best after `/scaffold-db` (auth builds on db patterns). Install dependencies first.
+- **Dependencies:** `/scaffold-auth` works best after `/scaffold-db` (auth builds on db patterns). `/scaffold-ui` requires `/scaffold-tailwind`. Install dependencies first.
+- **Environment setup:** `/scaffold-env` is recommended for all projects — it's standalone and works with any combination of other blueprints
 
 ## Important
 

package/.claude/skills/scaffold-env/SKILL.md

@@ -0,0 +1,222 @@
+---
+name: scaffold-env
+description: Scaffold T3 Env validated environment variables into the current project
+---
+
+# Scaffold Env Blueprint
+
+Scaffold the `env-t3` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all template files from the env blueprint:
+
+```
+~/.withmata/blueprints/blueprints/features/env-t3/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/env-t3/files/**/*
+```
+
+If not found at these paths, run `npx @withmata/blueprints` to install.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - Product name and scope (from Discovery)
+  - npm scope, workspace layout (from Foundation)
+  - What other blueprints are already installed (from Installed Blueprints)
+  - Use this information to pre-fill env variables and adapt file paths
+
+- **If it does not exist**: proceed normally — explore the project manually (Step 2) and ask all configuration questions (Step 3)
+
+When project context provides clear answers, skip the corresponding questions in Step 3. For example:
+- Context has `auth-better-auth` installed -> pre-populate auth env vars
+- Context has `env-t3` in Installed Blueprints -> warn about existing install
+
+## Step 2: Understand the Target Project
+
+Before making any changes, explore the target project to understand:
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory, no workspace config
+
+Confirm with user: "This looks like a [monorepo|single-repo] project. Is that right?"
+
+### 2b. Discover Apps
+
+Find all applications that need env setup:
+
+**Next.js apps** — look for:
+- `next.config.ts` or `next.config.js` or `next.config.mjs`
+- Typically in `apps/web/`, `apps/*/`, or project root (single-repo)
+
+**Backend apps** — look for:
+- `hono` or `express` or `@hono/node-server` in `package.json` dependencies
+- Typically in `apis/*/`, `apps/server/`, or project root (single-repo)
+
+### 2c. Check Existing Env Setup
+
+For each app found:
+- Does `env.ts` already exist? (Foundation blueprint creates a basic one)
+- Does `src/env/` directory exist? (Already has the split pattern)
+- Does `.env.example` exist?
+- Does `next.config.ts` already import env files?
+- Are `@t3-oss/env-nextjs` or `@t3-oss/env-core` already installed?
+
+### 2d. Check Installed Blueprints
+
+If other blueprints are installed, note their env vars so we can pre-populate:
+- **auth-better-auth**: `BETTER_AUTH_URL`, `BETTER_AUTH_SECRET`, `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `AUTH_DATABASE_URL`
+- **db-drizzle-postgres**: `{{GROUP_UPPER}}_DATABASE_URL` (in db package, not app)
+
+## Step 3: Ask Clarifying Questions
+
+Before scaffolding, ask the user:
+
+1. **Which apps to configure** — "I found these apps: [list]. Set up env validation for all of them?" (Default: yes, all)
+
+2. **Existing env.ts** — If an `env.ts` already exists: "I found an existing `env.ts`. I'll migrate it to the client/server split pattern and merge existing variables. Sound good?"
+
+3. **Pre-populate from installed blueprints** — If other blueprints are installed: "I see auth-better-auth is installed. Should I add its env vars to the server env schema?"
+
+Skip questions where the answer is obvious from the project structure.
+
+## Step 4: Adapt and Scaffold
+
+### 4a. Next.js Apps
+
+For each Next.js app:
+
+**If `env.ts` exists (e.g., from foundation blueprint):**
+1. Read the existing `env.ts` to extract current variables
+2. Split variables: `NEXT_PUBLIC_*` -> `client.ts`, everything else -> `server.ts`
+3. Create `src/env/client.ts` with the client variables
+4. Create `src/env/server.ts` with the server variables
+5. Update `next.config.ts`:
+   - Replace `import "./env"` with `import "./src/env/server"` and `import "./src/env/client"`
+   - If no existing env import, add both imports at the top (before any other code)
+6. Delete the old `env.ts`
+
+**If no existing env setup:**
+1. Create `src/env/client.ts` from template — replace `{{APP_NAME}}`
+2. Create `src/env/server.ts` from template — replace `{{APP_NAME}}`
+3. Update `next.config.ts` — add imports at the top
+
+**For all Next.js apps:**
+4. Create `.env.example` from template — replace `{{APP_NAME}}`
+5. Create `.env.local` (empty file)
+6. If other blueprints are installed, merge their env vars into the appropriate schema
+
+### 4b. Backend Apps
+
+For each backend app:
+
+1. Create `src/env.ts` from template — replace `{{APP_NAME}}`
+2. Update the app's entry point to import env:
+   ```typescript
+   import { env } from "./env.js";
+   ```
+3. Create `.env.example` from template — replace `{{APP_NAME}}`
+4. Create `.env.local` (empty file)
+5. If the app has hardcoded `process.env.PORT` or similar, refactor to use `env.PORT`
+
+### 4c. Dependency Installation
+
+For each Next.js app:
+- Ensure `@t3-oss/env-nextjs` and `zod` are in `dependencies`
+
+For each backend app:
+- Ensure `@t3-oss/env-core`, `zod`, and `dotenv` are in `dependencies`
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### env-t3
+blueprint: env-t3
+choices:
+  nextjs_env_location: src/env/
+  backend_env_location: src/env.ts
+apps_configured:
+  - name: <app name>
+    type: <nextjs|backend>
+    files:
+      - <list of files created>
+packages_added:
+  - <list of packages added>
+```
+
+If `.project-context.md` does not exist, create it with the standard header and the Installed Blueprints section.
+
+### Create Maintenance Skill
+
+Create a project-level maintenance skill for the env blueprint:
+
+**File:** `<project>/.claude/skills/env-maintenance/SKILL.md`
+
+```yaml
+---
+name: env-maintenance
+description: Maintenance rules for T3 Env validated environment variables. Invoke when adding, removing, or modifying environment variables.
+user-invocable: false
+---
+
+### env-t3 maintenance
+- After adding a new env var: add it to the env schema file (client.ts or server.ts), `.env.example`, and `.env.local`
+- NEXT_PUBLIC_* vars go in env/client.ts with explicit runtimeEnv mapping; server vars go in env/server.ts
+- After removing an env var: remove from schema, .env.example, and .env.local
+- Never access process.env directly — always use the typed env objects (clientEnv, serverEnv, or env)
+- Keep .env.example documented with section headers and local/production hints
+```
+
+## Step 6: Output Summary
+
+After scaffolding, provide the user with a clear summary:
+
+### Packages to Install
+
+**Next.js apps:**
+```bash
+pnpm add @t3-oss/env-nextjs zod
+```
+
+**Backend apps:**
+```bash
+pnpm add @t3-oss/env-core zod dotenv
+```
+
+### Files Created
+
+List every file that was created or modified, with a one-line description.
+
+### How to Use
+
+```typescript
+// In server components, API routes, server actions:
+import { serverEnv } from "~/env/server";
+
+// In client components:
+import { clientEnv } from "~/env/client";
+
+// In backend apps:
+import { env } from "./env.js";
+```
+
+### Next Steps
+
+- Fill in `.env.local` with your actual values (use `.env.example` as reference)
+- As you add features, add their env vars to the schema files and `.env.example`
+- Run `pnpm dev` to verify env validation passes
+
+## Important Notes
+
+- When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
+- Never overwrite existing files without asking. If env files exist, merge new variables into them.
+- If `next.config.ts` already imports env files, don't add duplicate imports.
+- The env schema files are the source of truth for what variables an app needs — keep them accurate.

package/.claude/skills/scaffold-tailwind/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: scaffold-tailwind
+description: Scaffold Tailwind v4 full design system into the current project
+---
+
+# Scaffold Tailwind v4 Blueprint
+
+Scaffold the `tailwind-v4` blueprint into the current project. This upgrades the foundation's minimal tailwind-config into a production-ready design system with animations, typography, sidebar tokens, and full shadcn/ui integration.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all template files from the tailwind blueprint:
+
+```
+~/.withmata/blueprints/blueprints/features/tailwind-v4/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/tailwind-v4/files/**/*
+```
+
+If not found at these paths, run `npx @withmata/blueprints` to install.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - npm scope (from Foundation)
+  - Whether `monorepo-turbo` foundation is installed
+  - What other blueprints are already installed
+  - Use this to determine if `config/tailwind-config/` exists
+
+- **If it does not exist**: proceed normally — explore the project manually
+
+## Step 2: Understand the Target Project
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory
+
+### 2b. Check Existing Tailwind Setup
+
+- Does `config/tailwind-config/` exist? (Foundation blueprint creates this)
+- Read existing `shared-styles.css` — is it the minimal version or already upgraded?
+- Read existing `package.json` — what deps are already present?
+- Check `tailwind-v4` in `.project-context.md` Installed Blueprints — already installed?
+
+## Step 3: Ask Clarifying Questions
+
+1. **Sidebar tokens** — "Include sidebar-specific color tokens for dashboard layouts? (Default: yes)"
+2. **Chart tokens** — "Include chart color tokens for data visualization? (Default: yes)"
+
+Skip questions if the user has indicated preferences or if the project type makes the answer obvious.
+
+## Step 4: Adapt and Scaffold
+
+### 4a. Monorepo — Upgrade Existing Config
+
+**If `config/tailwind-config/` exists (foundation was run):**
+
+1. **Replace `shared-styles.css`** — Copy the full version from this blueprint, replacing the foundation's minimal version entirely. The full version includes everything the minimal version had, plus:
+   - `@import "tw-animate-css"`
+   - `@import "shadcn/tailwind.css"`
+   - `@import "tailwind-scrollbar-hide/v4"`
+   - Sidebar tokens (`--color-sidebar-*`)
+   - Chart tokens (`--color-chart-*`)
+   - Extended radius tokens (`--radius-3xl`, `--radius-4xl`)
+   - Font mono token (`--font-mono`)
+
+2. **Merge `package.json` dependencies** — Add these to the existing `dependencies`:
+   - `@tailwindcss/typography`
+   - `shadcn`
+   - `tailwind-scrollbar-hide`
+   - `tw-animate-css`
+   Keep existing `devDependencies` unchanged.
+
+3. **Leave `postcss.config.mjs` unchanged** — it's already correct from foundation.
+
+**If `config/tailwind-config/` does NOT exist:**
+
+1. Create the `config/tailwind-config/` directory
+2. Copy `shared-styles.css` from template
+3. Copy `package.json` from template — replace `{{SCOPE}}`
+4. Create `postcss.config.mjs`:
+   ```javascript
+   export const postcssConfig = {
+     plugins: {
+       "@tailwindcss/postcss": {},
+     },
+   };
+   ```
+
+### 4b. Single-Repo
+
+1. Create `src/styles/shared-styles.css` from template
+2. Add all design system deps to root `package.json`
+3. Update `globals.css` or equivalent to import the shared styles:
+   ```css
+   @import "./src/styles/shared-styles.css";
+   ```
+
+### 4c. Install Dependencies
+
+Run `pnpm install` (or the project's package manager) to fetch new dependencies.
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### tailwind-v4
+blueprint: tailwind-v4
+choices:
+  include_sidebar_tokens: <true|false>
+  include_chart_tokens: <true|false>
+  include_scrollbar_hide: <true|false>
+files_modified:
+  - config/tailwind-config/shared-styles.css
+  - config/tailwind-config/package.json
+packages_added:
+  - "@tailwindcss/typography"
+  - shadcn
+  - tailwind-scrollbar-hide
+  - tw-animate-css
+```
+
+### Create Maintenance Skill
+
+Create a project-level maintenance skill:
+
+**File:** `<project>/.claude/skills/tailwind-maintenance/SKILL.md`
+
+```yaml
+---
+name: tailwind-maintenance
+description: Maintenance rules for Tailwind v4 design system. Invoke when modifying theme tokens, colors, or adding new apps.
+user-invocable: false
+---
+
+### tailwind-v4 maintenance
+- After adding a new color: add CSS variable to both :root and .dark selectors in shared-styles.css, then map in @theme inline
+- After adding a new app: import the tailwind-config package in the app's globals.css
+- After upgrading Tailwind: check for @import, @theme, or @custom-variant breaking changes
+- Never use tailwind.config.js — all configuration is CSS-based in shared-styles.css
+- Colors use OKLCH color space — do not use hex or RGB
+```
+
+## Step 6: Output Summary
+
+### Packages Added
+
+```
+@tailwindcss/typography, shadcn, tailwind-scrollbar-hide, tw-animate-css
+```
+
+### Files Modified
+
+List every file created or modified with a one-line description.
+
+### What Changed from Foundation
+
+- `shared-styles.css` upgraded with animation imports, sidebar tokens, chart tokens, scrollbar utility
+- `package.json` now includes design system dependencies
+- Typography plugin available (add `@plugin "@tailwindcss/typography"` in app globals.css)
+
+### Next Steps
+
+- Add `@plugin "@tailwindcss/typography"` to your app's `globals.css` if you need prose styling
+- Customize the primary color hue in `:root` and `.dark` (currently indigo at hue 264)
+- Run `/scaffold-ui` to set up a shared component library that uses this design system
+
+## Important Notes
+
+- The full `shared-styles.css` is a complete replacement — it includes everything the foundation's minimal version had plus the new additions.
+- Never overwrite `postcss.config.mjs` — it's already correct from the foundation.
+- If the user has customized colors in the existing `shared-styles.css`, ask before replacing. Offer to merge their custom values into the new file.

package/.claude/skills/scaffold-ui/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: scaffold-ui
+description: Scaffold shared UI component library with shadcn/ui into the current project
+---
+
+# Scaffold UI Blueprint
+
+Scaffold the `ui-shared-components` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all template files from the UI blueprint:
+
+```
+~/.withmata/blueprints/blueprints/features/ui-shared-components/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/ui-shared-components/files/**/*
+```
+
+If not found at these paths, run `npx @withmata/blueprints` to install.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - npm scope (from Foundation)
+  - Whether `tailwind-v4` is installed (required dependency)
+  - What other blueprints are installed
+  - Use this to pre-fill scope and adapt paths
+
+- **If it does not exist**: proceed normally — explore the project manually
+
+When project context provides clear answers, skip the corresponding questions in Step 3.
+
+## Step 2: Understand the Target Project
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory
+
+### 2b. Check Blueprint Dependencies
+
+**Required: `tailwind-v4`**
+
+Check if `tailwind-v4` is in `.project-context.md` Installed Blueprints, OR check if `config/tailwind-config/shared-styles.css` contains `@import "tw-animate-css"` (indicator of the full tailwind-v4 blueprint).
+
+If NOT installed: ask "UI components need the Tailwind design system. Run `/scaffold-tailwind` first? (Y/n)"
+- If yes: tell the user to run `/scaffold-tailwind` first, then come back
+- If no: proceed with basic Tailwind defaults and warn about missing design tokens
+
+### 2c. Explore Structure
+
+**If monorepo:**
+1. Does `packages/ui/` already exist? If so, what's in it?
+2. What npm scope is used?
+3. What is the shared TypeScript config package name?
+4. Where are the consuming apps? (`apps/web/`, `apps/*/`, etc.)
+5. What's in the consuming app's `globals.css`?
+
+**If single-repo:**
+1. Does `src/ui/` or `src/components/` exist?
+2. What framework is this? (Next.js?)
+3. What import convention is used? (`@/`, `#`, relative?)
+
+## Step 3: Ask Clarifying Questions
+
+1. **shadcn style** — "Which shadcn style do you prefer? (Default: new-york)" Only ask if the user hasn't specified.
+
+2. **Icon library** — "Which icon library? Lucide (default, shadcn default), Phosphor (richer set), or custom?"
+
+3. **Existing `packages/ui/`** — If it exists: "I found an existing `packages/ui/`. I'll merge the new files without overwriting existing ones."
+
+Skip questions where the answer is obvious.
+
+## Step 4: Adapt and Scaffold
+
+### 4a. Monorepo — Create UI Package
+
+1. Create `packages/ui/` directory (if it doesn't exist)
+2. Copy `package.json` — replace `{{SCOPE}}` with the project's npm scope
+3. Copy `tsconfig.json` — replace `{{SCOPE}}`
+4. Copy `components.json` — update style if user chose something other than `new-york`, update iconLibrary if user chose something other than `lucide`
+5. Create `styles/` directory and copy `globals.css` — replace `{{SCOPE}}`
+6. Create `utils/` directory, copy `cn.ts` and `cva.ts`
+7. Create empty directories: `components/ui/`, `icons/`, `icons/logos/`
+
+### 4b. Single-Repo — Create UI Directory
+
+1. Create `src/ui/` directory structure
+2. Copy utility files (`cn.ts`, `cva.ts`) to `src/ui/utils/`
+3. Copy `styles/globals.css` to `src/ui/styles/` — adjust import to direct path
+4. Copy `components.json` to project root — update aliases for single-repo paths
+5. Create empty directories: `src/ui/components/ui/`, `src/ui/icons/`
+6. Add UI deps to root `package.json`
+
+### 4c. Update Consuming App
+
+**For each Next.js app (monorepo):**
+
+Update `app/globals.css`. The final file should look like:
+
+```css
+@import "tailwindcss";
+@import "{{SCOPE}}/tailwind-config";
+@import "{{SCOPE}}/ui/styles";
+@plugin "@tailwindcss/typography";
+
+@source "../../../packages/ui";
+```
+
+Compute the `@source` relative path based on the consuming app's location relative to `packages/ui/`. For example:
+- `apps/web/` → `@source "../../../packages/ui"` (if workspace root is 3 levels up... actually the typical path is `../../packages/ui` since apps/web/ is 2 levels)
+- Verify the path resolves correctly
+
+**Important:** Don't overwrite the entire `globals.css` — merge the new imports. If the file already has `@import "tailwindcss"` and `@import "{{SCOPE}}/tailwind-config"`, add the new lines after them.
+
+### 4d. Dependency Installation
+
+Run `pnpm install` to wire workspace dependencies.
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### ui-shared-components
+blueprint: ui-shared-components
+choices:
+  shadcn_style: <style>
+  icon_library: <library>
+  include_cva: true
+files_created:
+  - <list of all files created>
+globals_css_updated:
+  - <list of globals.css files modified>
+packages_added:
+  - <list of packages>
+```
+
+### Create Maintenance Skill
+
+Create a project-level maintenance skill:
+
+**File:** `<project>/.claude/skills/ui-maintenance/SKILL.md`
+
+```yaml
+---
+name: ui-maintenance
+description: Maintenance rules for shared UI component library. Invoke when adding components, icons, or modifying the UI package.
+user-invocable: false
+---
+
+### ui-shared-components maintenance
+- Add shadcn components via `pnpm dlx shadcn@latest add <name>` from packages/ui/
+- Use cn() for all className composition — never concatenate class strings manually
+- Internal imports use #prefix (#components/ui/button); cross-package imports use @scope/ui/components/ui/button
+- After adding a new export directory: add to both exports and imports in packages/ui/package.json
+- After adding a new consuming app: add @import and @source directive to the app's globals.css
+```
+
+## Step 6: Output Summary
+
+### Packages to Install
+
+```bash
+# Should be handled by pnpm install, but verify these are in packages/ui/package.json:
+# Dependencies: @radix-ui/react-slot, class-variance-authority, clsx, tailwind-merge, tw-animate-css, shadcn
+# DevDeps: @tailwindcss/postcss, tailwindcss, typescript, @types/react, @types/react-dom
+```
+
+### Files Created
+
+List every file created or modified with a one-line description.
+
+### How to Add Components
+
+```bash
+# From packages/ui/
+cd packages/ui
+pnpm dlx shadcn@latest add button
+pnpm dlx shadcn@latest add card
+pnpm dlx shadcn@latest add input
+```
+
+### How to Use in Apps
+
+```typescript
+import { Button } from "@scope/ui/components/ui/button";
+import { cn } from "@scope/ui/utils/cn";
+```
+
+### Next Steps
+
+- Add your first shadcn components with the commands above
+- Create brand icons in `packages/ui/icons/logos/`
+- Build custom components in `packages/ui/components/`
+
+## Important Notes
+
+- When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
+- Never overwrite existing files without asking. If `packages/ui/` exists, merge new files.
+- The `@source` directive path must be correct relative to the consuming app — verify it resolves.
+- If `tailwind-v4` is not installed and the user proceeds anyway, the UI package will work but may have missing design tokens (no animations, no sidebar colors, etc.).