Polish docs and repo hygiene

.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[*.sh]
+indent_style = space
+indent_size = 2
+
+[*.yml]
+indent_style = space
+indent_size = 2

.github/workflows/shellcheck.yml

@@ -0,0 +1,20 @@
+name: ShellCheck
+
+on:
+  push:
+    paths:
+      - "dotfiles/**/*.sh"
+      - ".github/workflows/shellcheck.yml"
+  pull_request:
+    paths:
+      - "dotfiles/**/*.sh"
+      - ".github/workflows/shellcheck.yml"
+
+jobs:
+  shellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ludeeus/action-shellcheck@v2
+        with:
+          scandir: dotfiles

CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Thanks for helping improve ps1-craft. Keep changes small, readable, and fast.
+
+## Style rules
+
+- Keep the prompt hot path fast (no external commands unless feature-gated).
+- Use `printf` over `echo` for formatting.
+- Quote variables and paths; avoid word-splitting.
+- Maintain bash 3.2 compatibility for macOS.
+
+## Add a new theme or palette
+
+1) Update `dotfiles/ps1/ps1.sh` with the new colors/icons.
+2) Add a screenshot under `images/themes/`.
+3) Document it in `library.md` and `README.md`.
+
+## Testing
+
+- Run the installer script you changed.
+- Open a new shell and verify the prompt renders.
+- Run ShellCheck on `dotfiles/**/*.sh`.

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: ✨
+```text
-- Dirty: 🔨
+Clean      ✨
-- Staged: 📌
+Dirty      🔨
-- Untracked: 🧷
+Staged     📌
-- Stashed: 📦
+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
+├── .editorconfig
-├── contest-styles.json
+├── .github/
-├── images/
+│   └── workflows/
-│   ├── bash-pallete.png
+│       └── shellcheck.yml
-│   └── contest.png
+├── .gitignore
-│   └── themes/
+├── 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
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for style rules and how to add a new theme/palette
-- Make your changes
-- Open a merge request
-- Please keep consistent colors and styles
 
 ---
 

UNINSTALL.md

@@ -0,0 +1,35 @@
+# Uninstall
+
+## Linux / WSL (global)
+
+Remove installed files:
+
+```bash
+sudo rm -f /etc/profile.d/ps1.sh /etc/profile.d/banner.sh
+sudo rm -f /etc/ps1-season /etc/ps1-style /etc/ps1-punchline
+```
+
+Remove the managed block from `/etc/bash.bashrc`:
+
+```bash
+sudo sed -i '/# >>> dotfiles (managed) >>>/,/# <<< dotfiles (managed) <<</d' /etc/bash.bashrc
+```
+
+Open a new shell to confirm the prompt is gone.
+
+## macOS (per-user)
+
+Remove installed files:
+
+```bash
+rm -f ~/.config/ps1/ps1.sh ~/.config/ps1/season ~/.config/ps1/style
+```
+
+Remove the managed block from your shell configs:
+
+```bash
+sed -i '' '/# >>> user ps1 (managed) >>>/,/# <<< user ps1 (managed) <<</d' ~/.bashrc
+sed -i '' '/# >>> user ps1 (managed) >>>/,/# <<< user ps1 (managed) <<</d' ~/.bash_profile
+```
+
+Open a new shell or run `source ~/.bashrc`.