Unify MCP across clients; remove legacy plugin server

docs/storage.md

@@ -0,0 +1,59 @@
+# Storage (JSON-only)
+
+## `DSS_HOME` resolution
+
+DSS chooses a storage root in this order:
+
+1. `$DSS_HOME` if set
+2. `./.dss` if it exists in the current working directory
+3. `~/.dss`
+
+This supports:
+- **project-local** storage (recommended when running DSS inside a repo)
+- **shared user** storage (default fallback)
+- **server** storage (explicit `DSS_HOME` volume)
+
+## Directory layout
+
+Most persistent JSON state lives under:
+
+`$DSS_HOME/data/`
+
+```
+data/
+  _system/
+    activity/            # JSONL activity logs (by day)
+    cache/               # TTL cache entries (JSON)
+    users/               # auth users (JSON-only)
+    integration_health.json
+  projects/
+    <project_id>/
+      manifest.json
+      components/
+      figma/
+      integrations.json
+      metrics/
+      styles/
+      tokens/
+  teams/
+```
+
+## Concurrency / locking
+
+The JSON store uses simple file locking (`*.lock`) to reduce corruption when multiple processes write concurrently.
+
+## Project-local artifacts
+
+In addition to `$DSS_HOME/data/`, DSS also writes project-local artifacts under a repo’s `.dss/` directory, for example:
+
+- `.dss/analysis_graph.json` — portable analysis output (commit-friendly).
+- `.dss/config.json` — per-project DSS configuration (used by `ConfigService`).
+- `.dss/runtime-config.json` — runtime/server preferences (when using the headless server wrappers).
+
+## What is safe to commit
+
+Typical “commit-worthy” artifacts:
+- `<project>/.dss/analysis_graph.json` (generated analysis output)
+
+Typical “do not commit” data:
+- per-user caches and secrets under `$DSS_HOME/data/_system/cache`