Unify MCP across clients; remove legacy plugin server

docs/README.md

@@ -0,0 +1,35 @@
+# 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.