Document git capsule in library

libary.md

@@ -2,6 +2,28 @@
 
 This file lists every prompt theme, color codes, design intent, and configuration options.
 
+## Git Capsule (optional, all themes)
+
+What it is: a compact git status block shown on line 2 when you're inside a git repo.
+It uses `__git_ps1` when available, with a safe fallback to `git rev-parse` for the branch.
+
+States + emojis:
+- Clean repo: ✨
+- Dirty working tree: 🔨
+- Staged changes: 📌
+- Untracked files: 🧷
+- Stashed changes: 📦
+
+How it works:
+- The capsule only renders when a repo is detected (no extra noise outside git).
+- If `__git_ps1` is available, it reads git state flags and maps them to emojis.
+- If not, it falls back to the current branch/short SHA (still useful, but fewer states).
+
+Best practices:
+- Keep the capsule on during active work; it surfaces risk at a glance.
+- If you want faster prompts in very large repos, leave untracked detection off.
+- Use the Git theme for a minimal, work-safe look with the capsule always enabled.
+
 ## Seasonal (Aurora, Standard Pack)
 
 Design intent: calm, readable, long-session comfort with a subtle five-step gradient