diff --git a/.gitignore b/.gitignore
index 03dac17..9ddf47e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -69,12 +69,4 @@ Thumbs.db
#md files
plan.md
-#docs
-docs/architecture.visual-check.json
-docs/architecture.html
-docs/architecture.visual-check.1440x900.dark.png
-docs/architecture.visual-check.1440x900.light.png
-docs/architecture.visual-check.2048x1320.dark.png
-docs/architecture.visual-check.html
-
gitmate.architecture.json
\ No newline at end of file
diff --git a/README.md b/README.md
index 81474cd..495fb27 100644
--- a/README.md
+++ b/README.md
@@ -32,3 +32,15 @@ uv run gitmate config set model gemini-flash
`commit`, `pr-summary`, `changelog`, and `doc` are stubbed until their phases
land — see `AGENTS.md` and the phased roadmap for details.
+
+## Diagrams
+
+Editable draw.io sources plus publishable PNG exports (open the `.drawio`
+files in the draw.io desktop app to edit):
+
+| Diagram | Source | Export |
+|---|---|---|
+| System architecture (Phases 0–8, gemini-3.5-flash-lite) | [`docs/architecture.drawio`](docs/architecture.drawio) | [`docs/architecture.png`](docs/architecture.png) |
+| Phase 0 class diagram (`config.py`, `cli.py`) | [`docs/class-diagram.drawio`](docs/class-diagram.drawio) | [`docs/class-diagram.png`](docs/class-diagram.png) |
+| Use cases (implemented + planned) | [`docs/use-case.drawio`](docs/use-case.drawio) | [`docs/use-case.png`](docs/use-case.png) |
+| `config` command sequences | [`docs/sequence.drawio`](docs/sequence.drawio) | [`docs/sequence.png`](docs/sequence.png) |
diff --git a/docs/architecture.drawio b/docs/architecture.drawio
new file mode 100644
index 0000000..6a38828
--- /dev/null
+++ b/docs/architecture.drawio
@@ -0,0 +1,149 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/architecture.png b/docs/architecture.png
new file mode 100644
index 0000000..d81365e
Binary files /dev/null and b/docs/architecture.png differ
diff --git a/docs/class-diagram.drawio b/docs/class-diagram.drawio
new file mode 100644
index 0000000..fa55e8a
--- /dev/null
+++ b/docs/class-diagram.drawio
@@ -0,0 +1,101 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/class-diagram.png b/docs/class-diagram.png
new file mode 100644
index 0000000..419a872
Binary files /dev/null and b/docs/class-diagram.png differ
diff --git a/docs/sequence.drawio b/docs/sequence.drawio
new file mode 100644
index 0000000..65f2fc9
--- /dev/null
+++ b/docs/sequence.drawio
@@ -0,0 +1,79 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/sequence.png b/docs/sequence.png
new file mode 100644
index 0000000..a43813e
Binary files /dev/null and b/docs/sequence.png differ
diff --git a/docs/use-case.drawio b/docs/use-case.drawio
new file mode 100644
index 0000000..f885b78
--- /dev/null
+++ b/docs/use-case.drawio
@@ -0,0 +1,126 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/use-case.png b/docs/use-case.png
new file mode 100644
index 0000000..417d22f
Binary files /dev/null and b/docs/use-case.png differ