@leanspec/ui 0.2.7-dev.20251126090633 → 0.2.7

package/.next/standalone/packages/ui/dist/standalone/specs/086-template-component-deduplication/README.md

@@ -0,0 +1,146 @@
+---
+status: complete
+created: '2025-11-17'
+tags:
+  - refactoring
+  - templates
+  - maintenance
+priority: high
+created_at: '2025-11-17T01:27:01.679Z'
+updated_at: '2025-11-17T01:40:10.673Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-17T01:27:44.713Z'
+  - status: complete
+    at: '2025-11-17T01:40:10.673Z'
+completed_at: '2025-11-17T01:40:10.673Z'
+completed: '2025-11-17'
+---
+
+# template-component-deduplication
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-17 · **Tags**: refactoring, templates, maintenance
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+### Problem
+Template component files in `packages/cli/templates/_shared/agents-components/` contain significant code redundancy. When updating shared content (like status tracking requirements), we must edit multiple files with duplicate content, creating maintenance burden and risk of inconsistency.
+
+**Example redundancy patterns:**
+- `core-rules-base.md` and `core-rules-enterprise.md` both have "Never use nested code blocks" rule
+- `discovery-commands-{minimal,standard,enterprise}.md` share common intro text and progressive command additions
+- `essential-commands-{minimal,standard,enterprise}.md` have massive overlap (15→28→38 lines with shared sections)
+
+### Why Now
+We just improved status update instructions in AGENTS.md and had to update the same content in multiple files. This highlighted the maintenance problem and showed we need a DRY solution before making more updates.
+
+### Success Criteria
+- Shared content exists in exactly ONE file
+- Pattern-specific differences in separate addition files
+- Build system composes components automatically
+- Future updates to shared content require editing only one file
+- Generated AGENTS.md files remain functionally identical
+
+## Design
+
+### Refactoring Strategy
+
+Apply composition pattern (already proven for quality-standards):
+
+**1. Extract Shared Components**
+- Create base files with only truly common content
+- Name pattern: `{section}-shared.md`
+
+**2. Create Pattern-Specific Additions**
+- Files with only differences per pattern
+- Name pattern: `{section}-{pattern}-additions.md`
+
+**3. Use Array Composition in Config**
+```json
+"essentialCommands": [
+  "essential-commands-shared.md",
+  "essential-commands-standard-additions.md"
+]
+```
+
+### Files to Refactor
+
+**Priority 1: Essential Commands** (highest redundancy)
+- Shared: Header, Discovery, Viewing, Working basics, closing line
+- Minimal: Only basic commands
+- Standard: + Project Overview, Token Management, more detail
+- Enterprise: + Enterprise-specific commands
+
+**Priority 2: Discovery Commands** (progressive additions)
+- Shared: Intro text + base commands (stats, board, list, search)
+- Standard additions: + deps
+- Enterprise additions: + gantt
+
+**Priority 3: Core Rules** (one shared line)
+- Shared: "Never use nested code blocks" rule
+- Base additions: Base-specific rules
+- Enterprise additions: Enterprise-specific rules
+
+## Plan
+
+### Phase 1: Essential Commands Refactoring ✅ COMPLETE
+- [x] Analyze redundancy in essential-commands files
+- [x] Create `essential-commands-shared.md` with common content
+- [x] Create `essential-commands-minimal-additions.md`
+- [x] Create `essential-commands-standard-additions.md`
+- [x] Create `essential-commands-enterprise-additions.md`
+- [x] Update configs to use arrays
+- [x] Rebuild and verify output
+- [x] Delete old files
+
+### Phase 2: Discovery Commands Refactoring ✅ COMPLETE
+- [x] Create `discovery-commands-shared.md`
+- [x] Create pattern-specific addition files
+- [x] Update build script if needed (support for discoveryCommands array)
+- [x] Update configs
+- [x] Rebuild and verify
+- [x] Delete old files
+
+### Phase 3: Core Rules Refactoring ✅ COMPLETE
+- [x] Create `core-rules-shared.md`
+- [x] Create pattern-specific addition files
+- [x] Update configs
+- [x] Rebuild and verify
+- [x] Delete old files
+
+### Phase 4: Audit Other Components
+- [ ] Review remaining component files for redundancy
+- [ ] Document any other refactoring opportunities
+
+## Test
+
+- [ ] All three AGENTS.md templates generate successfully
+- [ ] Generated files are functionally identical to pre-refactor versions (diff check)
+- [ ] Build script supports arrays for all relevant config fields
+- [ ] No broken references to old component files
+- [ ] Token counts remain similar (no content lost)
+- [ ] Update status tracking instruction as test - should only require 1 file edit
+
+## Notes
+
+### Already Completed (Quality Standards)
+We successfully refactored quality-standards using this same approach:
+- Created `quality-standards-shared.md` (common standards)
+- Created `quality-standards-{minimal,enterprise}-additions.md`
+- Created `status-update-triggers.md` (extracted from workflow files)
+- Deleted `quality-standards-base.md` and `quality-standards-enterprise.md`
+
+This serves as the proven pattern for the remaining refactorings.
+
+### Build Script Enhancements
+Already supports:
+- `string | string[]` for workflow and qualityStandards
+- `readComponents()` function for composition
+
+May need to extend support to:
+- `discoveryCommands` (currently only string)
+- `coreRules` (currently only string)
+- `essentialCommands` (currently optional string)

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

@@ -0,0 +1,421 @@
+---
+status: complete
+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-17T06:12:03.020Z'
+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
+
+**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
+
+### 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 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** - ✅ **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)
+
+### Phase 2: Standalone UI Package (Week 2) - ✅ **COMPLETE**
+
+**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
+
+**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
+
+**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)
+
+### 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
+
+**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)
+
+**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)
+- [ ] Create GitHub release with notes
+- [ ] Announce feature in docs/social once npm publish is live
+
+## 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] `--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 (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)
+- [ ] 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
+- [ ] Both modes can run simultaneously (different ports)
+- [x] Process cleanup works (SIGINT propagated to child 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 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)
+
+### 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

@@ -0,0 +1,106 @@
+---
+status: complete
+created: '2025-11-17'
+tags: []
+priority: high
+created_at: '2025-11-17T02:09:38.041Z'
+updated_at: '2025-11-17T09:14:30.117Z'
+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'
+  - 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
+
+**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 -->