docs: rewrite doc/README.md as comprehensive master index v2.0.0

- Catalog 40+ documentation files across 4 sections - Add architecture quick reference (13 internal packages, 6-layer CSS, template structure) - Add complete E2E test suite matrix (83 Playwright tests grouped by range) - Add JavaScript modules inventory (7 files) - Add security features matrix (CSRF, rate limiting, bot detection, CSP) - Add Makefile commands reference (16 targets) - Add deployment scripts and CI/CD reference - Add metrics dashboard - Follow same pattern as commando and morenocuadrillero docs/README.md
2026-02-21 17:20:39 +00:00
parent 69012bb1ae
commit 15723dfbe6
1 changed files with 303 additions and 125 deletions
@@ -1,164 +1,342 @@
-# CV Project Documentation
+# CV Site — Documentation Master Index v2.0.0

-**Complete documentation for the Go + HTMX CV website project.**
+> Modern, minimal curriculum vitae website for Juan Andrés Moreno Rubio.
+> Go + HTMX + Hyperscript | Bilingual (ES/EN) | Server-Side PDF | Paper Design Aesthetic
+
+🔗 **Live:** [juan.andres.morenorub.io](https://juan.andres.morenorub.io/)

 ---

-## 📚 Quick Navigation
+## Quick Start

-### For Developers
-
-**Getting Started**
- [1. Architecture Overview](1-ARCHITECTURE.md) - System design and Go backend architecture
- [2. Modern Web Techniques](2-MODERN-WEB-TECHNIQUES.md) - Frontend architecture (HTMX, Hyperscript, CSS) ⭐
- [3. API Reference](3-API.md) - Complete API documentation with endpoints and responses
-
-**Technical Implementation**
- [4. Hyperscript Rules](4-HYPERSCRIPT-RULES.md) - Hyperscript conventions and best practices
- [5. Zoom Implementation](5-ZOOM-IMPLEMENTATION.md) - Custom zoom feature technical details
- [12. CSS Architecture](12-CSS-ARCHITECTURE.md) - Modular CSS structure and ITCSS organization ⭐
- [13. Toast Notifications](13-TOAST-NOTIFICATIONS.md) - Toast notification system for PDF downloads and user feedback
- [14. Backend Handlers](14-BACKEND-HANDLERS.md) - Handler architecture, type safety, middleware, and testing ⭐
- [16. CMD+K API](16-CMD-K-API.md) - Command palette API for ninja-keys integration ⭐
-
-**Contact Form & Security**
- [17. Contact Form](17-CONTACT-FORM.md) - Quick start guide for contact form with SMTP setup
- [18. Security Audit](18-SECURITY-AUDIT.md) - Comprehensive security audit report (OWASP Top 10)
- [19. Security Implementation](19-SECURITY-IMPLEMENTATION.md) - Detailed security controls documentation
-
-**Testing & Quality**
- [27. Testing](27-GO-TESTING.md) - Comprehensive testing documentation with coverage analysis
-
-**Deployment & Operations**
- [8. Deployment Guide](8-DEPLOYMENT.md) - Production deployment instructions
- [9. Security Policies](9-SECURITY.md) - Security guidelines and vulnerability reporting
+```bash
+cp .env.example .env          # Configure environment
+make dev                       # Dev server with hot reload (GO_ENV=development)
+make test                      # Go unit tests (fast, no Chrome)
+make test-all                  # All tests including PDF/Chrome integration
+make lint                      # golangci-lint
+make check                     # lint + unit tests
+make build                     # Build binary → cv-server
+```

 ---

-### For Users & Customizers
+## Documentation Map

- [6. User Guide](6-USER-GUIDE.md) - End-user documentation for CV features
- [7. Customization Guide](7-CUSTOMIZATION.md) - How to customize your CV content and styling
- [10. Privacy Policy](10-PRIVACY.md) - Data handling and privacy information
+### 1. Core Project Docs
+
+| File | Description | Location |
+|------|-------------|----------|
+| `README.md` | Project overview, features, demo, security highlights | Root |
+| `CLAUDE.md` | AI development guidance, quick commands, tech stack | Root |
+| `PROJECT-MEMORY.md` | Critical patterns, rules, lessons learned — **read first** | Root |
+| `Makefile` | Build targets (dev, test, lint, build, sprites, css) | Root |
+| `.env.example` | Environment configuration template | Root |
+| `CODE_OF_CONDUCT.md` | Code of conduct | Root |
+| `CONTRIBUTING.md` | Contributing guidelines | Root |
+| `LICENSE` | MIT License | Root |
+
+### 2. Core Technical Documentation (`doc/`)
+
+28 numbered docs covering every aspect of the system.
+
+| # | File | Description |
+|---|------|-------------|
+| 00 | [GO-DOCUMENTATION-INDEX](00-GO-DOCUMENTATION-INDEX.md) | Go system documentation index |
+| 01 | [ARCHITECTURE](01-ARCHITECTURE.md) | System design, Go backend architecture |
+| 02 | [MODERN-WEB-TECHNIQUES](02-MODERN-WEB-TECHNIQUES.md) | Frontend architecture (HTMX, Hyperscript, CSS) ⭐ |
+| 03 | [API](03-API.md) | Complete API reference with endpoints and responses |
+| 04 | [HYPERSCRIPT-RULES](04-HYPERSCRIPT-RULES.md) | Hyperscript conventions and best practices |
+| 05 | [ZOOM-IMPLEMENTATION](05-ZOOM-IMPLEMENTATION.md) | Custom zoom feature (25%-300%) |
+| 06 | [USER-GUIDE](06-USER-GUIDE.md) | End-user guide |
+| 07 | [CUSTOMIZATION](07-CUSTOMIZATION.md) | Customization guide |
+| 08 | [DEPLOYMENT](08-DEPLOYMENT.md) | Complete deployment guide |
+| 09 | [SECURITY](09-SECURITY.md) | Security features, CSP, XSS, headers |
+| 10 | [PRIVACY](10-PRIVACY.md) | Privacy & analytics policy |
+| 11 | [PDF-EXPORT](11-PDF-EXPORT.md) | Server-side PDF generation (chromedp) |
+| 12 | [CSS-ARCHITECTURE](12-CSS-ARCHITECTURE.md) | Modular CSS, ITCSS organization ⭐ |
+| 13 | [TOAST-NOTIFICATIONS](13-TOAST-NOTIFICATIONS.md) | Toast notification system |
+| 14 | [BACKEND-HANDLERS](14-BACKEND-HANDLERS.md) | Handler architecture, type safety, middleware ⭐ |
+| 15 | [SEO](15-SEO.md) | SEO optimization |
+| 16 | [CMD-K-API](16-CMD-K-API.md) | Command palette API (ninja-keys) ⭐ |
+| 17 | [CONTACT-FORM](17-CONTACT-FORM.md) | Contact form with SMTP |
+| 18 | [SECURITY-AUDIT](18-SECURITY-AUDIT.md) | OWASP Top 10 audit report |
+| 19 | [SECURITY-IMPLEMENTATION](19-SECURITY-IMPLEMENTATION.md) | Detailed security controls |
+| 20 | [HTMX-LEARNING](20-HTMX-LEARNING.md) | HTMX patterns and learning notes |
+| 21 | [ACCESSIBILITY](21-ACCESSIBILITY.md) | Accessibility (a11y) implementation |
+| 22 | [SPRITES](22-SPRITES.md) | SVG sprite system |
+| 23 | [DATA-CACHE](23-DATA-CACHE.md) | Data caching system |
+| 24 | [GO-VALIDATION-SYSTEM](24-GO-VALIDATION-SYSTEM.md) | Input validation framework |
+| 25 | [GO-TEMPLATE-SYSTEM](25-GO-TEMPLATE-SYSTEM.md) | Go template rendering system |
+| 26 | [GO-ROUTES-API](26-GO-ROUTES-API.md) | Route definitions and API structure |
+| 27 | [GO-TESTING](27-GO-TESTING.md) | Testing strategy and coverage analysis |
+
+**Additional docs:**
+
+| File | Description |
+|------|-------------|
+| [DECISIONS.md](DECISIONS.md) | Architectural Decision Records (ADRs) |
+| [HTMX-ANALYSIS-COMPLETE.md](HTMX-ANALYSIS-COMPLETE.md) | HTMX implementation analysis |
+| [cleanup-report-2025-12-02.md](cleanup-report-2025-12-02.md) | Codebase cleanup report |
+| `_go-learning/` | Go learning resources directory |
+
+### 3. Deployment & CI/CD
+
+| File | Description | Location |
+|------|-------------|----------|
+| `scripts/deploy.sh` | Deployment script | `scripts/` |
+| `scripts/healthcheck.sh` | Health check script | `scripts/` |
+| `scripts/rollback.sh` | Rollback script | `scripts/` |
+| `config/systemd/` | Systemd service configuration | `config/` |
+| `.github/workflows/deploy.yml` | GitHub Actions deploy workflow | `.github/` |
+| `.github/workflows/test.yml` | GitHub Actions test workflow | `.github/` |
+| `.github/workflows/README.md` | Workflows documentation | `.github/` |
+| `.github/ISSUE_TEMPLATE/` | Issue templates | `.github/` |
+
+### 4. Testing
+
+**Test Framework Documentation:**
+
+| File | Description | Location |
+|------|-------------|----------|
+| `tests/README.md` | Testing overview | `tests/` |
+| `tests/TEST-SUMMARY.md` | Test suite summary | `tests/` |
+| `tests/mjs/README.md` | Playwright test docs | `tests/mjs/` |
+| `tests/security/README.md` | Security tests docs | `tests/security/` |
+
+**Security Tests:**
+
+| File | Description |
+|------|-------------|
+| `tests/security/contact_security_test.go` | Contact form security tests |
+| `tests/security/security_tests.sh` | Security test shell scripts |
+
+**Integration Tests:**
+
+| File | Description |
+|------|-------------|
+| `tests/integration/email_test.go` | Email integration tests |
+
+**E2E Test Suite (`tests/mjs/`) — 83 Playwright Tests:**
+
+| Range | Tests | Coverage |
+|-------|-------|----------|
+| 0-9 | `0-zoom` `1-toggles` `2-keyboard-shortcuts` `3-hyperscript` `4-htmx` `5-language` `6-modals` `7-mobile-responsive` `8-hover-sync` `9-hyperscript-def-limit` | Core functionality |
+| 10-19 | `10-zoom-persistence` `11-zoom-ui-exclusion` `12-skeleton-language` `13-color-theme` `14-button-positioning` `14-pdf-modal` `15-icon-toggle` `16-awards-visual` `17-all-icons` `18-theme-and-mobile` `19-dark-theme` `19-pdf-download-url` | Visual & theme |
+| 20-29 | `20-dark-theme-debug` `20-pdf-download-debug` `21-view-switcher` `22-theme-consistency` `23-dark-theme-borders` `24-course-inline-icons` `24-pdf-download-params` `25-inline-icons` `26-course-list-icons` `27-course-icons-final` `28-references-pdf` `29-background-patterns` `29-pdf-toast` | Icons, PDF, dark theme |
+| 30-39 | `30-tooltip-macos-dock` `31-tooltip-visual` `32-all-tooltips-final` `32-hyperscript-multi-src` `33-keyboard-shortcuts-refactored` `33-mobile-tooltip-position` `34-hyperscript-refactor` `34-mobile-button-opacity` `35-ipad-sidebar` `35-mobile-colored-buttons` `36-button-hover-footer` `37-footer-hover` `38-mobile-fixes` `39-mobile-updates` | Tooltips, mobile, hyperscript |
+| 40-49 | `40-back-to-top-footer` `41-mobile-accordion` `43-info-modal-mobile-font` `43-mobile-accordion-modal` `44-mobile-modal-quick` `45-mobile-modal-comprehensive` `46-visual-accordion` `47-compact-accordion` `48-mobile-landscape-blur` `49-mobile-light-theme` | Mobile, modals, accordion |
+| 50-59 | `50-landscape-layout` `51-mobile-button-opacity` `52-mobile-device-detection` `53-final-mobile-fixes` `54-landscape-mode` `55-button-centering` `56-landscape-debug` `57-horizontal-scroll` `58-modal-centering` `59-landscape-photo-backdrop` | Landscape, responsive |
+| 60-69 | `60-accessibility` `60-sidebar-content-debug` `61-sidebar-positioning` `62-sidebar-computed-height` `63-media-query-match` `64-desktop-view` `65-page-2-sidebar` `66-comprehensive-all-viewports` `67-button-colors-visibility` `68-menu-colors-dark-theme` `69-scroll-header-behavior` | Accessibility, sidebar, viewports |
+| 70-82 | `70-json-content-validation` `71-cmd-k-api-scroll` `72-cmd-k-button` `73-contact-form` `74-button-icon-fluid-sizing` `75-debug-button-icons` `75-html-invoker-commands` `76-cmd-k-lazy-loading` `76-visual-verification` `77-intro-text-justification` `78-fab-search-removal` `79-sprites` `80-mobile-fab-overflow` `81-css-bundling` `82-head-support` | CMD+K, contact, sprites, CSS |

 ---

-## 📖 Documentation Overview
+## Architecture Quick Reference

-### Core Technical Documentation
+### Tech Stack

-| # | Document | Purpose | Audience |
-|---|----------|---------|----------|
-| 1 | [ARCHITECTURE.md](1-ARCHITECTURE.md) | Go backend architecture, package structure, design patterns | Backend developers |
-| 2 | [MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) | HTMX/Hyperscript frontend architecture, component patterns, ADRs | Frontend developers |
-| 3 | [API.md](3-API.md) | Complete API reference with all endpoints | API consumers, integrators |
-| 4 | [HYPERSCRIPT-RULES.md](4-HYPERSCRIPT-RULES.md) | Hyperscript coding conventions | Frontend developers |
-| 5 | [ZOOM-IMPLEMENTATION.md](5-ZOOM-IMPLEMENTATION.md) | Zoom feature implementation details | Feature developers |
-| 12 | [CSS-ARCHITECTURE.md](12-CSS-ARCHITECTURE.md) | Modular CSS structure, ITCSS layers, HTMX integration | Frontend developers, designers |
-| 13 | [TOAST-NOTIFICATIONS.md](13-TOAST-NOTIFICATIONS.md) | Toast notification system, PDF download feedback, user notifications | Frontend developers, UX designers |
-| 14 | [BACKEND-HANDLERS.md](14-BACKEND-HANDLERS.md) | Handler architecture, type safety, middleware pattern, testing strategy | Backend developers |
-| 15 | [SEO.md](15-SEO.md) | SEO optimization and best practices | Frontend developers |
-| 16 | [CMD-K-API.md](16-CMD-K-API.md) | CMD+K command palette API, ninja-keys integration | Frontend developers |
-| 17 | [CONTACT-FORM.md](17-CONTACT-FORM.md) | Contact form quick start guide | Backend developers |
-| 18 | [SECURITY-AUDIT.md](18-SECURITY-AUDIT.md) | Comprehensive security audit (OWASP Top 10) | Security teams |
-| 19 | [SECURITY-IMPLEMENTATION.md](19-SECURITY-IMPLEMENTATION.md) | Security controls implementation details | Backend developers, Security |
-| 27 | [GO-TESTING.md](27-GO-TESTING.md) | Comprehensive testing documentation and coverage | Backend developers, QA |
+| Component | Technology |
+|-----------|------------|
+| Backend | Go 1.21+ (stdlib HTTP server) |
+| Frontend | HTMX 1.9+ + Hyperscript + Vanilla JS |
+| Templates | Go `html/template` (server-side rendering) |
+| PDF Export | chromedp (headless Chrome) |
+| Styling | Custom CSS (6-layer ITCSS architecture) |
+| Icons | SVG sprites system |
+| Command Palette | ninja-keys (CMD+K) |
+| Testing | Playwright (E2E, 83 tests) + Go `testing` (unit) |
+| Deploy | Nginx + Systemd + Let's Encrypt + GitHub Actions |
+| i18n | Bilingual ES/EN with JSON data files |

-### User & Operations Documentation
+### Internal Packages (`internal/`)

-| # | Document | Purpose | Audience |
-|---|----------|---------|----------|
-| 6 | [USER_GUIDE.md](6-USER-GUIDE.md) | End-user feature documentation | CV users |
-| 7 | [CUSTOMIZATION.md](7-CUSTOMIZATION.md) | Content and style customization | CV customizers |
-| 8 | [DEPLOYMENT.md](8-DEPLOYMENT.md) | Deployment instructions and operations | DevOps, site operators |
-| 9 | [SECURITY.md](9-SECURITY.md) | Security policies and reporting | Security teams |
-| 10 | [PRIVACY.md](10-PRIVACY.md) | Privacy policy and data handling | Legal, compliance |
-| 11 | [PDF-EXPORT.md](11-PDF-EXPORT.md) | PDF generation architecture and configuration | Backend developers |
+| Package | Responsibility |
+|---------|---------------|
+| `cache/` | Page data caching |
+| `config/` | Configuration management |
+| `constants/` | Application constants |
+| `email/` | SMTP email service |
+| `fileutil/` | File utility functions |
+| `handlers/` | HTTP request handlers (CV, PDF, contact, API) |
+| `httputil/` | HTTP utility functions |
+| `middleware/` | Security headers, CSRF, rate limiting, logging |
+| `models/` | Data models (CV, UI) |
+| `pdf/` | PDF generation with chromedp |
+| `routes/` | Route configuration |
+| `templates/` | Template manager (hot reload in dev) |
+| `validation/` | Input validation framework |
+
+### Template Structure
+
+```
+templates/
+├── index.html              # Main layout wrapper (paper design)
+├── cv-content.html         # CV content rendering
+├── cv-text.txt             # Plain text CV export
+├── language-switch.html    # HTMX language switch partial
+└── partials/
+    ├── layout/             # head.html, head-scripts.html, head-language-switch.html
+    ├── cv/                 # CV section partials
+    ├── sections/           # Content sections
+    ├── navigation/         # Navigation components
+    ├── contact/            # Contact form partials
+    ├── modals/             # Modal dialogs (PDF, info, contact)
+    ├── widgets/            # Reusable widgets (zoom, theme, tooltips)
+    └── color-theme-switcher.html
+```
+
+### CSS Architecture (6 layers)
+
+| Layer | Directory | Purpose |
+|-------|-----------|---------|
+| 01 | `static/css/01-foundation/` | Reset, variables, base typography |
+| 02 | `static/css/02-layout/` | Grid, flexbox, page/paper layouts |
+| 03 | `static/css/03-components/` | Cards, buttons, sections, sidebar |
+| 04 | `static/css/04-interactive/` | Hover, transitions, animations |
+| 05 | `static/css/05-responsive/` | Breakpoints, mobile, landscape, tablet |
+| 06 | `static/css/06-effects/` | Backgrounds, patterns, blur, glassmorphism |
+| — | `static/css/main.css` | Main entry point (imports all layers) |
+| — | `static/css/print.css` | Print-specific styles |
+
+### JavaScript Modules
+
+| File | Responsibility |
+|------|---------------|
+| `static/js/main.js` | App initialization, HTMX setup |
+| `static/js/cv-functions.js` | CV-specific functions |
+| `static/js/color-theme.js` | Light/Dark/Auto theme switching |
+| `static/js/device-detection.js` | Mobile/desktop/tablet detection |
+| `static/js/footer-buttons-interaction.js` | Footer button interactions |
+| `static/js/ninja-keys-init.js` | CMD+K command palette setup |
+| `static/js/scroll-at-bottom-handler.js` | Scroll position detection |
+
+### Data Structure
+
+```
+data/
+├── cv-es.json              # CV content (Spanish)
+├── cv-en.json              # CV content (English)
+├── ui-es.json              # UI strings (Spanish)
+└── ui-en.json              # UI strings (English)
+```
+
+### Static Assets
+
+| Directory | Contents |
+|-----------|----------|
+| `static/css/` | 6-layer CSS architecture + print.css |
+| `static/js/` | 7 JavaScript modules |
+| `static/images/` | Profile photo, project images |
+| `static/dist/` | Built/bundled assets |
+| `static/hyperscript/` | Hyperscript library |
+| `static/pdf/` | Generated PDF files |
+| `static/psd/` | Design source files |
+| `static/llms.txt` | LLM-friendly site description |
+| `static/robots.txt` | Search engine directives |
+| `static/sitemap.xml` | XML sitemap |
+| `static/sprite-showcase.html` | SVG sprite preview page |
+
+### Security Features
+
+| Feature | Implementation |
+|---------|---------------|
+| CSRF Protection | Cryptographic tokens |
+| Rate Limiting | 5 forms/hour, 3 PDFs/minute |
+| Bot Detection | Honeypot fields + timing validation |
+| Input Validation | Comprehensive sanitization |
+| Security Headers | CSP, HSTS, X-Frame-Options (A+ rated) |
+| Browser-Only Access | Blocks automation tools on contact form |
+| Security Logging | Structured JSON logs |
+
+### Key Features
+
+| Feature | Implementation |
+|---------|---------------|
+| Bilingual | ES/EN with instant HTMX switching (no reload) |
+| PDF Export | Server-side via chromedp (headless Chrome) |
+| Paper Design | White paper on gray background aesthetic |
+| Zoom Control | 25%-300% with session persistence |
+| CMD+K Palette | ninja-keys integration for quick navigation |
+| Toast Notifications | PDF download feedback |
+| Responsive | Mobile, tablet, desktop, landscape |
+| Theme System | Light/Dark/Auto with localStorage |
+| SVG Sprites | Optimized icon system |
+| Hot Reload | Template hot reload in development mode |

 ---

-## 🏗️ Architecture Quick Reference
+## Makefile Commands

-**Backend**: Go (Hono-inspired routing)
- Clean package structure (`internal/` pattern)
- Template caching and rendering
- JSON-based CV data model
- Middleware: logging, security headers, CORS
-
-**Frontend**: HTMX + Hyperscript + Vanilla CSS
- Hypermedia-driven architecture (minimal JavaScript)
- Server-side rendering with HTMX partial updates
- Declarative behaviors with Hyperscript
- Component-level skeleton loaders
- Light/dark/auto color themes
-
-**Key Features**:
- ✅ Custom zoom control (25%-175%)
- ✅ Bilingual support (English/Spanish)
- ✅ Keyboard shortcuts (L/I/V/?)
- ✅ Print-optimized CSS
- ✅ Mobile responsive
- ✅ Accessibility (WCAG AA compliance)
+| Command | Description |
+|---------|-------------|
+| `make dev` | Dev server with hot reload |
+| `make run` | Production mode |
+| `make build` | Build binary → `cv-server` |
+| `make test` | Go unit tests (fast, no Chrome) |
+| `make test-unit` | Unit tests only |
+| `make test-local` | All unit tests from project root |
+| `make test-all` | All tests including PDF/Chrome integration |
+| `make test-integration` | Integration tests only (PDF) |
+| `make lint` | golangci-lint |
+| `make lint-fix` | Lint with auto-fix |
+| `make check` | Lint + unit tests |
+| `make clean` | Clean build artifacts |
+| `make sprites` | Generate SVG sprites |
+| `make sprites-clean` | Clean sprite artifacts |
+| `make css-dev` / `css-prod` / `css-watch` / `css-clean` | CSS build pipeline |

 ---

-## 🎯 Common Tasks
+## Scripts Reference

-### "I want to..."
-
-**...understand the system architecture**
-→ Start with [1-ARCHITECTURE.md](1-ARCHITECTURE.md) (backend) and [2-MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) (frontend)
-
-**...add a new feature**
-→ Read [2-MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) for frontend patterns, [3-API.md](3-API.md) for backend APIs
-
-**...customize my CV content**
-→ Follow [7-CUSTOMIZATION.md](7-CUSTOMIZATION.md) for content and styling changes
-
-**...deploy to production**
-→ Use [8-DEPLOYMENT.md](8-DEPLOYMENT.md) for step-by-step deployment instructions
-
-**...understand HTMX patterns**
-→ Check [2-MODERN-WEB-TECHNIQUES.md](2-MODERN-WEB-TECHNIQUES.md) Section 6 (HTMX Patterns)
-
-**...write Hyperscript code**
-→ Follow conventions in [4-HYPERSCRIPT-RULES.md](4-HYPERSCRIPT-RULES.md)
-
-**...report a security issue**
-→ See [9-SECURITY.md](9-SECURITY.md) for responsible disclosure process
-
-**...understand or improve test coverage**
-→ Read [27-GO-TESTING.md](27-GO-TESTING.md) for coverage analysis and testing patterns
+| Script | Purpose |
+|--------|---------|
+| `scripts/deploy.sh` | Production deployment |
+| `scripts/healthcheck.sh` | Health check verification |
+| `scripts/rollback.sh` | Deployment rollback |
+| `cmd/sprites/` | SVG sprite generation tool |

 ---

-## 📦 Archive
+## Cross-References

-Historical documentation (bug fixes, testing reports, implementation notes) is stored in [`archive/`](archive/) for reference. These documents are not actively maintained but preserved for historical context.
+| Resource | Notes |
+|----------|-------|
+| `doc/00-GO-DOCUMENTATION-INDEX.md` | Original numbered index with reading paths |
+| `PROJECT-MEMORY.md` | **Read first** — critical patterns and rules |
+| `CLAUDE.md` | AI development guidance and quick commands |
+| `doc/DECISIONS.md` | Architectural Decision Records |

 ---

-## 🔗 External Resources
+## Documentation Standards

- **HTMX Documentation**: https://htmx.org/
- **Hyperscript**: https://hyperscript.org/
- **Go Documentation**: https://go.dev/doc/
- **Playwright Testing**: https://playwright.dev/
+- **Core docs** (`doc/`) use numbered files (00-27) with cross-references
+- **Tests** follow numbered convention (0-82) plus feature-specific tests
+- **Status indicators:** ✅ Complete | 🚧 In Progress | ⏳ Planned
+- **Bilingual content** requires both `-es.json` and `-en.json` files
+- **Security docs** include both audit (18) and implementation (19)

 ---

-## 📝 Documentation Standards
+## Metrics

-All documentation in this project follows these standards:
-
- **Markdown format** with GitHub-flavored syntax
- **Clear structure** with table of contents for long documents
- **Code examples** with syntax highlighting
- **Up-to-date** reflecting current implementation
- **Versioned** via Git with meaningful commit messages
+| Metric | Value |
+|--------|-------|
+| Documentation files | 40+ |
+| Core technical docs (`doc/`) | 28 numbered + 3 additional |
+| Internal packages | 13 |
+| E2E test files (Playwright) | 83 |
+| JavaScript modules | 7 |
+| CSS layers | 6 |
+| Languages | 2 (ES, EN) |
+| Themes | 3 (Light, Dark, Auto) |
+| Security docs | 4 (audit, implementation, privacy, security) |
+| Deployment scripts | 3 |
+| GitHub Actions workflows | 2 (deploy, test) |
+| Zoom range | 25%-300% |

 ---

-**Last Updated**: 2025-12-06
-**Documentation Status**: Organized, comprehensive
-**Total Active Docs**: 20 core documents + archive
+**Version:** 2.0.0 | **Last Updated:** February 2026 | **Port:** default (dev)