docs: Restructure documentation with Bookstack-compatible hierarchy

- Organized docs into numbered shelf/book/chapter/page structure - Created comprehensive README.md with project overview - Added Getting Started book (quick start, installation, configuration) - Added Development book (workflow, testing, type sharing) - Added Architecture book (design principles, PDA-friendly patterns) - Added API Reference book (conventions, authentication) - Moved TYPE-SHARING.md to proper location - Updated all cross-references in main README - Created docs/README.md as master index - Removed old QA automation reports - Removed deprecated SETUP.md (content split into new structure) Documentation structure follows Bookstack best practices: - Numbered books: 1-getting-started, 2-development, 3-architecture, 4-api - Numbered chapters and pages for ordering - Clear hierarchy and navigation - Cross-referenced throughout Complete documentation available at: docs/README.md Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2026-01-28 17:46:33 -06:00
parent 6a038d093b
commit dd5b3117a7
18 changed files with 3846 additions and 0 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,176 @@
+# Mosaic Stack Documentation
+
+Complete documentation for Mosaic Stack, organized in Bookstack-compatible shelf/book/chapter/page structure.
+
+## 📚 Books
+
+### 1. Getting Started
+
+Essential guides to get Mosaic Stack installed and configured.
+
+- **[Quick Start](1-getting-started/1-quick-start/1-overview.md)** — Get up and running in 5 minutes
+- **[Installation](1-getting-started/2-installation/)**
+  - [Prerequisites](1-getting-started/2-installation/1-prerequisites.md)
+  - [Local Setup](1-getting-started/2-installation/2-local-setup.md)
+  - [Docker Setup](1-getting-started/2-installation/3-docker-setup.md)
+- **[Configuration](1-getting-started/3-configuration/)**
+  - [Environment Variables](1-getting-started/3-configuration/1-environment.md)
+  - [Authentik OIDC](1-getting-started/3-configuration/2-authentik.md)
+
+### 2. Development
+
+Developer guides for contributing to Mosaic Stack.
+
+- **[Workflow](2-development/1-workflow/)**
+  - [Branching Strategy](2-development/1-workflow/1-branching.md)
+  - [Testing Requirements](2-development/1-workflow/2-testing.md)
+- **[Database](2-development/2-database/)**
+  - Schema, migrations, and Prisma guides *(to be added)*
+- **[Type Sharing](2-development/3-type-sharing/)**
+  - [Type Sharing Strategy](2-development/3-type-sharing/1-strategy.md)
+
+### 3. Architecture
+
+Technical architecture and design decisions.
+
+- **[Overview](3-architecture/1-overview/)** — System design *(to be added)*
+- **[Authentication](3-architecture/2-authentication/)** — BetterAuth and OIDC *(to be added)*
+- **[Design Principles](3-architecture/3-design-principles/)**
+  - [PDA-Friendly Patterns](3-architecture/3-design-principles/1-pda-friendly.md)
+
+### 4. API Reference
+
+Complete API endpoint documentation.
+
+- **[Conventions](4-api/1-conventions/)**
+  - [Endpoint Conventions](4-api/1-conventions/1-endpoints.md)
+- **[Authentication](4-api/2-authentication/)**
+  - [Authentication Endpoints](4-api/2-authentication/1-endpoints.md)
+
+## 📝 Scratchpads
+
+Development notes and implementation details for specific issues:
+
+- [Issue #1: Project Scaffold](scratchpads/1-project-scaffold.md)
+- [Issue #2: PostgreSQL Schema](scratchpads/2-postgresql-pgvector-schema.md)
+- [Issue #3: Prisma ORM Setup](scratchpads/3-prisma-orm-setup.md)
+- [Issue #4: Authentik OIDC Integration](scratchpads/4-authentik-oidc-final-status.md)
+
+## 🔍 Quick Links
+
+### For New Users
+1. [Quick Start](1-getting-started/1-quick-start/1-overview.md)
+2. [Local Setup](1-getting-started/2-installation/2-local-setup.md)
+3. [Environment Configuration](1-getting-started/3-configuration/1-environment.md)
+
+### For Developers
+1. [Branching Strategy](2-development/1-workflow/1-branching.md)
+2. [Testing Requirements](2-development/1-workflow/2-testing.md)
+3. [Type Sharing](2-development/3-type-sharing/1-strategy.md)
+
+### For Architects
+1. [PDA-Friendly Design](3-architecture/3-design-principles/1-pda-friendly.md)
+2. [Authentication Flow](3-architecture/2-authentication/) *(to be added)*
+3. [System Overview](3-architecture/1-overview/) *(to be added)*
+
+### For API Consumers
+1. [API Conventions](4-api/1-conventions/1-endpoints.md)
+2. [Authentication Endpoints](4-api/2-authentication/1-endpoints.md)
+
+## 📋 Documentation Standards
+
+### File Organization
+
+```
+docs/
+├── {N}-{book-name}/              # Book (numbered)
+│   ├── README.md                 # Book overview
+│   ├── {N}-{chapter-name}/       # Chapter (numbered)
+│   │   ├── {N}-{page-name}.md    # Page (numbered)
+│   │   └── ...
+│   └── ...
+└── scratchpads/                  # Development notes (unnumbered)
+```
+
+### Numbering Convention
+
+- **Books:** `1-getting-started`, `2-development`, `3-architecture`, `4-api`
+- **Chapters:** `1-quick-start`, `2-installation`, `3-configuration`
+- **Pages:** `1-overview.md`, `2-local-setup.md`, `3-docker-setup.md`
+
+Numbers maintain order in file systems and Bookstack.
+
+### Writing Style
+
+- **Concise** — No unnecessary verbosity
+- **Action-oriented** — Use imperative mood ("Run the command", not "You should run")
+- **Example-heavy** — Show, don't just tell
+- **Code blocks** — Always include working examples
+- **Links** — Cross-reference related topics
+- **PDA-friendly** — Follow [design principles](3-architecture/3-design-principles/1-pda-friendly.md)
+
+### Code Examples
+
+Always include:
+- Language identifier for syntax highlighting
+- Complete, runnable examples
+- Expected output when relevant
+- Error cases and troubleshooting
+
+## 🛠️ Contributing to Docs
+
+### Adding New Pages
+
+1. Identify the appropriate book/chapter
+2. Create numbered markdown file
+3. Add to chapter's parent README
+4. Link from related pages
+5. Test all links and code examples
+
+### Updating Existing Pages
+
+1. Keep formatting consistent
+2. Update last-modified date
+3. Test all examples
+4. Check cross-references
+
+### Creating New Books
+
+1. Number sequentially (`5-{new-book}`)
+2. Create `README.md` overview
+3. Add chapter directories
+4. Update this index
+
+## 📊 Documentation Status
+
+| Book | Completion |
+|------|------------|
+| Getting Started | 🟢 Complete |
+| Development | 🟡 Partial |
+| Architecture | 🟡 Partial |
+| API Reference | 🟡 Partial |
+
+**Legend:**
+- 🟢 Complete
+- 🟡 Partial
+- 🔵 Planned
+- ⚪ Not started
+
+## 🔗 External Resources
+
+- **Project Repository:** https://git.mosaicstack.dev/mosaic/stack
+- **Issue Tracker:** https://git.mosaicstack.dev/mosaic/stack/issues
+- **Google Style Guides:** https://github.com/google/styleguide
+- **BetterAuth Docs:** https://www.better-auth.com
+- **Prisma Docs:** https://www.prisma.io/docs
+- **NestJS Docs:** https://docs.nestjs.com
+
+## 📧 Support
+
+- **Issues:** [Create an issue](https://git.mosaicstack.dev/mosaic/stack/issues/new)
+- **Discussions:** [Project discussions](https://git.mosaicstack.dev/mosaic/stack/discussions)
+
+---
+
+**Last Updated:** 2026-01-28
+**Version:** 0.0.1 (Pre-MVP)