Menu
Reference for navigating the Lumen turborepo โ workspace commands, where things live, cross-app imports. TRIGGER when user asks about project structure, where to put files, or how workspaces connect.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | monorepo-guide |
| description | Reference for navigating the Lumen turborepo โ workspace commands, where things live, cross-app imports. TRIGGER when user asks about project structure, where to put files, or how workspaces connect. |
Turborepo + pnpm workspaces. Three apps, shared root config.
lumen/
โโโ apps/
โ โโโ cli/ lumen-kb (published) / @lumen/cli (workspace alias) โ CLI engine + MCP server
โ โโโ web/ @lumen/web โ Next.js 15 dashboard + Better Auth
โ โโโ extension/ @lumen/extension โ Browser extension (placeholder)
โโโ turbo.json โ Task pipeline (build, dev, lint, test)
โโโ pnpm-workspace.yaml
โโโ .npmrc โ node-linker=hoisted, shamefully-hoist=true
โโโ package.json โ Root workspace (turbo, prettier, husky)
| What | Command |
|---|---|
| Build everything | pnpm build |
| Dev all apps | pnpm dev |
| CLI only dev | pnpm --filter lumen-kb dev -- <command> |
| Web only dev | pnpm --filter @lumen/web dev |
| Build CLI | pnpm --filter lumen-kb build |
| Lint all | pnpm lint |
| Test CLI | pnpm --filter lumen-kb test |
| Add dep to CLI | pnpm --filter lumen-kb add <pkg> |
| Add dep to web | pnpm --filter @lumen/web add <pkg> |
@lumen/web depends on @lumen/cli via "@lumen/cli": "workspace:*". This allows the web app to import engine functions directly:
import { searchBm25 } from '@lumen/cli/src/search/bm25.js';
This is not wired up yet โ currently the web app is UI-only. Phase 6 (Library) will make @lumen/cli properly exportable.
node_modules dirs are symlinks to /tmp/lumen-*/node_modules (iCloud workaround)pnpm install failure, recreate symlinks โ see CLAUDE.mdpnpm build runs turbo build which builds CLI first (it's a dependency of web)next build crashes on Node 23 โ use next dev or Node 22better-sqlite3 native binary must be rebuilt after Node upgrades: pnpm rebuild better-sqlite3lumen binary is linked from apps/cli/dist/cli.js โ re-link after moving: cd apps/cli && npm linkDiagnose Lumen CLI or MCP issues โ common errors, SQLite problems, search returning no results, compilation failures. TRIGGER when user reports a bug, error, or unexpected behavior.
Pre-deploy verification for Lumen monorepo โ type check, lint, test, build across all workspaces. TRIGGER when user says deploy, ship, release, pre-merge, or CI check.
Review changed code for Lumen project conventions โ catches gotchas that linters miss like wrong hash function, FTS5 quoting, missing .js extensions, interface instead of type. TRIGGER when user asks to review, check, or audit code they wrote.
Search, query, and explore the Lumen knowledge base via MCP tools. TRIGGER when user invokes /lumen or asks about their knowledge base, sources, concepts, or graph.
Scaffold a new page or component for the Lumen Next.js web app. TRIGGER when user asks to create, add, or build a new page, route, or dashboard section.
Scaffold a new Lumen CLI command following the Commander.js register pattern. TRIGGER when user asks to create, add, or implement a new CLI command or subcommand.