mostly documentation updates

.cursorrules

@@ -2,13 +2,13 @@
 
 **IMPORTANT:** This file, `claude.md`, and `AGENTS.md` must stay in sync. See "Sync Instructions" at bottom.
 
-**For universal development standards applicable to any project, see:** `DEVELOPMENT-STANDARDS.md`
+**For universal development standards applicable to any project, see:** `docs/guides/DEVELOPMENT-STANDARDS.md`
 
 ---
 
 ## Universal Standards (Apply to All Projects)
 
-See `DEVELOPMENT-STANDARDS.md` for complete details on:
+See `docs/guides/DEVELOPMENT-STANDARDS.md` for complete details on:
 - Code style (TypeScript strict, Prettier, ESLint, 2-space indentation)
 - Testing strategy (unit/integration/E2E pyramid, Jest, ≥70% coverage)
 - Accessibility (WCAG 2.1 Level AA minimum)
@@ -67,7 +67,7 @@ npm run format     # Auto-format with Prettier
 Every PR must include:
 1. **Progress log:** Create `docs/progress/YYYY_MM_DD.md` with work summary, blockers, next steps
 2. **Changelog:** Update `CHANGELOG.md` under `[Unreleased]` section
-3. **ADL entry:** If major architectural decision, create entry in `docs/ARCHITECTURE-DECISIONS.md`
+3. **ADL entry:** If major architectural decision, create entry in `docs/guides/ARCHITECTURE-DECISIONS.md`
 4. **User docs:** Update `user-docs/` if UI/behavior changed
 5. **Developer docs:** Update `docs/` if architecture/structure changed
 
@@ -107,6 +107,44 @@ Every PR must include:
 
 ---
 
+## Documentation Maintenance
+
+**Keep all documentation up to date and well-organized.**
+
+### Organization Standards
+- **Dev docs** (`dev-docs/`): ALL CAPS for technical docs, Title Case for user guides
+- **Example docs** (`docs/examples/`): kebab-case (e.g., `getting-started.md`)
+
+**Directory Structure:**
+- `dev-docs/specs/` - Technical specifications
+- `dev-docs/guides/` - Development guides
+- `dev-docs/planning/` - Phase plans
+- `dev-docs/progress/` - Daily logs (YYYY_MM_DD.md)
+- `dev-docs/` (root) - User guides and project docs
+- `docs/examples/` - Example documentation files
+
+### Update When
+- Adding/changing features → update relevant docs
+- Architectural decisions → create ADL entry
+- Setup/deployment changes → update user-docs/
+- Structure changes → update `DOCUMENTATION.md`
+- Daily work → create/update progress log
+
+### Quality Checklist
+- [ ] All file paths/references accurate
+- [ ] Cross-references updated
+- [ ] Naming conventions followed
+- [ ] `DOCUMENTATION.md` updated if structure changed
+- [ ] No broken links
+- [ ] Code examples tested
+
+### Cross-Reference Maintenance
+- Use relative paths: `docs/specs/EMBERDOCS-TECHNICAL-SPEC.md`
+- When moving files, update ALL references (use `grep` to find)
+- Update: README.md, DOCUMENTATION.md, planning docs, progress logs
+
+---
+
 ## Sync Instructions
 
 **These three files must always be in sync:**
@@ -116,7 +154,7 @@ Every PR must include:
 
 **When updating standards:**
 - [ ] Update all three files with consistent changes
-- [ ] Keep universal rules (DEVELOPMENT-STANDARDS.md section) identical across all three
+- [ ] Keep universal rules (docs/guides/DEVELOPMENT-STANDARDS.md section) identical across all three
 - [ ] Project-specific overrides can be formatted differently per file
 - [ ] Include "Sync Instructions" section in each file
 
@@ -126,3 +164,4 @@ Every PR must include:
 - New documentation requirement → add to all three
 - Architecture decision locked → add to ADL + all three files
 - Phase plan updated → reflect in guidelines
