Initial commit: Clean DSS implementation

Migrated from design-system-swarm with fresh git history. Old project history preserved in /home/overbits/apps/design-system-swarm Core components: - MCP Server (Python FastAPI with mcp 1.23.1) - Claude Plugin (agents, commands, skills, strategies, hooks, core) - DSS Backend (dss-mvp1 - token translation, Figma sync) - Admin UI (Node.js/React) - Server (Node.js/Express) - Storybook integration (dss-mvp1/.storybook) Self-contained configuration: - All paths relative or use DSS_BASE_PATH=/home/overbits/dss - PYTHONPATH configured for dss-mvp1 and dss-claude-plugin - .env file with all configuration - Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability Migration completed: $(date) 🤖 Clean migration with full functionality preserved
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
--- a/docs/DOCUMENTATION_HUB.md
+++ b/docs/DOCUMENTATION_HUB.md
@@ -0,0 +1,458 @@
+# 📚 DSS Documentation Hub: The Organism's Permanent Memory
+
+Welcome to the DSS Documentation Hub - the central repository where all knowledge about the design system organism lives. This is where we store what we've learned, how systems work, and where to find answers.
+
+**Think of this as the organism's brain - everything the system knows is recorded here.**
+
+---
+
+## 🧠 Navigation
+
+### Quick Links (Start Here)
+- **[Getting Started](#getting-started)** - New to DSS? Start here
+- **[Organism Framework](#organism-framework)** - Understand the biology
+- **[Extended Learning](#extended-learning)** - Deep dives into each system
+- **[How-To Guides](#how-to-guides)** - Common tasks and workflows
+- **[Troubleshooting](#troubleshooting)** - Problem solving
+
+---
+
+## Getting Started
+
+### For First-Time Users
+1. **[Quick Start](QUICK_START_ORGANISM.md)** - 5-minute overview
+2. **[Organism Overview](DSS_ORGANISM_README.md)** - System introduction
+3. **[Key Concepts](DSS_ORGANISM_GUIDE.md#key-concepts)** - Important ideas
+
+### For Developers
+1. **[Code Integration Guide](CODE_INTEGRATION_GUIDE.md)** - How to use organism vocabulary in code
+2. **[Architecture](ARCHITECTURE.md)** - System design
+3. **[Token Ingestion](TOKEN_INGESTION.md)** - How tokens enter the system
+
+### For Designers
+1. **[Design System Principles](../DSS_PRINCIPLES.md)** - Philosophy and approach
+2. **[Storybook Guide](../STORYBOOK_CONFIG.md)** - Documentation and presentation
+3. **[Quick Start Organism](QUICK_START_ORGANISM.md)** - Fast reference
+
+### For DevOps/Infrastructure
+1. **[Deployment](../DEPLOYMENT.md)** - Running the system
+2. **[Architecture](ARCHITECTURE.md)** - System structure
+3. **[Performance](PERFORMANCE.md)** - Optimization and monitoring
+
+---
+
+## Organism Framework
+
+### Foundation
+- **[DSS Organism Guide](DSS_ORGANISM_GUIDE.md)** - The complete framework
+- **[Organism Diagram](DSS_ORGANISM_DIAGRAM.md)** - Visual architecture
+- **[Framework Summary](ORGANISM_FRAMEWORK_SUMMARY.md)** - Executive overview
+
+### Vocabulary
+- **[Quick Glossary](DSS_BIOLOGY_GLOSSARY.md)** - Quick reference (A-Z)
+- **[Extended Glossary](EXTENDED_GLOSSARY.md)** - Deep dive into every term
+- **[Usage Guide](IMPLEMENTING_ORGANISM_FRAMEWORK.md)** - How to use in communication
+
+### The 11 Organ Systems
+
+Each system below has detailed documentation:
+
+#### 1. ❤️ Heart (Database)
+- **What It Is:** The persistent storage layer
+- **Key Files:** `dss/storage/`
+- **Vital Signs:** Response time, consistency, backup integrity
+- **Health Check:** Run `python -m dss.settings check-deps`
+- **Read More:** [DSS Organism Guide - Heart](DSS_ORGANISM_GUIDE.md#heart-database)
+
+#### 2. 🧠 Brain (Validators & Analysis)
+- **What It Is:** Validation rules and pattern detection
+- **Key Files:** `dss/validators/`, `dss/analyze/`
+- **Vital Signs:** Validation accuracy, pattern detection rate
+- **Health Check:** Run unit tests: `pytest tests/unit/`
+- **Read More:** [Extended Glossary - Brain](EXTENDED_GLOSSARY.md#-brain-validators--analysis-engine)
+
+#### 3. 🔌 Nervous System (API)
+- **What It Is:** REST API and MCP tool integration
+- **Key Files:** `dss/api/`, `tools/dss_mcp/`
+- **Vital Signs:** Response latency, endpoint availability
+- **Health Check:** `curl http://localhost:3456/health`
+- **Read More:** [Architecture - API Layer](ARCHITECTURE.md)
+
+#### 4. 🍽️ Digestive System (Token Ingestion)
+- **What It Is:** Parsing and extracting tokens from various sources
+- **Key Files:** `dss/ingest/`
+- **Vital Signs:** Parse success rate, processing time
+- **Health Check:** Check ingestion tests: `pytest tests/unit/ingest/`
+- **Read More:** [Token Ingestion Guide](TOKEN_INGESTION.md)
+
+#### 5. 🩸 Circulatory System (Design Tokens)
+- **What It Is:** The tokens themselves and their distribution
+- **Key Files:** `dss/models/token.py`
+- **Vital Signs:** Token count, distribution coverage
+- **Health Check:** Query token database
+- **Read More:** [Extended Glossary - Tokens](EXTENDED_GLOSSARY.md#-tokens-nutrients)
+
+#### 6. ⚡ Metabolic System (Transformations)
+- **What It Is:** Converting tokens to different formats
+- **Key Files:** `tools/style-dictionary/`, `dss/tools/`
+- **Vital Signs:** Transformation speed, format completeness
+- **Health Check:** Check transformation tests
+- **Read More:** [Extended Glossary - Metabolism](EXTENDED_GLOSSARY.md#-metabolic-system-transformations)
+
+#### 7. 🎛️ Endocrine System (Themes)
+- **What It Is:** Theme management and adaptation
+- **Key Files:** `dss/themes/`
+- **Vital Signs:** Theme availability, application success
+- **Health Check:** Load different themes in Storybook
+- **Read More:** [DSS Organism Guide - Themes](DSS_ORGANISM_GUIDE.md#endocrine-system)
+
+#### 8. 🛡️ Immune System (Validators & QA)
+- **What It Is:** Data validation and quality assurance
+- **Key Files:** `dss/validators/schema.py`
+- **Vital Signs:** Validation pass rate, error detection
+- **Health Check:** Run all tests: `pytest`
+- **Read More:** [Extended Glossary - Immunity](EXTENDED_GLOSSARY.md#health--immunity)
+
+#### 9. 👁️ Sensory Organs (Figma, Assets)
+- **What It Is:** Input systems for perceiving external designs
+- **Key Files:** `tools/figma/`
+- **Vital Signs:** API response time, cache hit rate
+- **Health Check:** Test Figma connection
+- **Read More:** [Extended Glossary - Sensory](EXTENDED_GLOSSARY.md#sensory--perception)
+
+#### 10. 🎨 Skin (Storybook & UI)
+- **What It Is:** Documentation and presentation layer
+- **Key Files:** `dss/storybook/`, `admin-ui/`
+- **Vital Signs:** Load time, user engagement
+- **Health Check:** Visit http://localhost:6006 (Storybook), http://localhost:5173 (Admin UI)
+- **Read More:** [Storybook Config](../STORYBOOK_CONFIG.md)
+
+#### 11. 🦴 Skeleton (Schemas & Structure)
+- **What It Is:** Naming conventions and data schemas
+- **Key Files:** `dss/models/`
+- **Vital Signs:** Naming consistency, schema compliance
+- **Health Check:** Check schema validation tests
+- **Read More:** [Extended Glossary - Skeleton](EXTENDED_GLOSSARY.md#-skeleton-schemas--structure)
+
+---
+
+## Extended Learning
+
+### Deep Dives by System
+
+Each organ system has extended documentation available:
+
+| System | Quick Ref | Extended | Code | Tests |
+|--------|-----------|----------|------|-------|
+| Heart ❤️ | [Glossary](EXTENDED_GLOSSARY.md#-heart-database-layer) | [Guide](DSS_ORGANISM_GUIDE.md#heart-database) | `dss/storage/` | `tests/` |
+| Brain 🧠 | [Glossary](EXTENDED_GLOSSARY.md#-brain-validators--analysis-engine) | [Analysis](../COMPONENT_AUDIT.md) | `dss/validators/` | `tests/unit/` |
+| Nervous 🔌 | [Glossary](EXTENDED_GLOSSARY.md#-nervous-system-api--webhooks) | [Architecture](ARCHITECTURE.md) | `dss/api/` | Integration tests |
+| Digestive 🍽️ | [Glossary](EXTENDED_GLOSSARY.md#-digestive-system-token-ingestion) | [Ingestion](TOKEN_INGESTION.md) | `dss/ingest/` | `tests/unit/ingest/` |
+| Circulatory 🩸 | [Glossary](EXTENDED_GLOSSARY.md#-tokens-nutrients) | [Models](../dss-mvp1/dss/models/) | `dss/models/` | Token tests |
+| Metabolic ⚡ | [Glossary](EXTENDED_GLOSSARY.md#-metabolic-system-transformations) | [Style Dict](../tools/style-dictionary/) | `tools/` | Transform tests |
+| Endocrine 🎛️ | [Glossary](EXTENDED_GLOSSARY.md#-endocrine-system--hormones) | [Guide](DSS_ORGANISM_GUIDE.md#endocrine-system) | `dss/themes/` | Theme tests |
+| Immune 🛡️ | [Glossary](EXTENDED_GLOSSARY.md#health--immunity) | [Validation](CODE_INTEGRATION_GUIDE.md#validation) | `dss/validators/` | All tests |
+| Sensory 👁️ | [Glossary](EXTENDED_GLOSSARY.md#-sensory-organs-figma-assets-external-systems) | [Figma](../tools/figma/) | `tools/figma/` | Figma tests |
+| Skin 🎨 | [Glossary](EXTENDED_GLOSSARY.md#-skin-storybook-documentation-ui) | [Storybook](../STORYBOOK_CONFIG.md) | `dss/storybook/` | UI tests |
+| Skeleton 🦴 | [Glossary](EXTENDED_GLOSSARY.md#-skeleton-schemas--structure) | [Schemas](../dss-mvp1/dss/models/) | `dss/models/` | Schema tests |
+
+---
+
+## How-To Guides
+
+### Common Tasks
+
+#### Adding a New Token Type
+1. Define the token type in `dss/models/token.py`
+2. Add validation rules in `dss/validators/schema.py`
+3. Create ingestion logic in `dss/ingest/base.py`
+4. Add transformation rules in `tools/style-dictionary/config.js`
+5. Document in Storybook
+
+#### Integrating a New Source
+1. Create ingestor in `dss/ingest/`
+2. Implement `TokenSource` abstract class
+3. Add tests in `tests/unit/ingest/`
+4. Register in API or CLI
+5. Document in `TOKEN_INGESTION.md`
+
+#### Adding a New Validator
+1. Create rule in `dss/validators/schema.py`
+2. Add error message in `admin-ui/js/core/error-handler.js`
+3. Add test cases in `tests/unit/validators/`
+4. Update documentation
+
+#### Debugging Issues
+1. Check logs: `admin-ui/js/core/logger.js` output
+2. Run health check: `python -m dss.settings check-deps`
+3. Check database: Query SQLite database
+4. Review error messages using organism metaphors
+5. Consult Troubleshooting section below
+
+### Workflow Examples
+- [Token Extraction Workflow](TOKEN_INGESTION.md#extraction-workflow)
+- [Component Definition Workflow](../COMPONENT_AUDIT.md)
+- [Theme Generation Workflow](../STORYBOOK_CONFIG.md#theme-generation)
+- [Deployment Workflow](../DEPLOYMENT.md#deployment-process)
+
+---
+
+## Troubleshooting
+
+### By Symptom
+
+**"The organism is sluggish"** (Slow performance)
+- Check database response time
+- Monitor CPU/memory usage
+- Review API latency
+- See: [Performance Guide](PERFORMANCE.md)
+
+**"The organism is confused"** (Validation errors)
+- Review error messages from immune system
+- Check token schema compliance
+- Verify naming conventions
+- See: [Validation Guide](CODE_INTEGRATION_GUIDE.md#validation)
+
+**"The organism can't see"** (Figma connection issues)
+- Verify Figma token configuration
+- Check sensory organs health
+- Review Figma API status
+- See: [Figma Integration](../tools/figma/README.md)
+
+**"The organism is sick"** (Data integrity issues)
+- Run validation checks
+- Review recent database operations
+- Check for corrupted tokens
+- See: [Error Handling](../ERROR_HANDLING.md)
+
+**"The organism is deaf"** (Not receiving updates)
+- Check API endpoints
+- Verify webhook configuration
+- Review event emitters
+- See: [Architecture - Communication](ARCHITECTURE.md)
+
+### Error Messages as Organism Communication
+
+The organism communicates health through error messages:
+- **🛡️ IMMUNE ALERT** - Validation failed (data rejected)
+- **❤️ CRITICAL** - Heart not responding (database down)
+- **⚠️ SYMPTOM** - Something unusual detected (warning)
+- **🧠 BRAIN ALERT** - Processing error (analyzer failed)
+- **⚡ METABOLISM ALERT** - Overload (rate limit)
+
+Decode these messages using the [Extended Glossary](EXTENDED_GLOSSARY.md).
+
+---
+
+## Documentation Structure
+
+```
+docs/
+├── DOCUMENTATION_HUB.md (YOU ARE HERE)
+│   └── Central index and navigation
+├── EXTENDED_GLOSSARY.md
+│   └── Complete vocabulary reference
+├── DSS_ORGANISM_GUIDE.md
+│   └── Framework foundation
+├── Quick References
+│   ├── QUICK_START_ORGANISM.md
+│   ├── DSS_BIOLOGY_GLOSSARY.md
+│   └── QUICK_START_ORGANISM.md
+├── System Guides
+│   ├── CODE_INTEGRATION_GUIDE.md
+│   ├── TOKEN_INGESTION.md
+│   ├── ARCHITECTURE.md
+│   └── PERFORMANCE.md
+├── Concepts
+│   ├── DSS_ORGANISM_DIAGRAM.md
+│   ├── ORGANISM_FRAMEWORK_SUMMARY.md
+│   └── DSS_ORGANISM_README.md
+└── Reference
+    ├── TROUBLESHOOTING.md
+    ├── MIGRATION.md
+    └── CODE_QUALITY.md
+```
+
+---
+
+## What You'll Find Here
+
+### Knowledge Categories
+
+**🧠 Conceptual**
+- What is the organism framework?
+- How do biological metaphors help?
+- What are the 11 organ systems?
+- Why think biologically?
+
+**🔧 Technical**
+- How do I implement organism vocabulary?
+- What code files handle each system?
+- How do I add new validators?
+- How do I integrate new sources?
+
+**📚 Reference**
+- Quick glossary of terms
+- Extended definitions with examples
+- Architecture diagrams
+- Data flow documentation
+
+**🐛 Problem-Solving**
+- How do I debug issues?
+- What does this error mean?
+- Why is the system slow?
+- How do I fix validation errors?
+
+**📈 Development**
+- How do I develop new features?
+- What's the testing strategy?
+- How do I deploy changes?
+- What are best practices?
+
+---
+
+## Finding What You Need
+
+### By Role
+
+**New Team Members**
+→ Start with [Getting Started](#getting-started)
+→ Read [Organism Framework](#organism-framework)
+→ Explore specific system you work on
+
+**Frontend Developers**
+→ Focus on [Sensory Organs](EXTENDED_GLOSSARY.md#-sensory-organs-figma-assets-external-systems) and [Skin](EXTENDED_GLOSSARY.md#-skin-storybook-documentation-ui)
+→ Read [Code Integration Guide](CODE_INTEGRATION_GUIDE.md)
+→ Explore `admin-ui/`, `dss/storybook/`
+
+**Backend Developers**
+→ Study [Digestive System](EXTENDED_GLOSSARY.md#-digestive-system-token-ingestion) and [Heart](EXTENDED_GLOSSARY.md#-heart-database-layer)
+→ Read [Token Ingestion](TOKEN_INGESTION.md)
+→ Explore `dss/ingest/`, `dss/storage/`
+
+**DevOps/Infrastructure**
+→ Focus on [Heart](EXTENDED_GLOSSARY.md#-heart-database-layer) and [Architecture](ARCHITECTURE.md)
+→ Read [Deployment](../DEPLOYMENT.md)
+→ Monitor system health
+
+**Designers**
+→ Read [Quick Start](QUICK_START_ORGANISM.md)
+→ Explore [Sensory Organs](EXTENDED_GLOSSARY.md#-sensory-organs-figma-assets-external-systems)
+→ Visit [Storybook Guide](../STORYBOOK_CONFIG.md)
+
+### By Problem Type
+
+**"I don't understand how X works"**
+→ Check [Extended Glossary](EXTENDED_GLOSSARY.md)
+→ Read the corresponding system guide
+→ Look at code examples in [Code Integration Guide](CODE_INTEGRATION_GUIDE.md)
+
+**"I'm getting an error"**
+→ Read the error message carefully
+→ Look up the term in [Extended Glossary](EXTENDED_GLOSSARY.md)
+→ Check [Troubleshooting](#troubleshooting)
+→ See [Error Handling](../ERROR_HANDLING.md)
+
+**"I need to add a new feature"**
+→ Find similar existing feature
+→ Review [Architecture](ARCHITECTURE.md)
+→ Check [How-To Guides](#how-to-guides)
+→ Look at test examples
+
+**"The system seems broken"**
+→ Run health check: `python -m dss.settings check-deps`
+→ Check [Troubleshooting](#troubleshooting)
+→ Review logs in [Logger](EXTENDED_GLOSSARY.md#-logger-consciousness)
+→ Contact DevOps/Infrastructure
+
+---
+
+## Keeping Documentation Fresh
+
+### Documentation Standards
+- Use organism vocabulary consistently
+- Include code examples
+- Link to related documentation
+- Keep examples up-to-date
+- Update when code changes
+
+### Contributing to Docs
+1. Edit relevant `.md` file
+2. Use organism vocabulary
+3. Include concrete examples
+4. Test all links
+5. Update index/navigation if adding new section
+
+### Documentation Review Checklist
+- [ ] Uses organism vocabulary consistently
+- [ ] Clear and concise explanations
+- [ ] Code examples work
+- [ ] Links are correct
+- [ ] Follows existing structure
+- [ ] Updated related docs
+
+---
+
+## Quick Stats
+
+| Metric | Value |
+|--------|-------|
+| **Documentation Files** | 15+ |
+| **Glossary Entries** | 100+ |
+| **Organ Systems** | 11 |
+| **Code Files** | 50+ |
+| **API Endpoints** | 34 |
+| **MCP Tools** | 32 |
+| **Test Files** | 20+ |
+
+---
+
+## Recent Changes
+
+**Latest Updates:**
+- ✨ Extended Glossary created with 100+ terms
+- ✨ Documentation Hub (this file) created
+- ✨ Organism vocabulary added to all core systems
+- ✨ Error messages updated with immune system metaphors
+- ✨ Logger categories expanded with organ system guidance
+
+**Planned Documentation:**
+- Extended guides for each organ system
+- Video tutorials
+- Interactive diagrams
+- Code walkthrough series
+
+---
+
+## Contact & Support
+
+### Getting Help
+- Check [Extended Glossary](EXTENDED_GLOSSARY.md) first
+- Review [Troubleshooting](#troubleshooting)
+- Ask in team chat with organism vocabulary
+- Create issue if it's a bug
+
+### Feedback
+- Suggest documentation improvements
+- Report broken links
+- Propose new topics
+- Share what worked for you
+
+---
+
+## See Also
+
+- [🧬 DSS Organism Guide](DSS_ORGANISM_GUIDE.md) - Full framework
+- [📚 Quick Reference Glossary](DSS_BIOLOGY_GLOSSARY.md) - Quick lookup
+- [🔧 Code Integration Guide](CODE_INTEGRATION_GUIDE.md) - How to use in code
+- [📊 Architecture](ARCHITECTURE.md) - System design
+- [🐛 Troubleshooting](TROUBLESHOOTING.md) - Problem solving
+
+---
+
+**Last Updated:** 2025-12-06
+**Version:** 1.0.0
+**Status:** Active & Maintained
+
+🧬 *The organism's permanent memory, always growing and learning.*
+