Polish docs and repo hygiene

2026-01-25 00:14:21 +00:00
parent 2443820037
commit 4a7cdcc11f
6 changed files with 167 additions and 25 deletions
--- a/library.md
+++ b/library.md
@@ -0,0 +1,464 @@
+# Theme Library
+
+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
+(date -> time -> user -> host -> path).
+
+Layout: two-line powerline, host+path on line 1, status + emoji on line 2.
+
+Winter:
+
+![Winter](./images/themes/season-winter.png)
+
+Emoji:
+- Set: sunrise 🏔️ 🌨️ ❄️ 🌌; work 🎿 ⛷️ 🏂 🧊; coffee ☕; evening 🌆; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=59  Z2_BG=61  Z3_BG=63  Z4_BG=38  Z5_BG=37
+Z1_FG=255 Z2_FG=255
+PATH_FG=152
+FRAME=60
+```
+
+Spring:
+
+![Spring](./images/themes/season-spring.png)
+
+Emoji:
+- Set: sunrise 🌷 🌱 🐣 🌤; work 🌿 🪴 🐝 🌼; coffee ☕; evening 🌤; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=68  Z2_BG=70  Z3_BG=72  Z4_BG=121 Z5_BG=120
+Z1_FG=255 Z2_FG=22
+PATH_FG=28
+FRAME=65
+```
+
+Summer:
+
+![Summer](./images/themes/season-summer.png)
+
+Emoji:
+- Set: sunrise 🌞 🏖️ 🌅 🌤; work 🏄 🏖️ 🚤 🌴; coffee 🧃; evening 🌇; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=141 Z2_BG=142 Z3_BG=143 Z4_BG=214 Z5_BG=208
+Z1_FG=255 Z2_FG=0
+PATH_FG=0
+FRAME=130
+```
+
+Autumn:
+
+![Autumn](./images/themes/season-autumn.png)
+
+Emoji:
+- Set: sunrise 🍁 🍂 🌫️ 🌦️; work 🍂 🍄 🎃 🪵; coffee ☕; evening 🌆; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=93  Z2_BG=95  Z3_BG=97  Z4_BG=166 Z5_BG=136
+Z1_FG=255 Z2_FG=255
+PATH_FG=223
+FRAME=95
+```
+
+## Contest Pack (style_pack=contest)
+
+Design intent: high-contrast silhouettes, fast scanning, stage-ready presence.
+
+Layout: configurable order for the left segment, always ends with "@host - /path".
+
+Aurora (contest palette):
+
+![Aurora (contest)](./images/themes/aurora.png)
+
+Emoji:
+- Set: sunrise ⚡️ 🛰️ 🧬 🧠; work 🛠️ 💾 🧪 🧩; coffee ☕; evening 🎛️; night 🕶️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=24 Z2_BG=31
+Z1_FG=255 Z2_FG=255
+PATH_FG=51
+FRAME=23
+```
+
+Neon:
+
+![Neon](./images/themes/neon.png)
+
+Emoji:
+- Set: sunrise ⚡️ 🛰️ 🧬 🧠; work 🛠️ 💾 🧪 🧩; coffee ☕; evening 🎛️; night 🕶️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=201 Z1_FG=255
+Z2_BG=45  Z2_FG=16
+PATH_FG=16
+FRAME=199
+```
+
+Forge:
+
+![Forge](./images/themes/forge.png)
+
+Emoji:
+- Set: sunrise ⚡️ 🛰️ 🧬 🧠; work 🛠️ 💾 🧪 🧩; coffee ☕; evening 🎛️; night 🕶️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=94  Z1_FG=230
+Z2_BG=166 Z2_FG=231
+PATH_FG=224
+FRAME=130
+```
+
+Circuit:
+
+![Circuit](./images/themes/circuit.png)
+
+Emoji:
+- Set: sunrise ⚡️ 🛰️ 🧬 🧠; work 🛠️ 💾 🧪 🧩; coffee ☕; evening 🎛️; night 🕶️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+FG_MAIN=46
+FG_DIM=22
+PATH_FG=120
+```
+
+Mono:
+
+![Mono](./images/themes/mono.png)
+
+Emoji:
+- Set: sunrise ⚡️ 🛰️ 🧬 🧠; work 🛠️ 💾 🧪 🧩; coffee ☕; evening 🎛️; night 🕶️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+FG_MAIN=250
+FG_DIM=240
+```
+
+Git:
+
+![Git](./images/themes/git.png)
+
+Emoji:
+- Set: sunrise ⚡️ 🛰️ 🧬 🧠; work 🛠️ 💾 🧪 🧩; coffee ☕; evening 🎛️; night 🕶️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=61 Z1_FG=255
+Z2_BG=37 Z2_FG=255
+PATH_FG=194
+FRAME=60
+```
+
+Hawolex:
+
+![Hawolex](./images/themes/hawolex.png)
+
+Emoji:
+- Set: sunrise 💻 🚗 🔊 🎮; work 🎧 🕹️ 📟 🧩; coffee ☕; evening 🌆; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=54 Z1_FG=255
+Z2_BG=31 Z2_FG=255
+PATH_FG=230
+FRAME=24
+```
+
+HawolexV2 (gradient):
+
+![HawolexV2](./images/themes/hawolexv2.png)
+
+Emoji:
+- Set: sunrise ⚡️ 🛰️ 🧬 🧠; work 🛠️ 💾 🧪 🧩; coffee ☕; evening 🎛️; night 🕶️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=54 Z2_BG=55 Z3_BG=56 Z4_BG=31 Z5_BG=30
+Z_FG=255
+PATH_FG=230
+FRAME=24
+```
+
+
+## Holidays Pack (style_pack=holiday)
+
+Design intent: themed color + emoji without sacrificing readability.
+Layout uses contest order and ends with "@host - /path".
+
+Christmas:
+
+![Christmas](./images/themes/christmas.png)
+
+Emoji:
+- Set: sunrise 🎄 🎅 ❄️ ⛄; work 🎁 🧤 🧣 🦌; coffee ☕; evening 🌟; night 🕯️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=52 Z2_BG=28
+Z1_FG=255 Z2_FG=255
+PATH_FG=194
+FRAME=88
+```
+
+Easter:
+
+![Easter](./images/themes/easter.png)
+
+Emoji:
+- Set: sunrise 🐣 🥚 🌷 🌤; work 🐰 🌼 🧺 🍫; coffee ☕; evening 🌅; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=186 Z2_BG=150
+Z1_FG=16  Z2_FG=16
+PATH_FG=94
+FRAME=143
+```
+
+Halloween:
+
+![Halloween](./images/themes/halloween.png)
+
+Emoji:
+- Set: sunrise 🎃 🦇 🌕 🕸️; work 👻 💀 🕯️ 🧪; coffee ☕; evening 🌆; night 🕷️
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=53 Z2_BG=166
+Z1_FG=255 Z2_FG=16
+PATH_FG=16
+FRAME=89
+```
+
+Valentine:
+
+![Valentine](./images/themes/valentine.png)
+
+Emoji:
+- Set: sunrise 💖 🌹 💘 💕; work 💌 🍫 🕊️ 💗; coffee ☕; evening 🌆; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=198 Z2_BG=205
+Z1_FG=255 Z2_FG=255
+PATH_FG=224
+FRAME=162
+```
+
+Thanksgiving:
+
+![Thanksgiving](./images/themes/thanksgiving.png)
+
+Emoji:
+- Set: sunrise 🦃 🍁 🥧 🍂; work 🍽️ 🌾 🧺 🥖; coffee ☕; evening 🌆; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=94  Z2_BG=136
+Z1_FG=230 Z2_FG=231
+PATH_FG=223
+FRAME=130
+```
+
+NewYear:
+
+![NewYear](./images/themes/newyear.png)
+
+Emoji:
+- Set: sunrise 🎆 🥂 🎇 ✨; work 🗓️ ⏳ 🚀 ✨; coffee ☕; evening 🌆; night 🌙
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=17 Z2_BG=20
+Z1_FG=255 Z2_FG=255
+PATH_FG=229
+FRAME=19
+```
+
+## Custom Pack (style_pack=custom)
+
+Design intent: experimental, high-signal styles with bold contrast and distinct silhouettes.
+Custom styles include a context badge when relevant (ssh, ctr, git).
+
+Radar:
+
+![Radar](./images/themes/radar.png)
+
+Emoji:
+- Set: seasonal (Spring/Summer/Autumn/Winter sets, same as Seasonal section)
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+FRAME=22
+FG_MAIN=46
+FG_DIM=28
+PATH_FG=120
+```
+
+Synthwave:
+
+![Synthwave](./images/themes/synthwave.png)
+
+Emoji:
+- Set: seasonal (Spring/Summer/Autumn/Winter sets, same as Seasonal section)
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=198 Z1_FG=255
+Z2_BG=45  Z2_FG=16
+Z3_BG=208 Z3_FG=16
+FRAME=201
+```
+
+Noir:
+
+![Noir](./images/themes/noir.png)
+
+Emoji:
+- Set: seasonal (Spring/Summer/Autumn/Winter sets, same as Seasonal section)
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+FG_MAIN=250
+FG_DIM=242
+PATH_FG=160
+FRAME=236
+```
+
+Topo:
+
+![Topo](./images/themes/topo.png)
+
+Emoji:
+- Set: seasonal (Spring/Summer/Autumn/Winter sets, same as Seasonal section)
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+PATH_FG_LIST=109,110,111,110
+FRAME=24
+```
+
+Glitch:
+
+![Glitch](./images/themes/glitch.png)
+
+Emoji:
+- Set: seasonal (Spring/Summer/Autumn/Winter sets, same as Seasonal section)
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+FG_MAIN=118
+FG_DIM=60
+FRAME=129
+```
+
+ArcticFire:
+
+![ArcticFire](./images/themes/arcticfire.png)
+
+Emoji:
+- Set: seasonal (Spring/Summer/Autumn/Winter sets, same as Seasonal section)
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+Z1_BG=24 Z1_FG=255
+Z2_BG=31 Z2_FG=255
+Z3_BG=208 Z3_FG=16
+FRAME=25
+```
+
+AcidLime:
+
+![AcidLime](./images/themes/acidlime.png)
+
+Emoji:
+- Set: seasonal (Spring/Summer/Autumn/Winter sets, same as Seasonal section)
+- Fixed times: 🥪 11:00–11:29, 🍲 16:00–16:59
+- Interval: time slots (Sunrise 05:00–08:59, Coffee 09:00–10:59, Work 11:30–15:59, Evening 17:00–22:59, Night 23:00–04:59), daily rotation
+
+```
+FG_MAIN=46
+FG_DIM=40
+PATH_FG=118
+FRAME=46
+```
+
+## Configuration Options
+
+Core:
+```
+PS1_STYLE_PACK=standard|contest|holiday|custom
+PS1_STYLE=aurora|neon|forge|circuit|mono|git|hawolex|hawolexv2|radar|synthwave|noir|topo|glitch|arcticfire|acidlime
+PS1_SEASON_MODE=dynamic|static
+PS1_SEASON=winter|spring|summer|autumn
+PS1_CONTEST_LAYOUT=day-time-user|user-time|time-user|day-time
+PS1_HOLIDAY=christmas|easter|halloween|valentine|thanksgiving|newyear
+PS1_GIT=0|1
+```
+
+Overrides:
+```
+PS1_FORCE_NF=1        # force Nerd Font separators
+PS1_FORCE_ASCII=1     # force ASCII/Unicode separators
+DISABLE_GLOBAL_PS1=1  # disable prompt in current shell
+~/.config/ps1/disable # disable prompt per-user
+```