Clarify git capsule state meanings

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 (plain language):
+- Clean repo: ✨ no local changes; your files match the last commit
+- Dirty working tree: 🔨 you edited tracked files but haven’t staged them yet
+- Staged changes: 📌 changes are staged and ready to commit
+- Untracked files: 🧷 new files git hasn’t started tracking
+- Stashed changes: 📦 work saved with `git stash` (not in your working tree)
+
+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