@leanspec/ui 0.2.8 → 0.2.9-dev.20251205030455

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

@@ -1,607 +0,0 @@
----
-status: in-progress
-created: '2025-11-17'
-tags:
-  - cli
-  - web
-  - dx
-  - integration
-priority: medium
-created_at: '2025-11-17T01:31:21.397Z'
-related:
-  - 035-live-specs-showcase
-  - 081-web-app-ux-redesign
-  - 082-web-realtime-sync-architecture
-updated_at: '2025-11-17T04:41:33.637Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T01:59:34.354Z'
-completed_at: '2025-11-17T02:00:24.131Z'
-completed: '2025-11-17'
----
-
-# CLI UI Command: `lean-spec ui`
-
-> **Status**: ⏳ In progress · **Priority**: Medium · **Created**: 2025-11-17 · **Tags**: cli, web, dx, integration
-
-**Project**: lean-spec  
-**Team**: Core Development  
-**Related**: Spec 035 (live-specs-showcase), Spec 081 (web-app-ux-redesign), Spec 082 (web-realtime-sync-architecture)
-
-## Current Status
-
-**Phase 1: CLI Command (Monorepo Mode)** - ✅ **COMPLETE**
-- Basic `lean-spec ui` command implemented with all options
-- Monorepo detection working (checks for `packages/web`)
-- Package manager auto-detection (pnpm/yarn/npm)
-- Port validation (1-65535 range)
-- Robust error handling and graceful shutdown
-- 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)**
-
-```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`:
-
-```json
-{
-  "name": "@leanspec/ui",
-  "version": "0.3.0",
-  "description": "Web UI for LeanSpec - visual spec management",
-  "bin": {
-    "leanspec-ui": "./bin/ui.js"
-  },
-  "dependencies": {
-    "@leanspec/core": "workspace:*",
-    "next": "16.0.1",
-    "react": "19.2.0",
-    "react-dom": "19.2.0"
-    // ... other web dependencies
-  },
-  "scripts": {
-    "build": "next build",
-    "start": "node bin/ui.js"
-  }
-}
-```
-
-**Standalone UI Wrapper (packages/ui/bin/ui.js):**
-
-```javascript
-#!/usr/bin/env node
-import { spawn } from 'child_process';
-import { resolve } from 'path';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const nextDir = join(__dirname, '..');
-
-// Parse CLI args
-const args = process.argv.slice(2);
-const specsDir = args[args.indexOf('--specs') + 1] || './specs';
-const port = args[args.indexOf('--port') + 1] || '3000';
-const noOpen = args.includes('--no-open');
-
-// Set environment variables
-process.env.SPECS_DIR = resolve(process.cwd(), specsDir);
-process.env.PORT = port;
-process.env.SPECS_MODE = 'filesystem'; // Force filesystem mode
-
-// Start Next.js server
-const child = spawn('next', ['start'], {
-  cwd: nextDir,
-  stdio: 'inherit',
-  env: process.env
-});
-
-// Open browser
-if (!noOpen) {
-  setTimeout(async () => {
-    const open = (await import('open')).default;
-    await open(`http://localhost:${port}`);
-  }, 2000);
-}
-
-process.on('SIGINT', () => {
-  child.kill();
-  process.exit(0);
-});
-```
-
-### Package Publishing Strategy
-
-**Option 1: Separate @leanspec/ui package** (Recommended)
-- **Pros**: Clean separation, can be used standalone, smaller CLI package
-- **Cons**: One more package to maintain
-- **Use case**: External projects using `npx lean-spec ui`
-
-**Option 2: Bundle in @leanspec/web**
-- **Pros**: Reuse existing package
-- **Cons**: Web package is currently private, larger dependency
-- **Use case**: Make `@leanspec/web` public with CLI wrapper
-
-**Option 3: Bundle in lean-spec CLI**
-- **Pros**: Single package install
-- **Cons**: CLI becomes massive (Next.js + React = ~50MB)
-- **Use case**: All-in-one installation
-
-**Recommendation: Option 1** - Create `@leanspec/ui` as a thin wrapper around `@leanspec/web` that:
-- Shares code with `@leanspec/web` (monorepo symlinks)
-- Has its own bin/ui.js entry point
-- Can be published separately
-- CLI delegates to it via `npx @leanspec/ui`
-
-### Auto-Detection Logic
-
-```typescript
-function detectSpecsDirectory(): string | null {
-  const candidates = [
-    './specs',
-    './spec',
-    './docs/specs',
-    './docs/spec',
-    './.lean-spec/specs'
-  ];
-  
-  for (const candidate of candidates) {
-    if (existsSync(resolve(process.cwd(), candidate))) {
-      return candidate;
-    }
-  }
-  
-  // Check for leanspec.yaml config
-  const configPath = resolve(process.cwd(), 'leanspec.yaml');
-  if (existsSync(configPath)) {
-    const config = yaml.load(readFileSync(configPath, 'utf-8'));
-    return config.specsDirectory || null;
-  }
-  
-  return null;
-}
-```
-
-### Integration with Spec 082 Architecture
-
-The web UI will use the **filesystem mode** (spec 082) for local projects:
-
-- Direct reads from `specs/` directory (no database required)
-- In-memory caching with 60s TTL
-- Realtime updates (changes appear within 60s)
-- No manual seeding or sync required
-
-**Environment Configuration:**
-```bash
-# Automatically set by lean-spec ui command
-SPECS_MODE=filesystem
-SPECS_DIR=/absolute/path/to/project/specs
-PORT=3000
-```
-
-## Plan
-
-### Phase 1: CLI Command (Week 1)
-
-**Day 1-2: Basic Command Implementation** - ✅ **COMPLETE**
-- [x] Create `packages/cli/src/commands/ui.ts`
-- [x] Implement command registration in registry
-- [x] Add monorepo detection logic (check for `packages/web`)
-- [x] Implement `runLocalWeb()` for dev mode
-- [x] Add port, specs-dir, and no-open options
-- [x] Add `--dry-run` flag for testing
-- [x] Test in LeanSpec monorepo
-- [x] Add port validation (1-65535)
-- [x] Auto-detect package manager (pnpm/yarn/npm)
-- [x] Fix race conditions and event listener leaks
-- [x] Comprehensive error handling
-
-**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) - 🚧 **TODO**
-
-**Day 4-5: Package Structure**
-- [ ] 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**
-- [ ] 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**
-- [ ] 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**
-- [ ] 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**
-- [ ] 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
-- [ ] Publish updated `lean-spec` CLI to npm
-- [ ] Create GitHub release with notes
-- [ ] Announce feature in docs and social media
-
-## Test
-
-### Functional Testing
-
-**CLI Command:**
-- [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
-- [x] `--dry-run` shows what would run without executing
-- [x] Error message when specs directory not found
-- [x] Graceful shutdown on Ctrl+C
-- [x] Port validation (1-65535 range)
-- [x] Package manager detection (pnpm/yarn/npm)
-
-**Standalone UI Package:**
-- [ ] `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:**
-- [ ] CLI delegates to standalone package correctly
-- [ ] Monorepo dev mode takes precedence over published package
-- [ ] Both modes can run simultaneously (different ports)
-- [ ] Process cleanup works (no orphaned processes)
-
-### Performance Testing
-
-- [ ] Startup time <5s (cold start)
-- [ ] Startup time <2s (warm cache)
-- [ ] Memory usage reasonable (<200MB)
-- [ ] No memory leaks during extended runs
-
-### Compatibility Testing
-
-- [ ] Works on macOS
-- [ ] Works on Linux
-- [ ] Works on Windows (WSL)
-- [ ] Works with Node 20+
-- [ ] Works with npm, pnpm, yarn
-- [ ] Works when installed globally vs locally
-
-### User Experience Testing
-
-- [ ] Clear startup messages
-- [ ] Helpful error messages
-- [ ] Browser opens to correct page
-- [ ] UI loads specs correctly
-- [ ] Changes to specs appear within 60s
-- [ ] Shutdown is clean (no errors)
-
-## Notes
-
-### Design Decisions
-
-**Why separate @leanspec/ui package?**
-- **Clean separation**: CLI stays lightweight, UI is separate concern
-- **Standalone use**: Users can run `npx @leanspec/ui` directly
-- **Smaller CLI**: Don't bloat CLI with Next.js/React dependencies
-- **Easier maintenance**: UI can version independently
-
-**Why not bundle UI in CLI?**
-- **Size**: Next.js + React = ~50MB, too large for CLI
-- **Dependencies**: React, Next.js not needed for CLI users who never use UI
-- **Complexity**: Build process more complicated
-- **Performance**: Slower CLI startup if bundled
-
-**Why detect monorepo mode?**
-- **Dev experience**: LeanSpec contributors shouldn't need published package
-- **Faster iteration**: Local changes immediately available
-- **Flexibility**: Can test unreleased UI changes
-
-**Why filesystem mode (spec 082)?**
-- **No setup**: Works immediately, no database required
-- **Realtime**: Changes appear within 60s (cache TTL)
-- **Simple**: Single source of truth (specs/ directory)
-- **Fast**: <100ms reads from filesystem
-
-### Package Size Comparison
-
-| Package | Compressed | Unpacked | Dependencies |
-|---------|-----------|----------|--------------|
-| `lean-spec` CLI | ~500KB | ~2MB | 20 packages |
-| `@leanspec/ui` | ~5MB | ~25MB | Next.js, React, UI libs |
-| **Combined** | ~5.5MB | ~27MB | Separate installs |
-
-**If bundled in CLI**: ~50MB unpacked (not acceptable)
-
-### Alternative Approaches Considered
-
-**1. Embedded Server in CLI**
-- Pros: Single package
-- Cons: Massive size, complex build, slow startup
-- **Rejected**: Too complex, violates Unix philosophy
-
-**2. Static HTML Export**
-- Pros: No server needed, tiny package
-- Cons: No realtime updates, limited interactivity
-- **Rejected**: Defeats purpose of web UI
-
-**3. Electron App**
-- Pros: Native feel, auto-updates
-- Cons: Even larger (100MB+), more maintenance
-- **Rejected**: Overkill for this use case
-
-**4. Browser Extension**
-- Pros: Integrated in browser
-- Cons: Limited filesystem access, requires extension install
-- **Rejected**: Adds friction to workflow
-
-### Open Questions
-
-- [ ] 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
-
-- **Spec 035**: Live Specs Showcase - Web app foundation
-- **Spec 081**: Web App UX Redesign - UI improvements
-- **Spec 082**: Web Realtime Sync Architecture - Filesystem mode enables this
-
-### Future Enhancements
-
-**v0.4+:**
-- [ ] `lean-spec ui export` - Static HTML export
-- [ ] `lean-spec ui share` - Temporary public URL (via ngrok/tunneling)
-- [ ] `lean-spec ui --watch` - Instant reload on file changes
-- [ ] Desktop app wrapper (Tauri/Electron)
-- [ ] VSCode webview integration (spec 017)
-- [ ] Multi-project mode (switch between projects in UI)
-
-### Dependencies
-
-**This spec depends on:**
-- Spec 082 (filesystem mode) - Must be complete for realtime updates
-- Spec 081 (UX redesign) - UI should be polished before exposing via CLI
-
-**This spec enables:**
-- Better DX for visual learners
-- Easier onboarding (show, don't tell)
-- Spec 017 (VSCode extension) - Can embed UI in webview
-- External adoption - Easy way to explore LeanSpec

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

@@ -1,104 +0,0 @@
----
-status: planned
-created: '2025-11-17'
-tags: []
-priority: high
-created_at: '2025-11-17T02:09:38.041Z'
-updated_at: '2025-11-17T02:58:35.396Z'
-transitions:
-  - status: in-progress
-    at: '2025-11-17T02:10:38.350Z'
-  - status: complete
-    at: '2025-11-17T02:10:43.845Z'
-  - status: planned
-    at: '2025-11-17T02:58:35.396Z'
-completed_at: '2025-11-17T02:10:43.845Z'
-completed: '2025-11-17'
----
-
-# Core Concepts: Real SDD Terminology Only
-
-> **Status**: 🗓️ Planned · **Priority**: High · **Created**: 2025-11-17
-
-**Project**: lean-spec  
-**Team**: Core Development
-
-## Overview
-
-Users report that the current "Core Concepts" section in docs-site contains philosophy and principles rather than actual terminology definitions. This creates confusion for newcomers trying to understand SDD basics.
-
-**Problem**: Current Core Concepts mixes:
-- Philosophical principles (first principles, progressive disclosure)
-- Process guidance (workflow, decision-making)
-- Actual SDD terminology (specs, tokens, context)
-
-**Goal**: Restructure Core Concepts to be a **glossary of essential SDD terms** only:
-- **Spec**: What is a specification in SDD context
-- **Context**: What context means (human + AI working memory)
-- **Tokens**: Why tokens matter for AI + human cognition
-- **Agent**: AI agents in SDD workflow
-- **Status**: Spec lifecycle states
-- **Dependencies**: Relationship between specs
-- Other concrete terms users encounter when using LeanSpec
-
-**Non-Goals**: 
-- Philosophy content → move to "Philosophy & Principles" section
-- Workflow guidance → move to tutorials/guides
-- Decision frameworks → keep in methodology docs
-
-## Design
-
-**Restructure Core Concepts as a terminology glossary with definitions only.**
-
-Each concept entry should:
-1. **Definition**: What it is (1-2 sentences)
-2. **Why it matters**: Practical importance for SDD
-3. **Example**: Concrete example from LeanSpec usage
-4. **Related**: Links to deeper explanations
-
-**Priority order for inclusion**:
-1. Terms users encounter in first 5 minutes (spec, status, tokens)
-2. Terms in CLI/UI (tags, priority, dependencies)
-3. SDD methodology terms (context, agent, signal-to-noise)
-4. Advanced concepts (progressive disclosure, templates)
-
-**Content reorganization**:
-- Philosophy → New "Philosophy & Principles" section
-- Workflow → Move to step-by-step tutorials (spec 089)
-- Decision frameworks → Keep in "Methodology" docs
-
-**Term structure template**:
-```markdown
-### [Term Name]
-
-**Definition**: [One sentence explanation]
-
-**Why it matters**: [Practical importance in SDD workflow]
-
-**Example**: 
-[Concrete example from LeanSpec usage]
-
-**See also**: [Links to related concepts or deeper docs]
-```
-
-## Plan
-
-- [ ] Audit current Core Concepts docs - identify what's philosophy vs terminology
-- [ ] Create list of essential SDD terms users encounter
-- [ ] Write clean definitions for each term (using template)
-- [ ] Create new "Philosophy & Principles" section in docs
-- [ ] Move philosophical content to new section
-- [ ] Update navigation/sidebar in docs-site
-- [ ] Verify all cross-references still work
-
-## Test
-
-- [ ] New user can find definition of any term they encounter in first use
-- [ ] Each term has clear, concise definition (no philosophy/principles mixed in)
-- [ ] Examples are concrete and actionable
-- [ ] Philosophy content successfully moved to separate section
-- [ ] All internal doc links still work after reorganization
-
-## Notes
-
-<!-- Optional: Research findings, alternatives considered, open questions -->