@leanspec/ui 0.2.7-dev.20251128020042 → 0.2.8

package/.next/standalone/packages/ui/dist/standalone/specs/058-docs-overview-polish/NOTES.md

@@ -0,0 +1,125 @@
+# Implementation Notes
+
+## Scope Evolution
+
+**Original Scope** (minor polish):
+- Fix feature list in overview
+- Fix example structure mismatch
+- Fix cosmetic date issue
+
+**Expanded Scope** (comprehensive restructure):
+- Restructure entire navigation (AI Integration → Working with AI in Guide)
+- Add First Principles doc (from spec 049)
+- Migrate all `docs/` content into docs-site
+- Create Workflow section (board, stats, deps, validate)
+- Update all Core Concepts to align with First Principles
+
+**Rationale for Scope Change**:
+1. **User feedback identified structural issues** - AI Integration tab placement is wrong
+2. **First Principles spec (049) completed** - Must be reflected in docs
+3. **Duplicate content causes confusion** - `docs/` folder vs docs-site
+4. **v0.2.0 launch approaching** - Must get structure right before launch
+
+## Key Architectural Decisions
+
+**Decision #1: AI Integration → Working with AI in Guide**
+
+- **Rationale**: LeanSpec is fundamentally AI-native, not AI-optional
+- **Impact**: Changes mental model from "docs + optional AI add-on" to "AI-integrated workflow"
+- **First Principle**: Bridge the Gap (align human intent with machine execution)
+
+**Decision #2: First Principles as Foundation**
+
+- **Rationale**: Everything derives from these 5 principles (spec 049)
+- **Impact**: Shows clear derivation hierarchy: Principles → Philosophy → Practice
+- **First Principle**: Intent Over Implementation (capture why, not just how)
+
+**Decision #3: Consolidate `docs/` into docs-site**
+
+- **Rationale**: Single source of truth, eliminate confusion
+- **Impact**: Better discoverability, easier maintenance, integrated navigation
+- **First Principle**: Context Economy (reduce cognitive load)
+
+**Decision #4: Add Workflow Section**
+
+- **Rationale**: Users need practical workflows, not just CLI reference
+- **Impact**: Shows how to use board, stats, deps, validate in real workflows
+- **First Principle**: Progressive Disclosure (add structure when useful)
+
+## Migration Impact
+
+**Breaking Changes**: None (only documentation reorganization)
+
+**User Impact**:
+- Old links redirect (e.g., `/docs/ai-integration/` → `/docs/guide/`)
+- `docs/` folder deprecated but kept for backwards compatibility
+- All content still accessible, just better organized
+
+**Maintenance Impact**:
+- Single docs source (docs-site) instead of two (`docs/` + docs-site)
+- Easier to keep docs in sync with code
+- Clear structure for future additions
+
+## Timeline Considerations
+
+**Estimated Effort**: 
+- Phase 1-2: 2-3 hours (navigation + core concepts)
+- Phase 3-4: 3-4 hours (AI content + migration)
+- Phase 5-6: 2-3 hours (workflow + overview updates)
+- Phase 7-8: 1-2 hours (testing + polish)
+- **Total**: 8-12 hours
+
+**Critical Path**: 
+1. Phase 2 (First Principles) - Foundation for everything else
+2. Phase 3 (AI content move) - Biggest structural change
+3. Phase 7 (Testing) - Ensure nothing breaks
+
+## Related Work
+
+**Dependencies**:
+- Spec 049 (First Principles) - MUST be complete (✅ Done)
+- Spec 043 (v0.2.0 Launch) - This blocks launch
+- Spec 057 (Validation) - Identified issues
+
+**Blocked By**: None
+
+**Blocks**:
+- v0.2.0 launch (spec 043)
+- Future docs updates (need correct structure first)
+
+## Success Metrics
+
+**Quantitative**:
+- Zero broken links
+- Build time <30 seconds
+- All internal references updated
+- Zero 404s after deployment
+
+**Qualitative**:
+- Navigation flows logically (Introduction → Concepts → AI → Features → Workflow)
+- First Principles clearly explained
+- AI integration feels core, not optional
+- Users can find what they need in <2 clicks
+
+**Dogfooding**:
+- This spec itself follows First Principles
+- Uses progressive disclosure (comprehensive but organized)
+- Signal-to-noise high (every section informs decisions)
+- Context economy maintained (split into sub-specs)
+
+## Lessons Learned
+
+**What Worked**:
+- User feedback caught structural issues early
+- Having First Principles (spec 049) made decisions clear
+- Comprehensive analysis revealed deeper issues than original scope
+
+**What to Improve**:
+- Should have aligned docs structure with First Principles from the start
+- Earlier consolidation of `docs/` folder would have prevented confusion
+
+**What's Next** (Post-Launch):
+- Consider automated link checking in CI
+- Add visual diagrams to First Principles doc
+- Create interactive examples for workflow section
+- Video walkthroughs for AI integration setup

