docs: fun emoji UX plus light-theme contrast fix

Punch up every page with humor and emoji navigation, refresh the
premium theme, and hard-fix light-mode CTA/tab contrast so secondary
buttons stay readable on pale backgrounds.

Author: piotrlaczkowski

README.md

@@ -182,17 +182,17 @@ TUI: `/compact`, `/sessions`, `/stats`, `/permission`, `/agents`, `/stop`, `/res
 
 ## 📚 Docs
 
-**Premium site (MkDocs Material → GitHub Pages):**
-[unicolab.github.io/smlcode](https://unicolab.github.io/smlcode/)
+**Premium + playful site (MkDocs Material → GitHub Pages):**
+☀️ [unicolab.github.io/smlcode](https://unicolab.github.io/smlcode/)
 
 | Section | Pages |
 |---------|--------|
-| Getting started | Install · Quick start · Concepts · Providers |
-| Handbook | Guide · TUI · Skills · Studio · Agents · Recipes |
-| Reference | CLI · Config · Testing · FAQ |
-| Internals | Architecture · Contributing |
+| 🚀 Getting started | 📦 Install · ⏱️ Quick start · 🧠 Concepts · 🔌 Providers |
+| 📘 Handbook | 🧭 Guide · 🖥️ TUI · 🦋 Skills · 🎨 Studio · 🧩 Agents · 🧪 Recipes |
+| 📚 Reference | ⌨️ CLI · ⚙️ Config · ✅ Testing · ❓ FAQ |
+| 🔧 Internals | 🏗️ Architecture · 🤝 Contributing |
 
-Local preview: `make docs-serve` → http://127.0.0.1:8000
+Local preview: `make docs-serve` → http://127.0.0.1:8000 — bring snacks. 🍿
 
 ---
 

docs/agents.md

@@ -1,30 +1,35 @@
 # 🧩 Agents
 
-Fourteen specialists. Scoped packs. No “hold the monorepo in your head” cosplay.
+Fourteen specialists. Scoped packs. No “hold the monorepo in your head” cosplay. 🎭
 
-!!! tip "Mix brains"
-    Cheap local explorer + sharper cloud reviewer in one run — [Providers](providers.md).
+<div class="slm-banner" markdown>
+<span class="slm-banner__emoji">🧬</span>
+<p class="slm-banner__text" markdown>
+<strong>Mix brains:</strong> cheap local explorer + sharper cloud reviewer in one run —
+see <a href="providers.md">Providers</a>. Budget diplomacy is a feature.
+</p>
+</div>
 
 ---
 
-## Roster
+## Roster 📋
 
 | ID | Tools | Output | When |
 |----|-------|--------|------|
-| `coordinator` | — | JSON actions | Pre-exec + each wave |
+| `coordinator` | — | JSON actions | Pre-exec + each wave 🧭 |
 | `orchestrator` | — | decisions | Reserved |
-| `context` | — | CONTEXT body | Run start |
-| `explorer` | ✅ | file map | Deep explore |
-| `docs` | ✅ | docs map | Docs/API queries |
-| `architect` | — | design JSON | Large/refactor |
-| `planner` | — | plan JSON | Always |
-| `splitter` | — | tasks JSON | Always |
-| `worker` | ✅ | status | Execute |
-| `deep` | ✅ | status | Multi-step |
-| `reviewer` | — | approve JSON | Critic |
-| `corrector` | ✅ | status | On reject |
-| `tester` | ✅ | passed | End validation |
-| `memory` | — | bullets | Learn |
+| `context` | — | CONTEXT body | Run start 📝 |
+| `explorer` | ✅ | file map | Deep explore 🔎 |
+| `docs` | ✅ | docs map | Docs/API queries 📚 |
+| `architect` | — | design JSON | Large/refactor 🏛️ |
+| `planner` | — | plan JSON | Always 📋 |
+| `splitter` | — | tasks JSON | Always ✂️ |
+| `worker` | ✅ | status | Execute 🛠️ |
+| `deep` | ✅ | status | Multi-step 🧪 |
+| `reviewer` | — | approve JSON | Critic 🔍 |
+| `corrector` | ✅ | status | On reject 🔧 |
+| `tester` | ✅ | passed | End validation ✅ |
+| `memory` | — | bullets | Learn 💾 |
 
 ```bash
 curl -s localhost:7420/api/agents | jq '.[].id'
@@ -33,7 +38,7 @@ curl -s localhost:7420/api/agents | jq '.[].id'
 
 ---
 
-## Custom agents
+## Custom agents ✨
 
 `.slmcode/agents/<id>.yaml` or `~/.slmcode/agents/`.
 
@@ -49,7 +54,7 @@ Different endpoints → unique backend keys (no accidental shared gateway).
 
 ---
 
-## Coordinator actions
+## Coordinator actions 🧭
 
 ```json
 {
@@ -64,9 +69,11 @@ Different endpoints → unique backend keys (no accidental shared gateway).
 }
 ```
 
