Polish docs and repo hygiene

README.md

@@ -1,19 +1,31 @@
-# Bashrc Dotfiles — Global & Portable Bash Prompt
+# ps1-craft — Global & Portable Bash Prompt
 
 Elegant, portable, and easy-to-install Bash prompt with seasonal palettes, time-aware emoji, and clean powerline structure.
 
+## ⚡ 10-Second Demo
+
+```text
+[Mon 14:32 steffen] ▶
+@host ~/ps1-craft ⟦main⟧ ✨
+```
+
+Preview (Aurora seasonal):
+
+![Aurora (seasonal)](images/themes/season-winter.png)
+
 ---
 
 ## ⚡ Quick Look
 
-- Theme gallery + full specs: [Theme Library](libary.md)
+- Theme gallery + full specs: [Theme Library](library.md)
+- Install scope + rollback: [UNINSTALL.md](UNINSTALL.md)
 - Packs: Seasonal (auto), Contest, Holidays, Custom, Git
 - Layout order option: day-time-user, user-time, time-user, day-time
 - Optional git capsule across themes
 
 ## ✅ Requirements (Nerd Fonts)
 
-This prompt relies on Nerd Font glyphs for the rounded separators.
+This prompt relies on Nerd Fonts glyphs for the rounded separators.
 
 ```bash
 bash dotfiles/install/install-nerdfont.sh
@@ -21,13 +33,29 @@ bash dotfiles/install/install-nerdfont.sh
 
 After install:
 
-- Set your terminal font to JetBrainsMono Nerd Font (or any Nerd Font)
+- Set your terminal font to JetBrainsMono Nerd Font (or any Nerd Fonts family)
 - Manual download: https://www.nerdfonts.com/font-downloads
 
 If you use a non‑Nerd font, the prompt falls back to ASCII/Unicode.
 
 ---
 
+## ⚠️ Safety / Scope (global install)
+
+Linux/WSL installs are global and modify system files:
+
+- Writes `/etc/profile.d/ps1.sh` and `/etc/profile.d/banner.sh`
+- Writes `/etc/ps1-season`, `/etc/ps1-style`, and `/etc/ps1-punchline`
+- Adds a managed source block in `/etc/bash.bashrc`
+
+Rollback and uninstall steps live in [UNINSTALL.md](UNINSTALL.md). You can also disable per user:
+
+- `export DISABLE_GLOBAL_PS1=1`
+- `export DISABLE_GLOBAL_BANNER=1`
+- `touch ~/.config/ps1/disable` (PS1) or `touch ~/.config/ps1/disable-banner` (banner)
+
+---
+
 ## 🚀 Install
 
 ### 🐧 Linux / WSL (global, all users)
@@ -35,13 +63,13 @@ If you use a non‑Nerd font, the prompt falls back to ASCII/Unicode.
 1) Clone the repo:
 
 ```bash
-git clone <repo-url>
+git clone git@github.com:Hawolex/ps1-craft.git
 ```
 
 2) Enter the folder:
 
 ```bash
-cd Bashrc
+cd ps1-craft
 ```
 
 3) Run the global installer (auto-installs deps + prompts for punchline):
@@ -57,13 +85,13 @@ sudo bash dotfiles/install/install-linux-global.sh
 1) Clone the repo:
 
 ```bash
-git clone <repo-url>
+git clone git@github.com:Hawolex/ps1-craft.git
 ```
 
 2) Enter the folder:
 
 ```bash
-cd Bashrc
+cd ps1-craft
 ```
 
 3) Run the user installer:
@@ -194,6 +222,12 @@ echo "Your punchline" | sudo tee /etc/ps1-punchline >/dev/null
 
 ## 🎛️ Themes & Style Packs
 
+Terminology:
+
+- Theme = palette + emoji set
+- Style = layout + separators
+- Pack = a curated set of styles/themes
+
 ### 🏁 Contest Pack
 
 The contest pack is a bold, DEFCON-ready set of five styles (Aurora, Neon, Forge, Circuit, Mono) with optional layout order. It always starts on a new line and ends with `@host - /path`.
@@ -225,11 +259,13 @@ Custom styles add a small context badge when relevant (`ssh`, `ctr`, `git`).
 
 The Git theme adds a repo-aware capsule on line 2 that only appears inside a Git repo. The branch name is wrapped as `⟦branch⟧`, and status emojis reflect state:
 
-- Clean: ✨
-- Dirty: 🔨
-- Staged: 📌
-- Untracked: 🧷
-- Stashed: 📦
+```text
+Clean      ✨
+Dirty      🔨
+Staged     📌
+Untracked  🧷
+Stashed    📦
+```
 
 It uses the same two-block layout as Aurora, but focuses on signal and minimal noise for fast scanning. Use it when you want repo status on every command without a full VCS prompt.
 
@@ -294,12 +330,16 @@ Meaning:
 
 ```text
 .
-├── .context.json
-├── contest-styles.json
-├── images/
-│   ├── bash-pallete.png
-│   └── contest.png
-│   └── themes/
+├── .editorconfig
+├── .github/
+│   └── workflows/
+│       └── shellcheck.yml
+├── .gitignore
+├── CONTRIBUTING.md
+├── LICENSE
+├── README.md
+├── UNINSTALL.md
+├── library.md
 ├── dotfiles/
 │   ├── banner/
 │   │   └── banner.sh
@@ -310,7 +350,9 @@ Meaning:
 │       ├── install-linux-global.sh
 │       ├── install-macos-user.sh
 │       └── install-nerdfont.sh
-└── README.md
+└── images/
+    ├── bash-pallete.png
+    └── themes/
 ```
 
 <details>
@@ -318,7 +360,7 @@ Meaning:
 
 Sometimes autodetection doesn’t work (e.g., on macOS without fontconfig):
 
-Force Nerd Font glyphs:
+Force Nerd Fonts glyphs:
 
 ```bash
 export PS1_FORCE_NF=1
@@ -335,6 +377,14 @@ Add these to your `~/.bashrc` or `~/.bash_profile`.
 
 ---
 
+## ⚙️ Performance Notes
+
+- Git capsule work only runs inside a Git repo and only when enabled
+- Large repos can slow status checks; disable with `PS1_GIT=0` or avoid the Git theme
+- Prompt logic avoids external commands unless a feature is enabled (banner, git capsule)
+
+---
+
 <details>
 <summary><strong>Disable prompt (per user)</strong></summary>
 
@@ -445,10 +495,7 @@ Palette reference:
 
 Want to help improve this project?
 
-- Fork the repository
-- Make your changes
-- Open a merge request
-- Please keep consistent colors and styles
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for style rules and how to add a new theme/palette
 
 ---