# DSS Context Map - Read This First

> **CRITICAL FOR AI AGENTS**: This file maps the entire DSS documentation hierarchy. Read this first when starting a new session to understand where information lives.

## Entry Point
You are in: `/home/overbits/dss/`

---

## 📘 TIER 1: Foundational Contracts (Always Loaded)

These files define the immutable contracts and philosophy of DSS. They change only through semantic versioning.

### System Architecture
- **File**: `docs/01_core/ARCHITECTURE.md`
- **Contains**: System design, component boundaries, technology stack
- **Updated When**: Major architectural decisions are made

### API Contracts
- **File**: `docs/01_core/API_CONTRACTS.md`
- **Contains**: Complete API specification, endpoint contracts, error codes
- **Updated When**: New endpoints added or contracts change

### Design System Philosophy
- **File**: `docs/01_core/PRINCIPLES.md`
- **Contains**: Core principles, design philosophy, development values
- **Updated When**: Core philosophy evolves

---

## 📊 TIER 2: Current State (Always Loaded)

These files reflect the *current* state of the system in production.

### Project Status
- **File**: `docs/02_status/PROJECT_STATUS.md`
- **Contains**: Deployment status, active bugs, roadmap

### Implementation Summary
- **File**: `docs/02_status/IMPLEMENTATION_SUMMARY.md`
- **Contains**: What has been built (phases 1-5C)

### Project Overview
- **File**: `README.md` (in root)
- **Contains**: Quick start, project description

---

## 📖 TIER 3: Reference Guides (Load as Needed)

- **Integration**: `docs/03_reference/INTEGRATION_GUIDE.md`
- **Migration**: `docs/03_reference/MIGRATION_GUIDE.md`
- **MCP Tools**: `docs/03_reference/MCP_TOOLS_SPEC.md`
- **Production**: `docs/03_reference/PRODUCTION_READINESS.md`

---

## 📦 TIER 4: Historical Archive

**Location**: `docs/archive/pre_optimization/`

Do NOT load these for normal work. These are historical snapshots from past phases.

---

## 🎯 Core Principles

1. **Single Source of Truth** - Each concept documented once
2. **Foundational Contracts** - API specs and principles are immutable
3. **Current State Transparency** - Status always reflects production
4. **Progressive Detail** - Quick ref → guides → specs
5. **Phase Agnostic** - Docs independent of dev phases
6. **Knowledge Persistence** - Deep context in `.knowledge/` graph
7. **MCP First** - Design system tools are first-class citizens

---

## 📍 Quick Navigation

| I Need To... | Read This... |
|---|---|
| Understand the system | `docs/01_core/ARCHITECTURE.md` |
| Check API endpoints | `docs/01_core/API_CONTRACTS.md` |
| See what's deployed | `docs/02_status/PROJECT_STATUS.md` |
| Integrate DSS | `docs/03_reference/INTEGRATION_GUIDE.md` |
| Migrate to DSS | `docs/03_reference/MIGRATION_GUIDE.md` |
| Know the philosophy | `docs/01_core/PRINCIPLES.md` |
| Deploy production | `docs/03_reference/PRODUCTION_READINESS.md` |
| Understand MCP tools | `docs/03_reference/MCP_TOOLS_SPEC.md` |
| Learn the project | `README.md` |
| Contribute code | `CONTRIBUTING.md` |

---

Last Updated: 2025-12-08