+Air-traffic control, not pilot. Let workers fly the plane.
+
 ---
 
-## Delegating
+## Delegating 📬
 
 ```bash
 slmcode task add "Deep refactor auth" --role deep --column ready_to_dev
@@ -75,7 +82,7 @@ slmcode task delegate T1 docs
 
 ---
 
-## Project instructions
+## Project instructions 📜
 
 Auto-loaded from:
 
@@ -84,14 +91,14 @@ Auto-loaded from:
 - `.cursorrules`
 - `.slmcode/PROJECT.md`
 
-!!! example "Tiny AGENTS.md"
+!!! example "✨ Tiny AGENTS.md"
     ```markdown
     # Agents
     - Tiny, reviewable diffs
     - No drive-by refactors
     - Match existing style
     ```
 
-→ [Skills](skills.md) · [Concepts](concepts.md)
+→ [🦋 Skills](skills.md) · [🧠 Concepts](concepts.md)
 
-Made with ♥ by [UnicoLab](https://unicolab.ai)
+☀️ Made with ♥ by [UnicoLab](https://unicolab.ai)

docs/architecture.md

@@ -1,23 +1,31 @@
 # 🏗️ Architecture
 
-How SLMCode stays sharp when the model is small, tired, or both.
+How SLMCode stays sharp when the model is small, tired, or both. 😴➡️😎
+
+<div class="slm-banner" markdown>
+<span class="slm-banner__emoji">🦃</span>
+<p class="slm-banner__text" markdown>
+<strong>Design thesis:</strong> routing in Go. Tiny packs per specialist. Disk evidence over vibes.
+If you stuff the whole repo into context, don’t be surprised when the model naps.
+</p>
+</div>
 
 ---
 
-## Design thesis
+## Design thesis 🧠
 
 30B-class SLMs fail when asked to “be a frontier agent” in one free-form loop.
 
 **Routing in Go. Tiny packs per specialist. Disk evidence over vibes.**
 
-!!! quote "Turkey rule"
+!!! quote "🦃 Turkey rule"
     If you stuff the whole repo into context, don't be surprised when the model naps.
 
-→ Narrative version: [Concepts](concepts.md)
+→ Narrative version: [🧠 Concepts](concepts.md)
 
 ---
 
-## Package map
+## Package map 📦
 
 ```text
 cmd/slmcode          CLI + embedded Studio (go:embed ui/)
@@ -46,28 +54,29 @@ pkg/retrieval        Embeddings / lexical ranking
 
 ---
 
-## Live streaming
+## Live streaming 📡
 
 `stream.Event` fields: `phase`, `kind`, `agent`, `task_id`, `scope`, `output`.
 Consumers: CLI, Studio SSE (`/api/events`), `/api/runs/latest`.
 
 ---
 
-## Explore reuse · critic · flywheel
+## Explore reuse · critic · flywheel 🔁
 
-- **Reuse** when CONTEXT/MEMORY are rich (override with `SLMCODE_FORCE_EXPLORE=1`)
-- **Critic**: worker → reviewer → corrector loop; disk evidence preferred
-- **Flywheel**: MEMORY / CONTEXT / SKILLS / sessions after each run
+- **Reuse** when CONTEXT/MEMORY are rich (override with `SLMCODE_FORCE_EXPLORE=1`) ♻️
+- **Critic**: worker → reviewer → corrector loop; disk evidence preferred 🔍
+- **Flywheel**: MEMORY / CONTEXT / SKILLS / sessions after each run 🦋
 
 ---
 
-## Parallelism
+## Parallelism ⚡
 
 `SubAgentExecutor` runs ready tasks up to `max_parallel`. Soft-skip blocked deps so one stuck locate can't freeze the board.
+One blocked task should not become a board-wide existential crisis.
 
 ---
 
-## Embed
+## Embed 🧩
 
 ```go
 import "github.com/UnicoLab/slmcode/pkg/harness"
@@ -79,6 +88,6 @@ res, err := h.Run(ctx, "refactor pkg/auth")
 
 Dependency: `github.com/piotrlaczkowski/GoLangGraph` (optional local replace for hacking).
 
-→ [Contributing](contributing.md)
+→ [🤝 Contributing](contributing.md)
 
-Made with ♥ by [UnicoLab](https://unicolab.ai)
+☀️ Made with ♥ by [UnicoLab](https://unicolab.ai)

docs/cli.md

@@ -1,6 +1,14 @@
 # ⌨️ CLI reference
 
-Binary name: **`slmcode`** (docs sometimes say *smlcode* — same project).
+Binary name: **`slmcode`** (docs sometimes say *smlcode* — same project, same vibes). 💚
+
+<div class="slm-banner" markdown>
+<span class="slm-banner__emoji">🛠️</span>
+<p class="slm-banner__text" markdown>
+<strong>Power-user tip:</strong> every command has <code>--help</code>.
+When in doubt, be loud with <code>-v</code> and green with <code>doctor</code>.
+</p>
+</div>
 
 ```bash
 slmcode --help
