Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .cursorrules
Original file line number Diff line number Diff line change
Expand Up @@ -77,7 +77,6 @@ Every PR must include:
- **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)
Expand All @@ -91,7 +90,6 @@ Every PR must include:

### 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`
Expand Down
8 changes: 3 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,18 +48,17 @@ All notable changes to EmberDocs are documented in this file. The format follows

## [0.1.0-beta] — TBD (Phase 02 Complete)

### MVP Phase 02: Stabilization & Plugins
### MVP Phase 02: Stabilization

**Target Release:** After 6-week MVP development + beta feedback period (4–8 weeks)

### Added
- **Error Handling:** Error boundaries with user-friendly messages for parse failures, missing files, invalid frontmatter
- **Accessibility:** WCAG 2.1 Level AA compliance (keyboard navigation, ARIA labels, color contrast ≥ 4.5:1)
- **Performance Monitoring:** Web Vitals tracking (LCP, FID, CLS) with console logging and hooks for external APM
- **Plugin System:** Lifecycle hooks (`onBuild`, `onParseMD`, `onSearchIndex`, `onRender`) with sample plugins
- **Version Detection:** Git tag-based version routing (`/docs/v1.0/guide`, `/docs/main/guide`)
- **Version Switcher UI:** Header dropdown to select available document versions
- **Documentation:** Expanded user guides (setup, deployment, configuration, troubleshooting), developer guides (plugin API, architecture deep dives)
- **Documentation:** Expanded user guides (setup, deployment, configuration, troubleshooting), developer guides (architecture deep dives)
- **Changelog:** This changelog documenting all releases

### Changed
Expand Down Expand Up @@ -107,7 +106,6 @@ This is the first alpha release containing core authoring, navigation, and searc
### Known Issues (Defer to Phase 02)
- [ ] Accessibility audit needed (defer detailed WCAG audit to Phase 02)
- [ ] Playwright end-to-end tests not yet implemented (will add in Phase 02)
- [ ] Plugin system not yet implemented (planned for Phase 02)
- [ ] Version detection/routing not yet implemented (planned for Phase 02)
- [ ] Changelog and release notes automation needed (will improve in Phase 02)

