@leanspec/ui 0.2.7 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/packages/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leanspec/web",
-  "version": "0.2.4",
+  "version": "0.2.2",
   "description": "LeanSpec Web: Fullstack spec showcase platform",
   "private": true,
   "type": "module",
@@ -19,7 +19,6 @@
     "db:seed": "tsx src/lib/db/seed.ts"
   },
   "dependencies": {
-    "@dagrejs/dagre": "^1.1.8",
     "@leanspec/core": "workspace:*",
     "@radix-ui/react-avatar": "^1.1.11",
     "@radix-ui/react-dialog": "^1.1.15",
@@ -37,7 +36,6 @@
     "dayjs": "^1.11.19",
     "drizzle-orm": "^0.38.3",
     "fuse.js": "^7.1.0",
-    "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
     "lucide-react": "^0.553.0",
@@ -46,23 +44,17 @@
     "react": "19.2.0",
     "react-dom": "19.2.0",
     "react-markdown": "^9.0.2",
-    "react-window": "^2.2.3",
-    "reactflow": "^11.11.4",
     "recharts": "^3.4.1",
     "rehype-highlight": "^7.0.1",
-    "rehype-slug": "^6.0.0",
     "remark-gfm": "^4.0.0",
     "sonner": "^2.0.7",
     "swr": "^2.3.6",
     "tailwind-merge": "^3.4.0",
-    "unified": "^11.0.5",
-    "unist-util-visit": "^5.0.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
     "@tailwindcss/typography": "^0.5.15",
     "@types/better-sqlite3": "^7.6.12",
-    "@types/mdast": "^4.0.4",
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",

package/.next/standalone/packages/ui/dist/standalone/packages/web/server.js

@@ -15,7 +15,7 @@ const currentPort = parseInt(process.env.PORT, 10) || 3000
 const hostname = process.env.HOSTNAME || '0.0.0.0'
 
 let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
-const nextConfig = {"env":{},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/Users/marvzhang/projects/codervisor/lean-spec","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"serverSourceMaps":false,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"clientSegmentCache":true,"dynamicOnHover":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":9,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":false,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":false,"lockDistDir":true,"isolatedDevBuild":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","turbopack":{"root":"/Users/marvzhang/projects/codervisor/lean-spec"},"distDirRoot":".next"}
+const nextConfig = {"env":{},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/home/marvin/projects/codervisor/lean-spec","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"serverSourceMaps":false,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"clientSegmentCache":true,"dynamicOnHover":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":31,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":false,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":false,"lockDistDir":true,"isolatedDevBuild":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","turbopack":{"root":"/home/marvin/projects/codervisor/lean-spec"},"distDirRoot":".next"}
 
 process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
 

package/.next/standalone/packages/ui/dist/standalone/specs/035-live-specs-showcase/README.md

@@ -1,5 +1,5 @@
 ---
-status: complete
+status: in-progress
 created: '2025-11-03'
 tags:
   - docs
@@ -8,21 +8,17 @@ tags:
   - v0.3.0-launch
 priority: high
 created_at: '2025-11-03T00:00:00Z'
-updated_at: '2025-11-17T08:18:56.995Z'
+updated_at: '2025-11-11T15:21:48.941Z'
 depends_on:
   - 067-monorepo-core-extraction
 transitions:
   - status: in-progress
     at: '2025-11-11T15:21:48.941Z'
-  - status: complete
-    at: '2025-11-17T08:18:56.995Z'
-completed_at: '2025-11-17T08:18:56.995Z'
-completed: '2025-11-17'
 ---
 
 # LeanSpec Web: Fullstack Spec Showcase Platform
 
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-03 · **Tags**: docs, dogfooding, web, v0.3.0-launch
+> **Status**: ⏳ In progress · **Priority**: High · **Created**: 2025-11-03 · **Tags**: docs, dogfooding, web, v0.3.0-launch
 
 **Project**: lean-spec  
 **Team**: Core Development

package/.next/standalone/packages/ui/dist/standalone/specs/072-ai-agent-first-use-workflow/README.md

@@ -1,5 +1,5 @@
 ---
-status: planned
+status: in-progress
 created: '2025-11-13'
 tags:
   - onboarding
@@ -8,17 +8,15 @@ tags:
   - mcp
 priority: high
 created_at: '2025-11-13T08:20:28.110Z'
-updated_at: '2025-11-17T08:18:44.417Z'
+updated_at: '2025-11-13T08:21:45.345Z'
 transitions:
   - status: in-progress
     at: '2025-11-13T08:21:45.345Z'
-  - status: planned
-    at: '2025-11-17T08:18:44.417Z'
 ---
 
 # ai-agent-first-use-workflow
 
-> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-13 · **Tags**: onboarding, ai-agents, ux, mcp
+> **Status**: ⏳ In progress · **Priority**: High · **Created**: 2025-11-13 · **Tags**: onboarding, ai-agents, ux, mcp
 
 **Project**: lean-spec  
 **Team**: Core Development

package/.next/standalone/packages/ui/dist/standalone/specs/081-web-app-ux-redesign/README.md

@@ -14,8 +14,7 @@ depends_on:
 related:
   - 052-branding-assets
   - 068-live-specs-ux-enhancements
-  - 094-ai-chatbot-web-integration
-updated_at: '2025-11-17T06:32:59.774Z'
+updated_at: '2025-11-17T01:14:24.924Z'
 transitions:
   - status: in-progress
     at: '2025-11-14T04:08:03.555Z'

package/.next/standalone/packages/ui/dist/standalone/specs/082-web-realtime-sync-architecture/README.md

@@ -1,5 +1,5 @@
 ---
-status: complete
+status: in-progress
 created: '2025-11-14'
 tags:
   - web
@@ -9,25 +9,20 @@ tags:
   - v0.3.0
 priority: critical
 created_at: '2025-11-14T05:33:26.170Z'
-updated_at: '2025-11-17T08:18:56.781Z'
+updated_at: '2025-11-14T05:35:02.854Z'
 transitions:
   - status: in-progress
     at: '2025-11-14T05:35:02.854Z'
-  - status: complete
-    at: '2025-11-17T08:18:56.781Z'
 related:
   - 035-live-specs-showcase
   - 081-web-app-ux-redesign
   - 068-live-specs-ux-enhancements
   - 065-v03-planning
-  - 094-ai-chatbot-web-integration
-completed_at: '2025-11-17T08:18:56.781Z'
-completed: '2025-11-17'
 ---
 
 # Web App Realtime Spec Sync Architecture
 
-> **Status**: ✅ Complete · **Priority**: Critical · **Created**: 2025-11-14 · **Tags**: web, architecture, deployment, realtime, v0.3.0
+> **Status**: ⏳ In progress · **Priority**: Critical · **Created**: 2025-11-14 · **Tags**: web, architecture, deployment, realtime, v0.3.0
 
 **Project**: lean-spec  
 **Team**: Core Development

package/.next/standalone/packages/ui/dist/standalone/specs/087-cli-ui-command/README.md

@@ -1,5 +1,5 @@
 ---
-status: complete
+status: in-progress
 created: '2025-11-17'
 tags:
   - cli
@@ -12,19 +12,17 @@ related:
   - 035-live-specs-showcase
   - 081-web-app-ux-redesign
   - 082-web-realtime-sync-architecture
-updated_at: '2025-11-17T06:12:03.020Z'
+updated_at: '2025-11-17T04:41:33.637Z'
 transitions:
   - status: in-progress
     at: '2025-11-17T01:59:34.354Z'
-  - status: complete
-    at: '2025-11-17T06:12:03.020Z'
 completed_at: '2025-11-17T02:00:24.131Z'
 completed: '2025-11-17'
 ---
 
 # CLI UI Command: `lean-spec ui`
 
-> **Status**: ✅ Complete · **Priority**: Medium · **Created**: 2025-11-17 · **Tags**: cli, web, dx, integration
+> **Status**: ⏳ In progress · **Priority**: Medium · **Created**: 2025-11-17 · **Tags**: cli, web, dx, integration
 
 **Project**: lean-spec  
 **Team**: Core Development  
@@ -41,29 +39,207 @@ completed: '2025-11-17'
 - Unit tests passing
 - Code review feedback addressed
 
+**Phase 2: Standalone UI Package (Production Mode)** - 🚧 **IN PROGRESS**
+- Need to create `@leanspec/ui` package for external projects
+- Need to implement `runPublishedUI()` logic in CLI
+- Need to set up npm publish CI workflow
+
+**What works now:**
+- ✅ `lean-spec ui` in LeanSpec monorepo (dev mode)
+- ✅ All command options: `--port`, `--specs`, `--no-open`, `--dry-run`
+- ✅ Auto-opens browser, launches web server with filesystem mode
+
+**What's next:**
+- Create standalone `@leanspec/ui` package
+- Implement production mode for external projects
+- Set up CI/CD for npm publishing
+
+## Overview
+
+Add a `lean-spec ui` command to the CLI that launches the local web interface for visual spec management. This provides a better UX for users who prefer graphical interfaces over CLI commands, especially for browsing, searching, and understanding spec relationships.
+
+**Why now?**
+- Web app is production-ready (specs 035, 081, 082 completed)
+- Filesystem-based architecture (spec 082) enables realtime local spec viewing
+- Natural complement to CLI workflow - some tasks are better visual (board view, search, relationships)
+- Low effort, high value feature for improving DX
+
+**What's the problem?**
+- Users must manually navigate to `packages/web` and run `npm run dev` to access the UI
+- No integrated workflow between CLI and web interface
+- External projects using `lean-spec` have no easy way to access the web UI
+- Missing discoverability - users may not know the web interface exists
+
+**What's the solution?**
+Add `lean-spec ui` command that:
+1. **For external projects**: Runs a published standalone web UI package (`@leanspec/ui`)
+2. **For LeanSpec monorepo** (dev): Optionally detects and runs local `packages/web` dev server
+3. Opens browser automatically to the UI
+4. Watches specs directory for changes (realtime updates via spec 082 architecture)
+
+## Design
+
+### Package Strategy
+
+**Published Package Approach** (Preferred for external projects):
+
+Create a separate `@leanspec/ui` package that:
+- Bundles the web app as a standalone executable
+- Can be run via `npx @leanspec/ui` or installed globally
+- Detects specs directory automatically (looks for `specs/` or `leanspec.yaml`)
+- Lightweight CLI wrapper around Next.js production build
+
+**Architecture:**
+```
+┌─────────────────────────────────────────────────────────┐
+│ User Project                                            │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  specs/                                                 │
+│  └── 001-my-spec/                                       │
+│      └── README.md                                      │
+│                                                         │
+│  $ npx lean-spec ui                                     │
+│         ↓                                               │
+│  Runs: npx @leanspec/ui --specs ./specs                 │
+│         ↓                                               │
+│  Opens: http://localhost:3000                           │
+│         ↓                                               │
+│  Web UI (filesystem mode) ← reads specs/ directly       │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Command Interface
+
+```bash
+# Start web UI (auto-detect specs directory)
+lean-spec ui
+
+# Specify custom specs directory
+lean-spec ui --specs ./my-specs
+
+# Specify custom port
+lean-spec ui --port 3001
+
+# Don't open browser automatically
+lean-spec ui --no-open
+
+# Show what would run without executing
+lean-spec ui --dry-run
+```
+
 ### Implementation Approach
 
-**Phase 1: CLI command (packages/cli/src/commands/ui.ts)**
-- `startUi` validates ports, resolves specs via explicit flag, `.lean-spec/config.json`, YAML configs, or common folder heuristics.
-- `detectPackageManager()` centralizes pnpm/yarn/npm detection using user agents + lockfiles so both dev and production code paths invoke the right tool.
-- `runLocalWeb()` now sets `SPECS_MODE=filesystem`, inherits the detected package manager (`pnpm run dev`, `yarn run dev`, etc.), auto-opens the browser, and tears down cleanly on `SIGINT`.
-
-**Phase 2: Published runner (`runPublishedUI`)**
-- Outside the monorepo we construct the proper command (`pnpm dlx --prefer-offline @leanspec/ui ...`, `yarn dlx ...`, or `npx --yes ...`) and stream stdio straight through so the packaged UI owns the console experience.
-- Dry runs show the exact delegation command for both monorepo and external cases, enabling smoke tests without starting servers.
-
-**@leanspec/ui package (packages/ui/)**
-- Next.js config now emits `output: 'standalone'`, producing `/.next/standalone/packages/web/server.js` plus the necessary node_modules snapshot.
-- `scripts/prepare-dist.mjs`
-  - Ensures a fresh web build exists (running `pnpm --filter @leanspec/web build` on demand).
-  - Copies `.next/standalone`, `.next/static`, `public/`, and `BUILD_ID` into `packages/ui/dist/`, handling the nested `packages/web` path automatically.
-- `bin/ui.js`
-  - Resolves specs via flag/config/heuristics, validates ports, and exposes `--port`, `--specs`, `--no-open`, and `--dry-run` flags.
-  - Runs `node dist/standalone/packages/web/server.js` with `SPECS_MODE=filesystem`, opens the browser after launch, and surfaces troubleshooting hints when the build is missing.
-
-**Release automation**
-- `.github/workflows/publish-ui.yml` installs dependencies, runs `pnpm --filter @leanspec/ui build`, and publishes the package with provenance whenever a `ui-v*` tag is pushed or the workflow is dispatched.
+**Phase 1: CLI Command (packages/cli/src/commands/ui.ts)**
+
+```typescript
+import { Command } from 'commander';
+import { spawn } from 'child_process';
+import { existsSync } from 'fs';
+import { resolve, join } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+
+export function registerUiCommand(program: Command) {
+  program
+    .command('ui')
+    .description('Start local web UI for spec management')
+    .option('-s, --specs <dir>', 'Specs directory', './specs')
+    .option('-p, --port <port>', 'Port to run on', '3000')
+    .option('--no-open', "Don't open browser automatically")
+    .option('--dry-run', 'Show what would run without executing')
+    .action(async (options) => {
+      const specsDir = resolve(process.cwd(), options.specs);
+      
+      // Verify specs directory exists
+      if (!existsSync(specsDir)) {
+        console.error(chalk.red(`✗ Specs directory not found: ${specsDir}`));
+        console.log(chalk.dim('\nRun `lean-spec init` to initialize LeanSpec in this directory.'));
+        process.exit(1);
+      }
+      
+      // Check if running in LeanSpec monorepo (dev mode)
+      const localWebDir = join(process.cwd(), 'packages/web');
+      const isMonorepo = existsSync(localWebDir);
+      
+      if (isMonorepo) {
+        // Dev mode: Run local web package
+        return runLocalWeb(localWebDir, options);
+      } else {
+        // Production mode: Run published @leanspec/ui package
+        return runPublishedUI(specsDir, options);
+      }
+    });
+}
+
+async function runLocalWeb(webDir: string, options: any) {
+  console.log(chalk.dim('→ Detected LeanSpec monorepo, using local web package\n'));
+  
+  if (options.dryRun) {
+    console.log(chalk.cyan('Would run:'));
+    console.log(chalk.dim(`  cd ${webDir} && npm run dev`));
+    return;
+  }
+  
+  const spinner = ora('Starting web UI...').start();
+  
+  const child = spawn('npm', ['run', 'dev'], {
+    cwd: webDir,
+    stdio: 'inherit',
+    env: { ...process.env, PORT: options.port }
+  });
+  
+  // Wait for server to be ready
+  setTimeout(async () => {
+    spinner.succeed('Web UI running');
+    console.log(chalk.green(`\n✨ LeanSpec UI: http://localhost:${options.port}\n`));
+    console.log(chalk.dim('Press Ctrl+C to stop\n'));
+    
+    if (options.open) {
+      const open = (await import('open')).default;
+      await open(`http://localhost:${options.port}`);
+    }
+  }, 3000);
+  
+  // Handle shutdown
+  process.on('SIGINT', () => {
+    child.kill();
+    console.log(chalk.dim('\n✓ Web UI stopped'));
+    process.exit(0);
+  });
+}
+
+async function runPublishedUI(specsDir: string, options: any) {
+  if (options.dryRun) {
+    console.log(chalk.cyan('Would run:'));
+    console.log(chalk.dim(`  npx @leanspec/ui --specs ${specsDir} --port ${options.port}`));
+    return;
+  }
+  
+  console.log(chalk.dim('→ Using published @leanspec/ui package\n'));
   
+  const spinner = ora('Starting web UI...').start();
+  
+  const child = spawn('npx', [
+    '@leanspec/ui',
+    '--specs', specsDir,
+    '--port', options.port,
+    options.open ? '' : '--no-open'
+  ].filter(Boolean), {
+    stdio: 'inherit',
+    env: process.env
+  });
+  
+  // Handle shutdown
+  process.on('SIGINT', () => {
+    child.kill();
+    console.log(chalk.dim('\n✓ Web UI stopped'));
+    process.exit(0);
+  });
+}
+```
+
 **Phase 2: Standalone UI Package (packages/ui/)**
 
 Create new package `@leanspec/ui`:
@@ -220,65 +396,67 @@ PORT=3000
 - [x] Fix race conditions and event listener leaks
 - [x] Comprehensive error handling
 
-**Day 3: External Package Delegation** - ✅ **COMPLETE**
-- [x] Implement `runPublishedUI()` that spawns pnpm/yarn/npm runners for `@leanspec/ui`
-- [x] Add specs directory auto-detection (config + heuristics)
-- [x] Add error handling for missing specs / missing build artifacts
-- [x] Add graceful shutdown (SIGINT handling)
-- [x] Test with and without local monorepo context (dry-run)
+**Day 3: External Package Delegation** - 🚧 **TODO**
+- [ ] Implement `runPublishedUI()` that spawns `npx @leanspec/ui`
+- [ ] Add specs directory auto-detection
+- [ ] Add error handling (specs dir not found)
+- [ ] Add graceful shutdown (SIGINT handling)
+- [ ] Test with non-existent @leanspec/ui (show helpful error)
 
-### Phase 2: Standalone UI Package (Week 2) - ✅ **COMPLETE**
+### Phase 2: Standalone UI Package (Week 2) - 🚧 **TODO**
 
 **Day 4-5: Package Structure**
-- [x] Create `packages/ui/` directory
-- [x] Build wrapper + dist copier sourced from `packages/web`
-- [x] Create `bin/ui.js` wrapper script
-- [x] Update package.json with bin entry point + publish config
-- [x] Configure build scripts (`scripts/prepare-dist.mjs` + `prepublishOnly`)
-- [x] Add README with usage + troubleshooting instructions
+- [ ] Create `packages/ui/` directory
+- [ ] Copy/symlink relevant files from `packages/web`
+- [ ] Create `bin/ui.js` wrapper script
+- [ ] Update package.json with bin entry point
+- [ ] Configure build scripts
+- [ ] Add README with usage instructions
 
 **Day 6-7: Standalone Build**
-- [x] Configure Next.js for standalone builds (`output: 'standalone'`)
-- [x] Test production build works and copies nested workspace paths
-- [x] Verify bundle completeness via `node packages/ui/bin/ui.js --dry-run`
-- [x] Add CLI arg parsing (--specs, --port, --no-open, --dry-run)
-- [x] Browser auto-open + graceful shutdown
+- [ ] Configure Next.js for standalone builds
+- [ ] Test production build works
+- [ ] Verify all dependencies bundled correctly
+- [ ] Test bin script launches correctly
+- [ ] Add CLI arg parsing (--specs, --port, --no-open)
+- [ ] Test opening browser automatically
 
 **Day 8: Integration Testing**
-- [x] Test `lean-spec ui` in monorepo (dev mode, dry-run)
-- [x] Test external invocation (`node ... ui --specs ... --dry-run`)
-- [x] Validate missing specs messaging + port validation
-- [ ] Full manual verification of realtime filesystem cache (tracked for follow-up release)
+- [ ] Test `lean-spec ui` in monorepo (dev mode)
+- [ ] Test `npx @leanspec/ui` in external project
+- [ ] Test `lean-spec ui` in external project (delegates to npx)
+- [ ] Verify realtime updates work (spec 082 filesystem mode)
+- [ ] Test error cases (no specs dir, port already in use)
 
 ### Phase 3: Documentation & Polish (Week 3)
 
 **Day 9-10: Documentation**
-- [x] Update CLI help text with `ui` command + specs override example
-- [x] Add examples to main README (Quick Start step 4)
-- [x] Create @leanspec/ui README with usage + env docs
-- [x] Document environment variables in the package README
-- [x] Add troubleshooting guide for the published package
+- [ ] Update CLI help text with `ui` command
+- [ ] Add examples to main README
+- [ ] Create @leanspec/ui README
+- [ ] Document environment variables
+- [ ] Add troubleshooting guide
 
 **Day 11-12: Publishing Preparation**
-- [x] Version bump coordination (`@leanspec/ui@0.3.0`)
-- [x] Update CHANGELOG.md
-- [ ] Test npm publish dry-run (handled during release freeze)
-- [x] Verify package.json metadata + files list
-- [ ] Test installation from npm registry (will happen after first publish)
+- [ ] Version bump coordination (CLI + UI packages)
+- [ ] Update CHANGELOG.md for both packages
+- [ ] Test npm publish dry-run
+- [ ] Verify package.json metadata
+- [ ] Test installation from npm registry
 
 **Day 13: Release**
-- [ ] Publish `@leanspec/ui` to npm (next release tag `ui-v0.3.0`)
-- [ ] Publish updated `lean-spec` CLI to npm (bundled with release cadence)
+- [ ] Publish `@leanspec/ui` to npm
+- [ ] Publish updated `lean-spec` CLI to npm
 - [ ] Create GitHub release with notes
-- [ ] Announce feature in docs/social once npm publish is live
+- [ ] Announce feature in docs and social media
 
 ## Test
 
 ### Functional Testing
 
 **CLI Command:**
-- [x] `lean-spec ui` works in LeanSpec monorepo (dev mode dry-run)
-- [x] `lean-spec ui` works in external projects (delegates via pnpm/yarn/npm dry-run)
+- [x] `lean-spec ui` works in LeanSpec monorepo (launches local web)
+- [ ] `lean-spec ui` works in external project (delegates to @leanspec/ui)
 - [x] `--specs` option overrides auto-detection
 - [x] `--port` option changes port correctly
 - [x] `--no-open` prevents browser from opening
@@ -289,18 +467,19 @@ PORT=3000
 - [x] Package manager detection (pnpm/yarn/npm)
 
 **Standalone UI Package:**
-- [ ] `npx @leanspec/ui` launches web UI (will verify after first publish)
-- [x] Dry-run confirms env vars (SPECS_MODE/SPECS_DIR) and command construction
-- [x] Works with custom `--specs` directory via CLI flag
-- [x] Browser auto-open + graceful shutdown logic implemented
-- [ ] Filesystem mode async cache + live reload acceptance (tracked via spec 082 instrumentation)
+- [ ] `npx @leanspec/ui` launches web UI
+- [ ] Auto-detects specs directory correctly
+- [ ] Works with custom `--specs` directory
+- [ ] Opens browser to correct URL
+- [ ] Environment variables set correctly (SPECS_MODE, SPECS_DIR)
+- [ ] Filesystem mode reads specs correctly
 - [ ] Cache updates work (realtime within 60s)
 
 **Integration:**
-- [x] CLI delegates to standalone package when outside the monorepo (dry-run verification)
-- [x] Monorepo dev mode takes precedence over published package
+- [ ] CLI delegates to standalone package correctly
+- [ ] Monorepo dev mode takes precedence over published package
 - [ ] Both modes can run simultaneously (different ports)
-- [x] Process cleanup works (SIGINT propagated to child processes)
+- [ ] Process cleanup works (no orphaned processes)
 
 ### Performance Testing
 
@@ -388,9 +567,16 @@ PORT=3000
 
 ### Open Questions
 
-- [ ] Should we support watching for file changes (instant reload) beyond the filesystem cache window? (Deferred to a future spec once we feel pain)
-- [ ] Should we add `lean-spec ui export/share` flows for static hosting or temporary sharing?
-- [ ] Should we bundle a version checker (warn if CLI/UI versions are out of sync)? (Candidate for the docs polish phase)
+- [ ] Should `@leanspec/ui` be in this monorepo or separate repo?
+  - **Recommendation**: Same monorepo (`packages/ui/`)
+- [ ] Should we support watching for file changes (instant reload)?
+  - **Recommendation**: Spec 082 cache (60s) is sufficient for v1
+- [ ] Should UI command be `lean-spec ui` or `lean-spec web`?
+  - **Recommendation**: `ui` is shorter, more intuitive
+- [ ] Should we add `lean-spec ui build` for static export?
+  - **Recommendation**: Not needed yet, defer to future
+- [ ] Should we bundle a version checker (warn if outdated)?
+  - **Recommendation**: Yes, add to Phase 3
 
 ### Related Work
 

package/.next/standalone/packages/ui/dist/standalone/specs/088-core-concepts-terminology-only/README.md

@@ -1,10 +1,10 @@
 ---
-status: complete
+status: planned
 created: '2025-11-17'
 tags: []
 priority: high
 created_at: '2025-11-17T02:09:38.041Z'
-updated_at: '2025-11-17T09:14:30.117Z'
+updated_at: '2025-11-17T02:58:35.396Z'
 transitions:
   - status: in-progress
     at: '2025-11-17T02:10:38.350Z'
@@ -12,15 +12,13 @@ transitions:
     at: '2025-11-17T02:10:43.845Z'
   - status: planned
     at: '2025-11-17T02:58:35.396Z'
-  - status: complete
-    at: '2025-11-17T09:14:30.117Z'
 completed_at: '2025-11-17T02:10:43.845Z'
 completed: '2025-11-17'
 ---
 
 # Core Concepts: Real SDD Terminology Only
 
-> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17
+> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-17
 
 **Project**: lean-spec  
 **Team**: Core Development