@@ -9,7 +17,7 @@ slmcode <command> --help
 
 ---
 
-## Global flags
+## Global flags 🌐
 
 | Flag | Env / notes |
 |------|-------------|
@@ -22,59 +30,59 @@ slmcode <command> --help
 | `--parallel` | Max parallel workers |
 | `--retries` | Review/correct retries |
 | `--think-passes` | Multipass think loops |
-| `--dry-run` | Don't write code files |
-| `-v` / `--verbose` | Loud agent logs |
+| `--dry-run` | Don't write code files 🎭 |
+| `-v` / `--verbose` | Loud agent logs 📢 |
 | `--no-banner` | Hide ASCII banner on help |
 
 ---
 
-## Commands
+## Commands 📚
 
-### Core loop
+### Core loop 🔁
 
 | Command | Purpose |
 |---------|---------|
-| `slmcode` / `tui` | Premium interactive TUI (**default**) |
-| `run` | Full pipeline or single specialist |
-| `chat` | Classic REPL |
-| `studio` | GUI + HTTP/SSE (`--listen host:port`) |
-| `doctor` | Provider/model/workspace health |
-| `init` | Create `.slmcode/` scaffolding |
-| `update` | Refresh binary (release) or rebuild from source |
+| `slmcode` / `tui` | Premium interactive TUI (**default**) 🖥️ |
+| `run` | Full pipeline or single specialist 🚀 |
+| `chat` | Classic REPL 💬 |
+| `studio` | GUI + HTTP/SSE (`--listen host:port`) 🎨 |
+| `doctor` | Provider/model/workspace health 🩺 |
+| `init` | Create `.slmcode/` scaffolding 🌱 |
+| `update` | Refresh binary (release) or rebuild from source ⬆️ |
 | `version` | Print version metadata |
 
-### Board & tasks
+### Board & tasks 📋
 
 | Command | Purpose |
 |---------|---------|
 | `board` | Show kanban |
-| `watch` | Live-refreshing kanban |
+| `watch` | Live-refreshing kanban 👀 |
 | `task` | add / show / edit / move / delegate / checklist / promote |
 | `status` | Query + plan head + board counts |
 | `plan` | Show `PLAN.md` |
 
-### Memory & skills
+### Memory & skills 💾
 
 | Command | Purpose |
 |---------|---------|
 | `context` | Show / edit `CONTEXT.md` |
 | `docs` | List / show / edit markdown memory |
-| `skills` | List / show / new / edit |
-| `session` | list / show / resume |
+| `skills` | List / show / new / edit 🦋 |
+| `session` | list / show / resume 🛟 |
 
-### Git helpers & safety
+### Git helpers & safety 🛡️
 
 | Command | Purpose |
 |---------|---------|
 | `diff` | Working tree diff |
 | `commit` | `git add -A && commit` helper |
 | `apply` | Apply `.slmcode/pending/` (review mode) |
-| `config` | Show / set harness config |
+| `config` | Show / set harness config ⚙️ |
 | `completion` | Shell completion scripts |
 
 ---
 
-## `run` deep dive
+## `run` deep dive 🚀
 
 ```bash
 slmcode run -v "add JWT auth"
@@ -97,7 +105,7 @@ Query sugar: `@skill:name`, `@file:path`, `@folder:path` (when supported by inst
 
 ---
 
-## `config`
+## `config` ⚙️
 
 ```bash
 slmcode config                 # show
@@ -106,22 +114,22 @@ slmcode config set model qwen2.5-coder:14b
 slmcode config set permission review
 ```
 
-Full field list → [Config reference](config.md).
+Full field list → [⚙️ Config reference](config.md).
 
 ---
 
-## `doctor` reads as
+## `doctor` reads as 🩺
 
-- Active provider / model / endpoint  
-- Reachability  
-- Embedding mode (`openai` / `local` / `lexical`)  
-- Workspace / board / skills sanity  
+- Active provider / model / endpoint
+- Reachability
+- Embedding mode (`openai` / `local` / `lexical`)
+- Workspace / board / skills sanity
 
-Green → ship. Red → [FAQ](faq.md).
+Green → ship. 💚 Red → [❓ FAQ](faq.md).
 
 ---
 
-## Completions
+## Completions 🐚
 
 ```bash
 slmcode completion zsh > "$(brew --prefix)/share/zsh/site-functions/_slmcode"
@@ -133,6 +141,9 @@ Installers may place these automatically on system installs.
 
 ---
 
-## Exit philosophy
+## Exit philosophy 🚪
+
+SLMCode prefers **visible failure** over silent “done” theater.
+Check the board, the diff, and `doctor` when something smells off. 👃
 
-SLMCode prefers **visible failure** over silent “done” theater. Check the board, the diff, and `doctor` when something smells off.
+☀️ Made with ♥ by [UnicoLab](https://unicolab.ai)