package/.next/standalone/packages/ui/dist/standalone/specs/058-docs-overview-polish/README.md

@@ -0,0 +1,286 @@
+---
+status: complete
+created: '2025-11-07'
+tags:
+  - documentation
+  - quality
+  - restructure
+  - first-principles
+priority: high
+related:
+  - '056'
+  - '057'
+  - 049
+depends_on:
+  - 049
+created_at: '2025-11-07T01:53:09.673Z'
+updated_at: '2025-11-07T15:18:39.640Z'
+transitions:
+  - status: in-progress
+    at: '2025-11-07T02:17:43.534Z'
+  - status: complete
+    at: '2025-11-07T02:19:49.555Z'
+  - status: in-progress
+    at: '2025-11-07T08:00:00.000Z'
+  - status: complete
+    at: '2025-11-07T07:03:23.727Z'
+  - status: in-progress
+    at: '2025-11-07T07:12:56.735Z'
+  - status: complete
+    at: '2025-11-07T15:18:39.640Z'
+completed_at: '2025-11-07T02:19:49.555Z'
+completed: '2025-11-07'
+---
+
+# Docs-Site Comprehensive Restructure
+
+> **Status**: ✅ Complete · **Priority**: High · **Created**: 2025-11-07 · **Tags**: documentation, quality, restructure, first-principles
+
+**Project**: lean-spec  
+**Team**: Core Development
+
+## Overview
+
+**Comprehensive docs-site restructure** to align with LeanSpec First Principles (spec 049) and fix structural issues.
+
+**Scope Changed**: Originally minor polish, now major restructure based on findings:
+1. ❌ **AI Integration as separate tab** - Wrong! AI is core to LeanSpec, not optional add-on
+2. ❌ **Core Concepts outdated** - Doesn't align with First Principles (spec 049)
+3. ❌ **`docs/` folder not integrated** - Valuable content (MCP, migration, examples) not in docs-site
+4. ❌ **Navigation structure suboptimal** - Doesn't reflect actual workflow
+
+**Why Now**: 
+- Part of v0.2.0 launch (spec 043) - must be right before launch
+- Spec 049 established First Principles - docs must reflect them
+- Current structure treats AI as optional when it's fundamental
+- Duplicate content in `docs/` folder causes confusion
+
+**Result**: Cohesive, principle-driven documentation that reflects LeanSpec's AI-native identity.
+
+## Problems Identified
+
+**See [ANALYSIS.md](./ANALYSIS.md) for detailed problem analysis.**
+
+**Summary of Key Issues**:
+
+1. **AI Integration Structure is Wrong** (Critical)
+   - Separate "AI Integration" tab treats AI as optional
+   - Should be integrated into Guide as "Working with AI"
+   - Contradicts AI-native identity
+
+2. **Core Concepts Missing First Principles** (Critical)
+   - Spec 049 established 5 First Principles (Context Economy, Signal-to-Noise, etc.)
+   - Current docs don't have First Principles doc
+   - Philosophy appears arbitrary without showing foundation
+
+3. **`docs/` Folder Not Integrated** (High Priority)
+   - Valuable content exists outside docs-site (MCP-SERVER.md, MIGRATION.md, examples)
+   - Causes confusion and duplication
+   - Need single source of truth
+
+4. **Navigation Doesn't Reflect Workflow** (Medium Priority)
+   - No workflow section (board, stats, deps, validate)
+   - Features and workflow mixed
+   - Doesn't show progression: Concepts → Setup → Workflow → Reference
+
+## Design
+
+**See [DESIGN.md](./DESIGN.md) for complete design documentation.**
+
+**See [IMPLEMENTATION.md](./IMPLEMENTATION.md) for detailed implementation specifications** (content templates, migration steps, code examples).
+
+### Navigation Structure (Summary)
+
+**New Structure**:
+```
+Guide/
+  Introduction/ (Overview, Getting Started, Examples)
+  Core Concepts/ (First Principles, Philosophy, When to Use)
+  Working with AI/ (Setup, Best Practices, Examples)
+  Features/ (Templates, Custom Fields, Variables)
+  Workflow/ (Board & Stats, Dependencies, Validation)
+  Migration
+  
+Reference/
+  CLI Commands
+  Configuration
+  Frontmatter Schema
+  MCP Server API
+  
+Roadmap
+```
+
+**Key Changes**:
+1. ✅ AI Integration moved into Guide as "Working with AI"
+2. ✅ First Principles added (from spec 049)
+3. ✅ Workflow section added (board, stats, deps, validate)
+4. ✅ MCP Server API in Reference
+5. ✅ Single AI tab removed
+
+### Content Updates (Summary)
+
+1. **Add First Principles doc** - Extract from spec 049, adapt for docs-site
+2. **Update Philosophy** - Show derivation from First Principles
+3. **Migrate AI content** - Move ai-integration/ into guide/
+4. **Consolidate `docs/`** - Merge MCP-SERVER.md, MIGRATION.md, examples into docs-site
+5. **Create Workflow docs** - New guides for board, stats, deps, validate
+6. **Update Overview** - Better feature grouping, prominently feature MCP
+
+## Plan
+
+### Phase 1: Navigation & Structure (Foundation)
+- [ ] Update `sidebars.ts` with new structure
+  - [ ] Move AI Integration content into guideSidebar
+  - [ ] Add Core Concepts with first-principles
+  - [ ] Add Workflow section
+  - [ ] Add MCP Server to Reference
+  - [ ] Remove aiSidebar
+- [ ] Test navigation build (ensure no broken links)
+
+### Phase 2: Core Concepts (Critical Content)
+- [ ] Create `docs-site/docs/guide/first-principles.mdx`
+  - [ ] Extract content from spec 049 (FIRST-PRINCIPLES.md)
+  - [ ] Adapt for docs-site format (Docusaurus)
+  - [ ] Add clear examples and conflict resolution framework
+- [ ] Update `docs-site/docs/guide/philosophy.mdx`
+  - [ ] Add intro linking to First Principles
+  - [ ] Show how philosophy derives from principles
+  - [ ] Update Core Philosophy section with derivation
+- [ ] Update `docs-site/docs/guide/principles.mdx`
+  - [ ] Add note: "Agile Principles derive from First Principles"
+  - [ ] Link to First Principles doc
+
+### Phase 3: Working with AI (Move from Separate Tab)
+- [ ] Rename/move AI integration content into Guide
+  - [ ] `ai-integration/index.mdx` → `guide/ai-setup.mdx`
+  - [ ] `ai-integration/setup.mdx` → merge into `guide/ai-setup.mdx`
+  - [ ] `ai-integration/best-practices.mdx` → `guide/ai-best-practices.mdx`
+  - [ ] `ai-integration/examples.mdx` → `guide/ai-examples.mdx`
+  - [ ] `ai-integration/agents-md.mdx` → incorporate into `guide/ai-setup.mdx`
+- [ ] Update internal links (all references to `/docs/ai-integration/` → `/docs/guide/`)
+- [ ] Delete old `docs-site/docs/ai-integration/` directory
+
+### Phase 4: Migrate `docs/` Content (Consolidation)
+- [ ] Create `docs-site/docs/reference/mcp-server.mdx`
+  - [ ] Migrate content from `docs/MCP-SERVER.md`
+  - [ ] Enhance with comprehensive setup, troubleshooting, security
+  - [ ] Format for Docusaurus
+- [ ] Create `docs-site/docs/guide/migration.mdx`
+  - [ ] Migrate content from `docs/MIGRATION.md`
+  - [ ] Add to Guide section
+- [ ] Enhance `docs-site/docs/guide/custom-fields.mdx`
+  - [ ] Incorporate examples from `docs/examples/CUSTOM-FIELDS-GUIDE.md`
+  - [ ] Add config examples from `docs/examples/`
+- [ ] Deprecate `docs/` folder
+  - [ ] Create `docs/README.md` with redirect message
+  - [ ] Keep folder but mark as deprecated
+
+### Phase 5: Workflow Section (New Content)
+- [ ] Create `docs-site/docs/guide/board-stats.mdx`
+  - [ ] Document board and stats commands
+  - [ ] Show project visibility workflows
+- [ ] Create `docs-site/docs/guide/dependencies.mdx`
+  - [ ] Document deps command
+  - [ ] Explain `related` vs `depends_on`
+  - [ ] Show relationship patterns
+- [ ] Create `docs-site/docs/guide/validation.mdx`
+  - [ ] Document validate command
+  - [ ] Explain complexity analysis
+  - [ ] Show quality workflows
+
+### Phase 6: Overview Updates (Original Scope)
+- [ ] Update `docs-site/docs/guide/index.mdx`
+  - [ ] Replace "How It Works" with "What You Get"
+  - [ ] Prominently feature MCP server
+  - [ ] Group features: CLI, MCP, Templates
+  - [ ] Update example to match actual templates
+  - [ ] Fix example date
+  - [ ] Link to roadmap page
+
+### Phase 7: Testing & Validation
+- [ ] Build docs-site: `cd docs-site && npm run build`
+- [ ] Verify no broken links
+- [ ] Check all internal references updated
+- [ ] Review navigation flow
+- [ ] Test search functionality
+- [ ] Validate on mobile/desktop
+
+### Phase 8: Cleanup & Polish
+- [ ] Update README.md if needed (ensure it matches docs-site)
+- [ ] Update AGENTS.md with new doc structure
+- [ ] Archive or remove redundant content
+- [ ] Add migration notes to CHANGELOG.md
+
+## Test
+
+**Success Criteria**:
+
+### Navigation & Structure
+- [ ] AI Integration moved into Guide as "Working with AI"
+- [ ] First Principles doc exists and is prominent
+- [ ] Workflow section exists (board-stats, dependencies, validation)
+- [ ] MCP Server reference complete and comprehensive
+- [ ] No separate AI Integration tab
+- [ ] Sidebar navigation logical and intuitive
+
+### Content Quality
+- [ ] First Principles clearly explained with examples
+- [ ] Philosophy shows derivation from First Principles
+- [ ] All `docs/` content integrated into docs-site
+- [ ] MCP Server docs comprehensive (setup, troubleshooting, security)
+- [ ] Migration guide complete
+- [ ] Custom fields examples included
+
+### Completeness
+- [ ] MCP server prominently featured in overview
+- [ ] Features grouped logically (CLI, MCP, Templates)
+- [ ] Workflow docs complete (board, stats, deps, validate)
+- [ ] All internal links updated (no `/docs/ai-integration/` references)
+- [ ] `docs/` folder deprecated with redirect message
+
+### Technical
+- [ ] Docs-site builds without errors: `cd docs-site && npm run build`
+- [ ] No broken links
+- [ ] Search functionality works
+- [ ] Mobile/desktop rendering correct
+- [ ] All images/assets load
+
+### Alignment
+- [ ] Docs reflect First Principles (spec 049)
+- [ ] AI-native identity clear throughout
+- [ ] README.md consistent with docs-site
+- [ ] AGENTS.md reflects new structure
+
+**Validation Commands**:
+```bash
+# Build docs-site
+cd docs-site && npm run build
+
+# Validate specs
+cd .. && npx lean-spec validate
+
+# Check for broken links (if link checker installed)
+# npm run check-links
+```
+
+## Notes
+
+**See [NOTES.md](./NOTES.md) for implementation notes, decisions, and lessons learned.**
+
+**Key Points**:
+- Scope expanded from minor polish to comprehensive restructure
+- User feedback + First Principles (spec 049) drove changes
+- AI Integration → Working with AI (AI is core, not optional)
+- Single source of truth (docs-site), deprecate `docs/` folder
+- Estimated effort: 8-12 hours over 1-2 days
+
+**Related Specs**:
+- **Spec 049**: LeanSpec First Principles (foundation for this work)
+- **Spec 056**: Initial docs audit (fixed major issues)
+- **Spec 057**: Comprehensive validation (found these issues)
+- **Spec 043**: v0.2.0 launch (parent context, this blocks launch)
+
+---
+
+**Status**: 🚧 In Progress (scope expanded from minor polish to comprehensive restructure)  
+**Next Steps**: Execute Phase 1 (Navigation & Structure)