+- Documentation structure/organization changed → update all three + DOCUMENTATION.md

.env.example

@@ -1,66 +1,55 @@
-# ============================================
 # EmberDocs Configuration
-# ============================================
-# Copy this file to .env.local and fill in your values
-# Never commit .env.local to version control
+# Copy this file to .env.local and customize as needed
+# All variables are optional - EmberDocs works with sensible defaults
 
-# ============================================
-# Content Configuration (Optional)
-# ============================================
-# Directory where markdown documentation files are stored
-# Default: docs/examples
-# Examples:
-#   EMBERDOCS_CONTENT_DIR=docs/content      # Files in docs/content/ folder
-#   EMBERDOCS_CONTENT_DIR=content           # Files in content/ folder
-#   EMBERDOCS_CONTENT_DIR=pages             # Files in pages/ folder
-EMBERDOCS_CONTENT_DIR=docs/examples
+# Branding (optional)
+# Default product name is "EmberDocs"
+EMBERDOCS_PRODUCT_NAME="EmberDocs"
 
-# URL route prefix for documentation pages
-# Default: /docs
-# Examples:
-#   EMBERDOCS_BASE_ROUTE=/documentation  # URLs: /documentation/getting-started/intro
-#   EMBERDOCS_BASE_ROUTE=/help           # URLs: /help/getting-started/intro
-#   EMBERDOCS_BASE_ROUTE=/guides         # URLs: /guides/getting-started/intro
-EMBERDOCS_BASE_ROUTE=/docs
+# Company or organization name (used in headers, metadata, and page titles)
+# If set, page titles will be formatted as: {PRODUCT_NAME} - {COMPANY_NAME} Documentation
+EMBERDOCS_COMPANY_NAME="Your Company Name"
 
-# Show marketing landing page on root route (/)
-# Default: false (root route redirects to documentation index)
-# Set to 'true' to show the EmberDocs framework marketing landing page
-# Only needed for the EmberDocs framework repository itself
-# EMBERDOCS_SHOW_LANDING=true
+# Default author name (used when document frontmatter doesn't specify an author)
+EMBERDOCS_DEFAULT_AUTHOR="Your Name"
 
-# ============================================
-# Branding & Metadata
-# ============================================
-# Default author name for documents
-# Used when a document's frontmatter doesn't specify an author
-# If not set, author metadata will only appear if specified in document frontmatter
-# EMBERDOCS_DEFAULT_AUTHOR=Your Company Name
+# Primary URL for your company/product (used in links and metadata)
+EMBERDOCS_PRIMARY_URL=https://your-url.com
 
-# Company or organization name
-# Used in headers, metadata, and page titles
-# If not set, product name will be used alone
-# EMBERDOCS_COMPANY_NAME=Your Company, Inc.
-
-# Product name
-# Used in headers, metadata, and page titles
-# Default: EmberDocs
-# EMBERDOCS_PRODUCT_NAME=Your Product Name
-
-# Primary URL for the company/product
-# Used in links, metadata, and footer
-# EMBERDOCS_PRIMARY_URL=https://example.com
-
-# Logo path (relative to /public directory)
+# Logo Configuration (optional)
+# Path to your logo image (relative to /public directory)
 # Supported formats: PNG, SVG, JPG
-# Example: /logos/my-logo.png
+# Example: /logos/your-logo.png
 # EMBERDOCS_LOGO_PATH=/logos/your-logo.png
 
+# Navigation Links (optional)
+# Header navigation links as JSON object
+# Format: {"Label": "URL", "Another Label": "Another URL"}
+# External links must start with http:// or https://
+# Internal links start with /
+# EMBERDOCS_HEADER_LINKS={"Docs": "/docs", "Features": "/#features", "GitHub": "https://github.com/yourorg"}
+
+# Footer Configuration (optional)
 # Footer text content (e.g., copyright notice)
-# Example: "Your Company © 2025"
-# EMBERDOCS_FOOTER_TEXT=Your Company © 2025
+# EMBERDOCS_FOOTER_TEXT="Your Company © 2025"
 
