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

docs/principles/FIRST_PRINCIPLES.md

@@ -0,0 +1,144 @@
+# DSS First Principles
+
+> **The 7 foundational truths that govern all design system decisions**
+
+---
+
+## Principle 1: Single Source of Truth
+
+**Design tokens are the canonical representation of design decisions.**
+
+- All outputs derive from tokens, never the reverse
+- Tokens are immutable facts; themes are interpretations
+- The database is the authoritative source for all token data
+- External systems query DSS; DSS does not duplicate external state
+
+```
+Source (Figma/CSS/JSON) → DSS Tokens (truth) → Outputs (CSS/SCSS/TS)
+```
+
+---
+
+## Principle 2: Atomic Composition
+
+**Build complexity through composition, not complexity.**
+
+The 5-level hierarchy:
+
+1. **Tokens** - Design variables (colors, spacing, typography)
+2. **Primitives** - Base UI elements (button, input, icon)
+3. **Components** - Composite UI (form field, card)
+4. **Layouts** - Page structure patterns
+5. **Views** - Complete screens
+
+**Rules:**
+- Each level only references the level below
+- Never skip levels (components don't directly use tokens without primitives)
+- Composition creates complexity; primitives stay simple
+
+---
+
+## Principle 3: Separation of Concerns
+
+**Keep distinct responsibilities in distinct places.**
+
+| Concern | Separation |
+|---------|------------|
+| Definition vs Application | What tokens exist ≠ How they're used |
+| Source vs Output | Where tokens come from ≠ What format they export to |
+| Core vs Custom | Immutable DSS standards ≠ Client-specific extensions |
+| Design vs Development | Token definition ≠ Token implementation |
+
+---
+
+## Principle 4: Translation Over Transformation
+
+**External systems translate TO the design system, not the reverse.**
+
+- Legacy code maps to canonical tokens via translation dictionaries
+- Never modify core to accommodate edge cases
+- Custom props live in client namespace, not DSS core
+- The translation layer is explicit and auditable
+
+```
+Legacy CSS → Translation Dictionary → DSS Canonical Tokens
+Figma → Translation Dictionary → DSS Canonical Tokens
+```
+
+---
+
+## Principle 5: Observable Health
+
+**Every layer must have measurable health indicators.**
+
+- Validation happens at system boundaries
+- Errors surface immediately with actionable context
+- Metrics are collected at each layer
+- Health status is queryable at any time
+
+**Health Indicators by Layer:**
+| Layer | Indicators |
+|-------|------------|
+| Core | Database connectivity, schema validity |
+| Ingestion | Parse success rate, source availability |
+| Validation | Error counts, warning counts |
+| State | Token coverage, consistency scores |
+| Processing | Transformation success, output validity |
+| Presentation | Component coverage, story completeness |
+| Integration | API latency, MCP tool availability |
+
+---
+
+## Principle 6: Progressive Enhancement
+
+**Start minimal, scale through composition.**
+
+1. Start with tokens (foundation)
+2. Add components when tokens are stable
+3. Add layouts when components are proven
+4. Scale through composition, not complexity
+
+**Anti-patterns to avoid:**
+- Building components before defining tokens
+- Creating layouts before components exist
+- Adding features before foundations are solid
+
+---
+
+## Principle 7: Documentation as Code
+
+**Documentation lives alongside implementation.**
+
+- Every token has a reference
+- Every component has a story
+- Storybook is the living documentation
+- Changes to code trigger changes to docs
+- Documentation is versioned with code
+
+```
+Component Code + Story + Docs = Complete Delivery
+```
+
+---
+
+## Application
+
+When making design system decisions, ask:
+
+1. Does this maintain a single source of truth?
+2. Does this follow atomic composition?
+3. Are concerns properly separated?
+4. Are we translating TO DSS, not FROM it?
+5. Can we observe the health of this change?
+6. Are we enhancing progressively?
+7. Is this documented alongside the code?
+
+If any answer is "no", reconsider the approach.
+
+---
+
+## See Also
+
+- [Glossary](../GLOSSARY.md) - Corporate terminology
+- [Architecture Overview](../architecture/OVERVIEW.md) - 7-layer system
+- [Atomic Hierarchy](./ATOMIC_HIERARCHY.md) - Composition rules