Expand Down Expand Up @@ -183,7 +181,7 @@ EmberDocs uses **Semantic Versioning**: `MAJOR.MINOR.PATCH`
```bash
# Create a release tag
git tag -a v0.1.0-alpha -m "MVP Phase 01: Core engine"
git tag -a v0.1.0-beta -m "MVP Phase 02: Stabilization & plugins"
git tag -a v0.1.0-beta -m "MVP Phase 02: Stabilization"
git tag -a v1.0.0 -m "General availability release"

# Push tags to remote
Expand Down
1 change: 0 additions & 1 deletion DEVELOPMENT-STANDARDS.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,6 @@ Useful references:
## Licensing and third-party dependencies

- Core license: `LICENSE`
- SDK license: `sdk/LICENSE`
- Third-party notices: `NOTICES.md`

When adding dependencies:
Expand Down
4 changes: 1 addition & 3 deletions LICENSE
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,7 @@ All rights reserved.
This license applies to the EmberDocs core framework source code in this repository,
except for any files or directories that include a different license notice.

In particular:
- The `sdk/` directory (when present) is licensed separately under the GNU General Public License v3.
- Third-party dependencies are licensed under their respective licenses.
Third-party dependencies are licensed under their respective licenses.

By using, copying, or modifying the Software, you agree to the terms below.

Expand Down
8 changes: 3 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,7 @@ emberdocs/
### For Contributors

- **[Development Roadmap](docs/emberdocs-roadmap.md)** - 16-week development timeline
- **[Licensing](docs/EMBERDOCS-LICENSING.md)** - Proprietary core license (source-available) and GPLv3 SDK boundary
- **[Licensing](docs/EMBERDOCS-LICENSING.md)** - Proprietary core license (source-available)

---

Expand All @@ -155,7 +155,6 @@ emberdocs/

### Advanced Features
- 🔄 Multi-language support (planned)
- 🔄 Plugin system (GPLv3)
- 🔄 API documentation generator
- 🔄 Interactive examples
- 🔄 Version comparison
Expand Down Expand Up @@ -183,7 +182,7 @@ Core documentation engine with markdown parsing, basic search, and dark mode.
Multi-version support, advanced search, mobile navigation, and CLI tool.

### **v1.0** (Weeks 13-16)
Plugin SDK, performance optimization, component library, and hosted service.
Performance optimization, component library, and hosted service.

👉 **[View Detailed Roadmap](docs/emberdocs-roadmap.md)**

Expand All @@ -192,7 +191,6 @@ Plugin SDK, performance optimization, component library, and hosted service.
## 🔐 License

- **Core Framework:** Proprietary source-available license (free to use and self-host; redistribution is not permitted)
- **Plugin SDK:** GPLv3 (open source)
- **Hosted Service:** Proprietary (optional premium offering)

See **[EMBERDOCS-LICENSING.md](docs/EMBERDOCS-LICENSING.md)** for details.
Expand Down Expand Up @@ -232,7 +230,7 @@ npm run dev
2. **Developer First** - Built by developers, for developers
3. **Privacy Matters** - No tracking, no data collection
4. **Performance Obsessed** - Every millisecond counts
5. **Open & Transparent** - Source-available core, open SDK
5. **Open & Transparent** - Source-available core

---

Expand Down
1 change: 0 additions & 1 deletion brand/EMBERDOCS-STYLE-GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -647,7 +647,6 @@ Thick: 2.5px (for emphasis)

**License structure:**
- Core: proprietary source-available license
- Plugin SDK: GPLv3
- Hosted/SaaS: Proprietary (optional premium offering)

### Examples
Expand Down
1 change: 0 additions & 1 deletion brand/emberdocs-brand-guidelines.md
Original file line number Diff line number Diff line change
Expand Up @@ -755,7 +755,6 @@ https://emberdocs.com/brand/logos.zip

**Licensing Details:**
- "Core: proprietary source-available license"
- "Plugin SDK: GPLv3"
- "Hosted Service: Proprietary (optional premium offering)"
- "Full licensing details at emberdocs.com/licensing"

Expand Down
3 changes: 0 additions & 3 deletions claude.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,6 @@ EmberDocs is a documentation platform built with Next.js 16, TypeScript, and Tai
- **Auto-Generated Navigation:** Sidebar built from file structure
- **Client-Side Search:** FlexSearch pre-built at build time, <100ms queries
- **Dark-First Theme:** CSS variables with light theme opt-in
- **Plugin System:** 4 lifecycle hooks for extensibility (Phase 02)
- **Multi-Version Support:** Git-tag based versioning with fallback

### Code Organization
Expand Down Expand Up @@ -236,7 +235,6 @@ cp .env.example .env.local

**Current Status:**
- ✅ Core framework is licensed under the EmberDocs Core Proprietary License (source-available). See `LICENSE`.
- ✅ Plugin SDK (`sdk/`) is licensed under GPLv3. See `sdk/LICENSE`.
- ✅ NOTICES.md file documents third-party licenses
- ✅ Automated license checking via `npm run license-check`
- ✅ License check integrated into `npm run check` command
Expand All @@ -256,7 +254,6 @@ cp .env.example .env.local

These decisions are fixed for Phase 01–02. Follow them:

- **ADL-008:** Plugin system uses 4 lifecycle hooks (onBuild, onParseMD, onSearchIndex, onRender)
- **ADL-009:** Search performance target <100ms per query on 1000 docs (Week 1 spike to validate)
- **ADL-010:** Git-tag versioning with fallback to single version
- **ADL-011:** Hybrid testing (TDD for D1.1; implement-then-test for D1.2–D1.4)
Expand Down
81 changes: 5 additions & 76 deletions docs/ARCHITECTURE-DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -151,50 +151,19 @@ Versions are defined by Git tags (e.g., `v1.0`, `v2.0`) or branch names in the d

---

## ADL-006: AGPL-3.0 Core + GPLv3 Plugin SDK for Licensing

**Date:** 2025-12-20
**Updated:** 2025-12-28 (superseded)
**Status:** Superseded by ADL-013
**Context:**
- EmberDocs aims to be free-to-self-host (core framework) with strong copyleft protection
- Plugins (themes, integrations) should be community-extensible; encourage open-source contributions
- Need to ensure network service providers share source code modifications

**Decision:**
- **Core framework:** AGPL-3.0 license, open source with strong copyleft (ensures network service providers share source code)
- **Plugin SDK:** GPLv3 license; plugins must be open-source, but can integrate with proprietary code
- **Licensed integrations:** Separate paid tier for official plugins/themes (future)

**Alternatives Considered:**
- Fully open-source (MIT): Strong community, but harder to monetize; no revenue for maintenance
- Fully proprietary: Limits adoption and community plugins; not developer-friendly
- Dual licensing (AGPL + commercial): Stronger copyleft, but can discourage enterprise adoption

**Consequences:**
- ✅ Free core appeals to developers and small teams
- ✅ GPL plugins encourage community contributions while protecting against forks
- ✅ Clear path to monetization via paid plugins/themes
- ⚠️ GPL licensing may deter some commercial users (need clear legal guidance)
- ⚠️ Requires discipline to categorize code as core vs. plugin

**Related Docs:** `EMBERDOCS-LICENSING.md`, `LICENSING-UPDATE-SUMMARY.md`

---

## ADL-007: Phase-Based MVP Development (6-Week Plan)

**Date:** 2025-12-23
**Status:** Accepted
**Context:**
- Project scope is large (versioning, search, theming, plugins, analytics)
- Project scope is large (versioning, search, theming, analytics)
- Team is small; need to prioritize ruthlessly
- Early feedback from docs authors and users is critical

**Decision:**
Split MVP into 2 phases over 6 weeks:
- **Phase 01 (Weeks 1-3):** Core engine (content loading, TOC/nav generation, syntax highlighting, dark/light themes, instant search)
- **Phase 02 (Weeks 4-6):** Stabilization & plugins (accessibility, perf budgets, plugin hooks, CI integration, expanded docs)
- **Phase 02 (Weeks 4-6):** Stabilization (accessibility, perf budgets, CI integration, expanded docs)

Full feature set (versioning, team accounts, analytics) deferred to Beta/v1.0.

Expand All @@ -214,41 +183,6 @@ Full feature set (versioning, team accounts, analytics) deferred to Beta/v1.0.

---

## ADL-008: Plugin System — Minimal Hooks for MVP (4 Hooks)

**Date:** 2025-12-23
**Status:** Accepted
**Context:**
- EmberDocs needs extensibility for themes, custom transformers, and integrations
- Risk: Too many hooks = scope creep; too few = plugins can't do useful things
- MVP Phase 02 (Week 2) allocates limited time for plugin system design

**Decision:**
Implement 4 lifecycle hooks for MVP: `onBuild`, `onParseMD`, `onSearchIndex`, `onRender`.
- `onBuild`: Runs at start of build; can generate assets or config
- `onParseMD`: Transforms parsed Markdown AST (e.g., inject metadata, custom syntax)
- `onSearchIndex`: Enriches search index (e.g., boost certain docs, add custom fields)
- `onRender`: Post-processes rendered HTML (e.g., theme variants, inject analytics)

**Design for Extensibility:** Use a hook registry pattern so v1.0 can add more hooks without breaking existing plugins. Example: `plugin.hooks.register('onBuild', callback)` instead of `plugin.onBuild = callback`.

**Alternatives Considered:**
- Minimal (2 hooks): Too restrictive; couldn't support common use cases
- Rich (8+ hooks): Scope creep; delays Phase 02; overkill for MVP
- None (no plugins yet): Misses extensibility opportunity; harder to retrofit later

**Consequences:**
- ✅ Covers 80% of plugin use cases (themes, metadata, search, rendering)
- ✅ Scoped and shippable in Phase 02
- ⚠️ Defers CLI commands, real-time webhooks, component system to v1.0
- ⚠️ Requires sample plugins to validate design adequacy

**Deferred to v1.0:** CLI hooks, theme system, component registration, real-time indexing.

**Related Docs:** `docs/planning/mvp_phase02of02.md` (D2.4), `docs/FEATURE-DEPENDENCIES.md`

---

## ADL-009: Search Performance Target — <100ms for 1000 Docs

**Date:** 2025-12-23
Expand Down Expand Up @@ -422,19 +356,16 @@ Implement **WCAG 2.1 Level AA** as MVP target. Phase 02 Week 1 (D2.2) includes 3

---

## ADL-013: Proprietary Core License (Source-Available) + GPLv3 SDK Boundary
## ADL-013: Proprietary Core License (Source-Available)

**Date:** 2025-12-28
**Status:** Accepted
**Context:**
- EmberDocs core is intended to be free to use and self-host while restricting redistribution of the core framework.
- The project needs a clear boundary for an open-source Plugin SDK.
- Documentation and marketing must reflect the license model accurately to avoid confusion.

**Decision:**
- **Core framework:** Proprietary source-available license (everything outside `sdk/`). See `LICENSE`.
- **Plugin SDK:** GPLv3 (`sdk/`). See `sdk/LICENSE`.
- The core framework must not depend on code within `sdk/` to keep licensing boundaries clear.
- **Core framework:** Proprietary source-available license. See `LICENSE`.
- Docs and marketing must not describe the core framework as open source.

**Alternatives Considered:**
Expand All @@ -443,13 +374,11 @@ Implement **WCAG 2.1 Level AA** as MVP target. Phase 02 Week 1 (D2.2) includes 3
- Dual licensing: increases operational and legal overhead.

**Consequences:**
- ✅ Clear boundary between proprietary core and GPLv3 SDK
- ✅ Free-to-self-host core remains available to users
- ✅ Less risk of license messaging drift across docs and marketing
- ⚠️ Requires discipline to keep SDK and core dependencies isolated
- ⚠️ Requires clear contributor guidance on redistribution restrictions

**Related Docs:** `LICENSE`, `docs/EMBERDOCS-LICENSING.md`, `sdk/README.md`, `NOTICES.md`
**Related Docs:** `LICENSE`, `docs/EMBERDOCS-LICENSING.md`, `NOTICES.md`

---

Expand Down
25 changes: 7 additions & 18 deletions docs/EMBERDOCS-LICENSING.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,17 @@
# EmberDocs Licensing Model
# EmberDocs Licensing

**Last Updated:** 2025-12-28
**Status:** Official
**Status:** Official

## Overview

EmberDocs uses a split licensing model:
EmberDocs core is licensed under the EmberDocs Core Proprietary License (source-available). See `LICENSE`.

- **Core framework (this repository, except `sdk/`)**: EmberDocs Core Proprietary License (source-available). See `LICENSE`.
- **Plugin SDK (`sdk/`)**: GNU General Public License v3. See `sdk/LICENSE`.
- **Third-party dependencies**: Licensed under their respective licenses. See `NOTICES.md`.
Third-party dependencies are licensed under their respective licenses. See `NOTICES.md`.

This document is a human-readable summary. The license texts are the source of truth.

## Core framework (proprietary): what you can do
## Core framework license (summary)

You may:

Expand All @@ -22,30 +20,21 @@ You may:
- Modify the core framework for your own use.
- Deploy the core framework to serve documentation content for your products, services, or organization (including serving documentation to the public).

## Core framework (proprietary): restrictions

You may not, without prior written permission from the licensor:

- Distribute, publish, or otherwise make available the core framework (or any modified version of it) to any third party, in source or binary form.
- Sell, sublicense, rent, lease, or otherwise transfer rights to the core framework.
- Provide the core framework as a hosted or managed service to third parties where the primary value is providing access to EmberDocs itself (for example, an "EmberDocs-as-a-service" offering).
- Provide the core framework as a hosted or managed service to third parties where the primary value is providing access to EmberDocs itself (for example, an \"EmberDocs-as-a-service\" offering).

For full details, see `LICENSE`.

## Plugin SDK (`sdk/`) license

All contents under `sdk/` are licensed under GPLv3. See `sdk/LICENSE`.

To keep licensing boundaries clear, the core framework should not depend on code within `sdk/`.

## Contributions

If you submit a contribution to this repository, your contribution is governed by the contribution terms described in the core license. See `LICENSE`.
If you submit a contribution to this repository, your contribution is governed by the contribution terms described in `LICENSE`.

## Where to find license texts

- Core license: `LICENSE`
- SDK license: `sdk/LICENSE`
- Third-party notices: `NOTICES.md`


Loading
Loading