# DSS Documentation (Human)

This directory contains **human-facing** documentation for DSS.

If you’re looking for AI/agent-oriented notes, see `docs/ai.md`.

## What DSS Is

DSS (Design System Server) is a toolkit that can run in two modes:

1. **Local developer tool**: analyze any project on disk, extract tokens, generate Storybook stories, and expose `dss_*` tools to Claude Code via MCP.
2. **Headless server**: run a FastAPI backend that teams (UX/QA/Admin) can access through the web Admin UI, and that AI assistants can interact with via the `/api/claude/chat` endpoint and MCP tool endpoints.

## MCP across clients

DSS exposes the same `dss_*` toolset to multiple AI clients via MCP:

- Recommended: `./scripts/enable-mcp-clients.sh`
- **Claude Code**: `./scripts/setup-mcp.sh` generates `.claude/mcp.json`.
- **Codex CLI**: `codex mcp add dss -- /absolute/path/to/dss/scripts/dss-mcp`
- **Gemini CLI**: `gemini mcp add dss /absolute/path/to/dss/scripts/dss-mcp`

The Claude plugin system (commands/skills under `dss-claude-plugin/`) is Claude-specific, but DSS makes those guides/hooks available to *any* MCP client via:
- `dss_list_guides` (use `include_meta=true` for hook metadata)
- `dss_get_guide`
- `dss_match_skills`

## Documentation Map

- `docs/quickstart.md` — install + run locally, and run the headless server.
- `docs/architecture.md` — how CLI, API, Admin UI, and MCP fit together.
- `docs/configuration.md` — environment variables, ports, and operational knobs.
- `docs/storage.md` — JSON-only storage layout and `DSS_HOME` rules.
- `docs/upgrade-notes.md` — recent upgrades and migration notes.
- `docs/ai.md` — where the AI/agent documentation lives.