documentation updates and organization

Author: kristinaquinones

.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

.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)

AGENTS.md

@@ -2,13 +2,13 @@
 
 **IMPORTANT:** This file, `claude.md`, and `.cursorrules` 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:** `dev-docs/guides/DEVELOPMENT-STANDARDS.md`
 
 ---
 
 ## Universal Standards (Apply to All Projects)
 
-See `DEVELOPMENT-STANDARDS.md` for comprehensive details on:
+See `dev-docs/guides/DEVELOPMENT-STANDARDS.md` for comprehensive details on:
 - **Code Style:** TypeScript strict, Prettier, ESLint, naming conventions
 - **Testing:** Unit/integration/E2E pyramid, Jest, coverage targets ≥70%
 - **Git & Version Control:** Conventional Commits, branch strategy, semantic versioning
@@ -45,9 +45,9 @@ npm run dev
 - [ ] Repo cloned and dependencies installed
 - [ ] Dev server running at http://localhost:3000
 - [ ] All tests pass: `npm run check`
-- [ ] Read `docs/QUICK-REFERENCE.md` (5 min)
-- [ ] Reviewed Phase 01 deliverables in `docs/planning/mvp_phase01of02.md`
-- [ ] Checked locked decisions in `docs/ARCHITECTURE-DECISIONS.md`
+- [ ] Read `dev-docs/Quick-Reference.md` (5 min)
+- [ ] Reviewed Phase 01 deliverables in `dev-docs/planning/mvp_phase01of02.md`
+- [ ] Checked locked decisions in `dev-docs/guides/ARCHITECTURE-DECISIONS.md`
 - [ ] Configured Git user: `git config user.name "Your Name"`
 
 ---
@@ -206,7 +206,7 @@ Describe what changed and why in 1–3 sentences.
 - [x] Manual testing in browser
 
 ## Documentation
-- [x] Progress log created: `docs/progress/YYYY_MM_DD.md`
+- [x] Progress log created: `dev-docs/progress/YYYY_MM_DD.md`
 - [x] CHANGELOG.md updated under `[Unreleased]`
 - [x] User docs updated (if UI changed)
 - [x] Developer docs updated (if architecture changed)
@@ -270,7 +270,7 @@ git branch -d feature/search-indexing
 
 ### Progress Log (Required)
 
