foundational configuration, documentation, and workflow standards for the EmberDocs project

.cursorrules

@@ -0,0 +1,130 @@
+# AI Assistant Guidelines — EmberDocs
+
+**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`
+
+---
+
+## Universal Standards (Apply to All Projects)
+
+See `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)
+- Security (input validation, secrets, dependencies)
+- Git workflow (Conventional Commits, feature branches)
+- Documentation (README, QUICK-REFERENCE, progress logs, API docs)
+- Performance targets (Lighthouse ≥85, bundle <300KB gzipped)
+- PR requirements (tests, docs, scope)
+
+---
+
+## Project-Specific Rules (EmberDocs)
+
+### Tech Stack
+- **Framework:** Next.js 16 with App Router
+- **Language:** TypeScript (strict mode required)
+- **Styling:** Tailwind CSS + CSS Variables (dark-first theme)
+- **Testing:** Jest + Testing Library
+- **Search:** FlexSearch (pre-built index, <100ms queries)
+- **Versioning:** Git-tag based with graceful fallback
+
+### Code Organization
+- `src/app/` — Next.js routes, layouts, pages (App Router)
+- `src/lib/` — Utilities, business logic, content parsing
+- `src/components/` — Reusable React components
+- `docs/` — Developer documentation, planning, progress
+- `user-docs/` — User guides (setup, deployment, troubleshooting)
+- `brand/` — Design assets, style guide, logos
+
+### Critical Modules (D1.1 Critical Path)
+1. **Content Pipeline** (`src/lib/content.ts`) — Markdown/MDX parsing, frontmatter, TOC
+2. **Navigation Generator** (`src/lib/navigation.ts`) — Sidebar nav from file tree
+3. **Search Indexing** (`src/lib/search.ts`) — FlexSearch index building
+4. **Doc Page Component** (`src/app/docs/[...slug]/page.tsx`) — Renders parsed content
+
+### Build & Test Commands
+```bash
+npm install        # Install dependencies
+npm run dev        # Next.js dev server (http://localhost:3000)
+npm run lint       # ESLint + Prettier check
+npm run typecheck  # TypeScript strict mode check
+npm test           # Jest unit tests
+npm run check      # Full CI suite (lint → typecheck → test → license-check)
+npm run license-check  # Verify all dependency licenses
+npm run build      # Production build
+npm run format     # Auto-format with Prettier
+```
+
+### File Naming
+- **Components:** `PascalCase.tsx` (e.g., `SearchPalette.tsx`)
+- **Utilities:** `kebab-case.ts` (e.g., `parse-markdown.ts`)
+- **Tests:** `*.test.ts` or `*.spec.ts`
+- **Markdown docs:** `Title Case.md` (e.g., `QUICK-REFERENCE.md`)
+
+### Documentation Requirements
+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`
+4. **User docs:** Update `user-docs/` if UI/behavior changed
+5. **Developer docs:** Update `docs/` if architecture/structure changed
+
+### Git Workflow
+- **Branch:** `feature/name`, `fix/name`, `chore/name`
+- **Commit:** Imperative, lowercase (e.g., `feat(search): add FlexSearch indexing`)
+- **PR:** Link issues, include testing checklist, scope to one feature
+
+### Key Decisions (Locked in ADL)
+- **Plugins:** 4 lifecycle hooks (onBuild, onParseMD, onSearchIndex, onRender)
+- **Search:** <100ms per query on 1000 docs (Week 1 spike to validate)
+- **Versioning:** Git tags with fallback to single version
+- **Testing:** Hybrid TDD (D1.1) + iterate approach (D1.2–D1.4)
+- **Accessibility:** WCAG 2.1 Level AA (US ADA + EU EN 301 549)
+
+### Security & Configuration
+- ✅ Commit: `.env.example` (template only)
+- ❌ Never commit: `.env.local`, `.env.production`, secrets
+- Use env vars for all secrets; never hardcode
+- Validate all user input; sanitize HTML outputs
+
+### License Compliance
+- ✅ Core framework is licensed under a proprietary source-available license (see `LICENSE`)
+- ✅ Plugin SDK (`sdk/`) is GPLv3 (see `sdk/LICENSE`)
+- ✅ All dependencies are license-compliant with the project's allowlist
+- ✅ NOTICES.md file documents all third-party licenses
+- ✅ Automated license checking via `npm run license-check`
+- ✅ License check integrated into `npm run check` command
+- **When adding dependencies:**
+  - Check license compatibility before installing
+  - Update NOTICES.md with new dependencies
+  - Run `npm run license-check` to verify no conflicts
+  - Avoid GPL, AGPL, or other strong copyleft licenses in core framework dependencies
+
+### Design Assets
+- Store originals in `brand/`, `logos/`, `mockups/`
+- Add new variants as separate files, never overwrite originals
+- Keep style guide in `brand/EMBERDOCS-STYLE-GUIDE.md`
+
+---
+
+## Sync Instructions
+
+**These three files must always be in sync:**
+1. **.cursorrules** (this file) — Concise rules for AI assistants
+2. **claude.md** — Detailed guidelines for humans
+3. **AGENTS.md** — Contributing process and standards
+
+**When updating standards:**
+- [ ] Update all three files with consistent changes
+- [ ] Keep universal rules (DEVELOPMENT-STANDARDS.md section) identical across all three
+- [ ] Project-specific overrides can be formatted differently per file
+- [ ] Include "Sync Instructions" section in each file
+
+**Changes that require sync:**
+- New coding style rule → add to all three files
+- New tool added (linter, test framework, etc.) → update all three
+- New documentation requirement → add to all three
+- Architecture decision locked → add to ADL + all three files
+- Phase plan updated → reflect in guidelines

.env.example

@@ -0,0 +1,66 @@
+# ============================================
+# EmberDocs Configuration
+# ============================================
+# Copy this file to .env.local and fill in your values
+# Never commit .env.local to version control
+
+# ============================================
+# 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
+
+# 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
+
+# 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
+
+# ============================================
+# 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
+
+# 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)
+# Supported formats: PNG, SVG, JPG
+# Example: /logos/my-logo.png
+# EMBERDOCS_LOGO_PATH=/logos/your-logo.png
+
+# Footer text content (e.g., copyright notice)
+# Example: "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"}

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,116 @@
+## Summary
+
+**What changed and why?**
+
+Describe the changes in 1–3 sentences. Include the "why" (what problem does this solve?).
+
+- [ ] Summary is clear and includes rationale
+
+**Linked issues:**
+- Fixes #
+- Relates to #
+
+---
+
+## Testing
+
+All tests must pass locally before submitting. Use the checklist below:
+
+- [ ] `npm run lint` — passed (ESLint + Prettier)
+- [ ] `npm run typecheck` — passed (TypeScript strict mode)
+- [ ] `npm run test` — passed (Jest unit tests)
+- [ ] `npm run build` — passed (production build succeeds)
+
+**Manual testing:**
+- [ ] Feature tested locally (`npm run dev`)
+- [ ] Responsive design checked (mobile 375px, tablet 768px, desktop 1280px)
+- [ ] Browser console has no errors/warnings
+
+**If you skipped any tests, justify here:**
+(e.g., "Skipped X because Y; will fix in follow-up PR #42")
+
+---
+
+## Documentation
+
+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`
+  - Include: work summary, related PRs, any blockers, next steps
+
+**Example:**
+```markdown
+# Progress: 2025-12-23
+
+## Summary
+- ✅ Implemented error handling module (D2.1)
+- ✅ Created ARCHITECTURE-DECISIONS.md ADL
+
+## Work Done
+...
+
+## Related PRs
+- #123: ADL for design decisions
+```
+
+### 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)
+- [ ] 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)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` section
+
+### Developer Documentation (If architecture/code structure changed)
+- [ ] `docs/ARCHITECTURE-DECISIONS.md` updated (new ADL entry if major decision)
+- [ ] `docs/emberdocs-technical-spec.md` updated (architecture changes)
+- [ ] TypeScript JSDoc comments added to exported functions (or updated)
+- [ ] `docs/QUICK-REFERENCE.md` updated (if new npm script or pattern)
+- [ ] `AGENTS.md` or `claude.md` updated (if process/style changes)
+
+### Changelog (All PRs)
+- [ ] `CHANGELOG.md` updated under `[Unreleased]` with feature/fix/change
+  - Format: `- Added ..., Fixed ..., Changed ...` (see CHANGELOG.md for examples)
+
+---
+
+## Screenshots / Demo (if UI changes)
+
+If this PR includes UI changes, provide evidence:
+
+- [ ] Screenshots of before/after (for CSS/layout changes)
+- [ ] Loom video walkthrough (for complex interactions, ~1 min video)
+- [ ] GIF of responsive design (mobile, tablet, desktop)
+
+Alternatively, link to a Vercel preview: `https://emberdocs-pr-XX.vercel.app/`
+
+---
+
+## Checklist Before Submitting
+
+- [ ] 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/`
+- [ ] Relevant docs updated (user or developer)
+- [ ] Changelog updated under `[Unreleased]`
+- [ ] No unrelated changes (scope-focused)
+
+---
+
+## Questions or Blockers?
+
+If you need help:
+1. Check `docs/QUICK-REFERENCE.md` for common tasks
+2. Review existing PRs for similar changes
+3. Ask in the GitHub discussion or open an issue
+4. Refer to `AGENTS.md` or `claude.md` for contributor guidelines
+
+

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm run test
+
+      - name: Build
+        run: npm run build

.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+node_modules
+.next
+out
+dist
+coverage
+.env.local
+.env.production
+.env.development
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+public/search-index.json

.license-checker.json

@@ -0,0 +1,6 @@
+{
+  "onlyAllow": "MIT;Apache-2.0;BSD-2-Clause;BSD-3-Clause;0BSD;ISC;LGPL-3.0-or-later;AGPL-3.0;MPL-2.0;CC-BY-3.0;CC-BY-4.0;CC0-1.0;Python-2.0",
+  "excludePrivatePackages": true,
+  "exclude": "emberdocs"
+}
+

.prettierrc

@@ -0,0 +1,7 @@
+{
+  "singleQuote": true,
+  "semi": true,
+  "tabWidth": 2,
+  "printWidth": 100,
+  "trailingComma": "none"
+}