docs: add Design Philosophy section with Karesansui Architecture (#98)

Add DESIGN_PHILOSOPHY.md documenting the extension's design principles
using the Japanese dry garden metaphor (karesansui):
- The Stone: Core functionality (profile CRUD, git config)
- Sand Patterns: Quality aspects (90% coverage, logging, timeouts)
- Accents: Differentiation (26 languages, icons, SSH/GPG)
- Stones We Don't Place: Intentional constraints (no GitHub API)
Also adds simplified Design Philosophy sections to EN/JA READMEs
linking to the full document.

🖥️ IDE: [Cursor](https://cursor.sh)
🔌 Extension: [Claude Code](https://claude.ai/download)


Model-Raw: claude-opus-4-5-20251101

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: nullvariant

extensions/git-id-switcher/README.md

@@ -538,6 +538,18 @@ If you previously saved empty settings, they may have synced to the cloud and ar
 
 ---
 
+## Design Philosophy
+
+> "Who am I?" — That's the only question this extension answers.
+
+Built on **Karesansui Architecture**: a simple core (100 lines),
+surrounded by deliberate quality (90% coverage, logging, timeouts)
+and intentional constraints (no GitHub API, no token management).
+
+[Read the full philosophy](docs/DESIGN_PHILOSOPHY.md)
+
+---
+
 ## Contributing
 
 Contributions welcome! See [CONTRIBUTING.md](https://github.com/nullvariant/nullvariant-vscode-extensions/blob/main/CONTRIBUTING.md).

extensions/git-id-switcher/docs/DESIGN_PHILOSOPHY.md

@@ -0,0 +1,113 @@
+# Karesansui Architecture
+
+*A design philosophy for Git ID Switcher*
+
+---
+
+## Placing Stones
+
+The gardener asks:
+
+"Why is this stone here?"
+
+A stone that cannot answer should not be placed.
+
+This garden called Git ID Switcher faces the same question.
+
+---
+
+## The Core
+
+"Who am I?" — that's what we switch.
+
+Nothing more.
+
+```bash
+git config user.name
+git config user.email
+```
+
+It could be written in 100 lines.
+
+That's precisely why we can spend everything else on *how* to place it.
+
+---
+
+## The Stone
+
+Immovable. The center of the garden.
+
+Create a profile. Select it. Write to git config.
+
+This is the stone. Everything else exists to make this stone shine.
+
+---
+
+## Sand Patterns
+
+Ripples raked around the stone.
+
+Not the stone itself, but what makes the stone a stone.
+
+90% test coverage. Structured logging. Timeout handling. Input validation.
+
+Sand patterns go unnoticed. But a garden without them is just barren land.
+
+---
+
+## Accents
+
+Small presences that give the garden its story.
+
+26 language support. Icons. SSH/GPG key association.
+
+The garden could exist without them. But with accents, the garden becomes *someone's* garden.
+
+---
+
+## Stones We Don't Place
+
+The most important decision is what *not* to place.
+
+GitHub API integration. Token management. Authentication wizards.
+
+They might be convenient. But the moment you place them, it becomes a different garden.
+
+The essence of karesansui lies in *empty space*.
+
+---
+
+## On Over-Engineering
+
+"That's excessive," they say.
+
+They're right.
+
+But no one questions ROI in a hobby garden.
+
+Lining up coverage badges is like hanging a scroll. They're there because they're beautiful.
+
+---
+
+## Origin
+
+2003\. CSS Zen Garden.
+
+The same HTML held infinite styles.
+
+Freedom exists within constraints.
+
+What I learned in that garden became the seed of this one.
+
+---
+
+## Coda
+
+Git ID Switcher is art wearing the mask of open source.
+
+To users, it functions as a tool.
+To the maker, it exists as a garden.
+
+Both are true. Both are real.
+
+And so the gardener is satisfied.

extensions/git-id-switcher/docs/i18n/en/README.md

@@ -534,6 +534,18 @@ If you previously saved empty settings, they may have synced to the cloud and ar
 
 ---
 
+## Design Philosophy
+
+> "Who am I?" — That's the only question this extension answers.
+
+Built on **Karesansui Architecture**: a simple core (100 lines),
+surrounded by deliberate quality (90% coverage, logging, timeouts)
+and intentional constraints (no GitHub API, no token management).
+
+[Read the full philosophy](../../DESIGN_PHILOSOPHY.md)
+
+---
+
 ## Contributing
 
 Contributions welcome! See [CONTRIBUTING.md](../../CONTRIBUTING.md).

extensions/git-id-switcher/docs/i18n/ja/README.md

@@ -534,6 +534,18 @@ VS Codeなどのエディタは設定スキーマをメモリにキャッシュ
 
 ---
 
+## 設計哲学
+
+> **「私は誰」を切り替える** — この拡張機能が答える唯一の問い
+
+**枯山水アーキテクチャ**で設計しています。コアは100行で書ける単純さ。
+だからこそ、残りを品質（テスト90%、ログ、タイムアウト）と
+意図的な制約（GitHub API連携なし、トークン管理なし）に費やせます。
+
+[設計哲学の全文を読む](../../DESIGN_PHILOSOPHY.md)
+
+---
+
 ## 貢献
 
 貢献を歓迎します！[CONTRIBUTING.md](../../CONTRIBUTING.md)をご覧ください。

extensions/git-id-switcher/scripts/generate-root-readme.js

@@ -78,6 +78,18 @@ function transformLicenseLink(content) {
   );
 }
 
+/**
+ * Transform DESIGN_PHILOSOPHY.md link to correct relative path
+ * ../../DESIGN_PHILOSOPHY.md -> docs/DESIGN_PHILOSOPHY.md
+ * (from root README perspective)
+ */
+function transformDesignPhilosophyLink(content) {
+  return content.replace(
+    /\(\.\.\/\.\.\/DESIGN_PHILOSOPHY\.md\)/g,
+    `(docs/DESIGN_PHILOSOPHY.md)`
+  );
+}
+
 function main() {
   // Read source file
   if (!fs.existsSync(SOURCE_PATH)) {
@@ -93,6 +105,7 @@ function main() {
   content = removeEnSuffixFromImages(content);
   content = transformContributingLink(content);
   content = transformLicenseLink(content);
+  content = transformDesignPhilosophyLink(content);
 
   // Add auto-generated header
   content = AUTO_GENERATED_HEADER + content;