-# Footer links as JSON object
-# Format: {"Label": "URL", "Another Label": "Another URL"}
-# Example: {"Privacy": "/privacy", "Terms": "/terms", "Contact": "/contact"}
-# EMBERDOCS_FOOTER_LINKS={"Privacy": "/privacy", "Terms": "/terms"}
+# Footer links as JSON object (same format as header links)
+# EMBERDOCS_FOOTER_LINKS={"Privacy": "/privacy", "Terms": "/terms", "Contact": "/contact"}
+
+# Content Configuration (optional)
+# Custom documentation content directory (default: docs/examples)
+# EMBERDOCS_CONTENT_DIR=docs/examples
+
+# Custom documentation base route (default: /docs)
+# URLs will be served at this path instead of /docs/*
+# EMBERDOCS_BASE_ROUTE=/docs
+
+# Framework Mode (only for EmberDocs framework repository)
+# Set to true to show the EmberDocs marketing landing page at root (/)
+# Default: false (root redirects to /docs/index)
+# EMBERDOCS_SHOW_LANDING=false
+
+# Theme Selection
+# Choose the theme for both landing page and documentation pages
+# Options: dark (default), light, monochrome
+# EMBERDOCS_THEME=monochrome

.github/PULL_REQUEST_TEMPLATE.md

@@ -36,7 +36,7 @@ All tests must pass locally before submitting. Use the checklist below:
 Documentation is required for most PRs. Check the boxes that apply:
 
 ### Progress Log (Required for all PRs)
-- [ ] Daily progress log created in `docs/progress/YYYY_MM_DD_progress.md`
+- [ ] Daily progress log created in `dev-docs/progress/YYYY_MM_DD_progress.md`
   - Include: work summary, related PRs, any blockers, next steps
 
 **Example:**
@@ -55,17 +55,17 @@ Documentation is required for most PRs. Check the boxes that apply:
 ```
 
 ### Phase Plan Updates (If scope changed)
-- [ ] `docs/planning/mvp_phase01of02.md` updated with deliverable changes (if applicable)
-- [ ] `docs/planning/mvp_phase02of02.md` updated (if applicable)
+- [ ] `dev-docs/planning/mvp_phase01of02.md` updated with deliverable changes (if applicable)
+- [ ] `dev-docs/planning/mvp_phase02of02.md` updated (if applicable)
 - [ ] Exit criteria reviewed for go/no-go status
 
 **Example:** "Updated D1.3 acceptance criteria per feedback in #42"
 
 ### User-Facing Documentation (If UI/behavior changed)
-- [ ] `user-docs/Setup.md` updated (setup/installation changes)
-- [ ] `user-docs/Deployment.md` updated (deployment steps changed)
-- [ ] `user-docs/Configuration.md` updated (new config options)
-- [ ] `user-docs/Troubleshooting.md` updated (new error cases documented)
+- [ ] `dev-docs/Setup.md` updated (setup/installation changes)
+- [ ] `dev-docs/Deployment.md` updated (deployment steps changed)
+- [ ] `dev-docs/Configuration.md` updated (new config options)
+- [ ] `dev-docs/Troubleshooting.md` updated (new error cases documented)
 - [ ] `CHANGELOG.md` updated under `[Unreleased]` section
 
 ### Developer Documentation (If architecture/code structure changed)
@@ -98,7 +98,7 @@ Alternatively, link to a Vercel preview: `https://emberdocs-pr-XX.vercel.app/`
 - [ ] All tests pass locally (`npm run check`)
 - [ ] No console errors/warnings in dev mode
 - [ ] Commit messages are clear and imperative (e.g., "Add error handling module")
-- [ ] Progress log created in `docs/progress/`
+- [ ] Progress log created in `dev-docs/progress/`
 - [ ] Relevant docs updated (user or developer)
 - [ ] Changelog updated under `[Unreleased]`
 - [ ] No unrelated changes (scope-focused)