-**File:** `docs/progress/YYYY_MM_DD.md` (e.g., `docs/progress/2025_12_24.md`)
+**File:** `dev-docs/progress/YYYY_MM_DD.md` (e.g., `dev-docs/progress/2025_12_24.md`)
 
 **Template:**
 ```markdown
@@ -313,7 +313,7 @@ git branch -d feature/search-indexing
 
 ### Architecture Decision (If applicable)
 
-**File:** `docs/ARCHITECTURE-DECISIONS.md`
+**File:** `dev-docs/guides/ARCHITECTURE-DECISIONS.md`
 
 If you made a major architectural decision, create an ADL entry:
 
@@ -440,6 +440,100 @@ Use GitHub Discussions for:
 
 ---
 
+## Documentation Maintenance
+
+**IMPORTANT:** Documentation must be kept up to date and well-organized. This is a requirement for all contributions.
+
+### Documentation Organization
+
+**Naming Conventions:**
+- **Developer docs** (`dev-docs/`): ALL CAPS with hyphens for technical docs, Title Case for user guides
+  - Technical examples: `ARCHITECTURE-DECISIONS.md` (in `dev-docs/guides/`), `EMBERDOCS-TECHNICAL-SPEC.md` (in `dev-docs/specs/`)
+  - User guide examples: `Setup.md`, `Deployment.md`, `Quick-Reference.md` (in `dev-docs/`)
+- **Example docs** (`docs/examples/`): kebab-case
+  - Examples: `getting-started.md`, `api-reference.md`
+
+**Directory Structure:**
+- `dev-docs/specs/` - Technical specifications (EMBERDOCS-TECHNICAL-SPEC.md, EMBERDOCS-API-SPEC.md, etc.)
+- `dev-docs/guides/` - Development guides (ARCHITECTURE-DECISIONS.md, DEVELOPMENT-STANDARDS.md, etc.)
+- `dev-docs/planning/` - Phase plans and planning documents
+- `dev-docs/progress/` - Daily progress logs (format: `YYYY_MM_DD.md` or `YYYY_MM_DD_description.md`)
+- `dev-docs/` (root) - User guides and project overview docs (Setup.md, Deployment.md, Quick-Reference.md, PROJECT-OVERVIEW.md, etc.)
+- `docs/examples/` - Example documentation files (user-facing sample docs)
+
+**Reference Documentation:**
+- `DOCUMENTATION.md` at repository root provides complete documentation index
+- Always update `DOCUMENTATION.md` when adding, moving, or renaming documentation files
+
+### When to Update Documentation
+
+**Always update documentation when:**
+- Adding new features or changing existing functionality
+- Making architectural decisions (create ADL entry in `dev-docs/guides/ARCHITECTURE-DECISIONS.md`)
+- Changing setup or deployment processes
+- Updating dependencies or tools
+- Completing deliverables (update progress logs in `dev-docs/progress/`)
+- Fixing bugs that affect user workflows
+
+**Specific documentation to update:**
+- **Technical Specs** (`dev-docs/specs/`): When architecture, API, or system design changes
+- **Architecture Decisions** (`dev-docs/guides/ARCHITECTURE-DECISIONS.md`): When making major technical decisions
+- **Progress Logs** (`dev-docs/progress/`): Daily (end of work day) - required for all work sessions
+- **User Docs** (`dev-docs/`): When features change or new setup steps added
+- **README.md**: When project overview, quick start, or key features change
+- **DOCUMENTATION.md**: When documentation structure changes (new files, moved files, renamed files)
+
+### Documentation Quality Checklist
+
+**Before committing documentation changes:**
+- [ ] All file paths and references are accurate (use relative paths, not absolute)
+- [ ] Cross-references between documents are updated
+- [ ] Naming conventions are followed (ALL CAPS for dev docs, Title Case for user docs)
+- [ ] `DOCUMENTATION.md` is updated if structure changed
+- [ ] Progress log created if this is a work session (`dev-docs/progress/YYYY_MM_DD.md`)
+- [ ] No broken links (verify with `grep` or link checker)
+- [ ] Code examples are tested and accurate
+- [ ] Screenshots/mockups are up to date (if applicable)
+
+### Cross-Reference Maintenance
+
+**Always maintain accurate cross-references:**
+- Use relative paths: `dev-docs/specs/EMBERDOCS-TECHNICAL-SPEC.md` (not absolute paths)
+- When moving files, update ALL references across the codebase
+- Use `grep` to find all references before moving/renaming files:
+  ```bash
+  grep -r "old-filename" . --include="*.md"
+  ```
+- Update references in: README.md, DOCUMENTATION.md, planning docs, progress logs, and internal cross-references
+
+### Documentation Review Process
+
+**During code review, reviewers verify:**
+- [ ] Documentation changes match code changes
+- [ ] New features are documented
+- [ ] Breaking changes are clearly marked
+- [ ] Examples and code snippets are accurate
+- [ ] Links and references work
+- [ ] Progress log is created/updated
+
+**Before merging PR:**
+- [ ] All documentation references are valid
+- [ ] `DOCUMENTATION.md` reflects current structure
+- [ ] No orphaned documentation files
+- [ ] Documentation follows naming conventions
+
+### Documentation as Part of PR Requirements
+
+**Every PR must include:**
+1. **Progress Log** - Create `dev-docs/progress/YYYY_MM_DD.md` with work summary
+2. **Changelog** - Update `CHANGELOG.md` under `[Unreleased]` section
+3. **Documentation Updates** - Update relevant docs (dev-docs/ if UI or architecture changed)
+4. **DOCUMENTATION.md** - Update if documentation structure changed
+
+**See also:** Documentation Requirements section above for detailed templates.
+
+---
+
 ## Sync Instructions
 
 **These three files must always stay in sync:**
@@ -460,28 +554,29 @@ Use GitHub Discussions for:
 - Architecture decision locked (also create ADL entry)
 - Phase plan updated
 - Git workflow changed
+- Documentation structure/organization changed (also update DOCUMENTATION.md)
 
 ---
 
 ## Quick Links
 
-- **Phase Plans:** `docs/planning/mvp_phase01of02.md`, `docs/planning/mvp_phase02of02.md`
-- **Architecture Decisions:** `docs/ARCHITECTURE-DECISIONS.md`
-- **Developer Cheat Sheet:** `docs/QUICK-REFERENCE.md`
-- **Development Standards:** `DEVELOPMENT-STANDARDS.md`
-- **Setup Guide:** `docs/DEV-SETUP-VERIFICATION.md`
-- **Feature Dependencies:** `docs/FEATURE-DEPENDENCIES.md`
+- **Phase Plans:** `dev-docs/planning/mvp_phase01of02.md`, `dev-docs/planning/mvp_phase02of02.md`
+- **Architecture Decisions:** `dev-docs/guides/ARCHITECTURE-DECISIONS.md`
+- **Developer Cheat Sheet:** `dev-docs/Quick-Reference.md`
+- **Development Standards:** `dev-docs/guides/DEVELOPMENT-STANDARDS.md`
+- **Setup Guide:** `dev-docs/guides/DEV-SETUP-VERIFICATION.md`
+- **Feature Dependencies:** `dev-docs/guides/FEATURE-DEPENDENCIES.md`
 - **Changelog:** `CHANGELOG.md`
 - **PR Template:** `.github/PULL_REQUEST_TEMPLATE.md`
 
 ---
 
 ## Getting Help
 
-- **Code Questions:** Check `docs/QUICK-REFERENCE.md`
-- **Architecture Questions:** See `docs/ARCHITECTURE-DECISIONS.md`
-- **Standards Questions:** Read `DEVELOPMENT-STANDARDS.md` or `claude.md`
-- **Setup Issues:** Follow `docs/DEV-SETUP-VERIFICATION.md`
+- **Code Questions:** Check `dev-docs/Quick-Reference.md`
+- **Architecture Questions:** See `dev-docs/guides/ARCHITECTURE-DECISIONS.md`
+- **Standards Questions:** Read `dev-docs/guides/DEVELOPMENT-STANDARDS.md` or `claude.md`
+- **Setup Issues:** Follow `dev-docs/guides/DEV-SETUP-VERIFICATION.md`
 - **GitHub Issues:** Open an issue for bugs or feature requests
 - **GitHub Discussions:** Ask questions or discuss design
 - **Project Board:** View progress and blockers