docs: harden getting started install flow

Author: codejunkie99

docs/getting-started.md

@@ -2,38 +2,51 @@
 
 ## 1. Install agentic-stack
 
-### macOS / Linux (recommended)
+### macOS / Linux with Homebrew (recommended)
 
 ```bash
 brew tap codejunkie99/agentic-stack https://github.com/codejunkie99/agentic-stack
 brew install agentic-stack
 ```
 
-### Windows (PowerShell)
+This installs the `agentic-stack` command.
 
-```powershell
+### Source checkout (no Homebrew)
+
+If you prefer not to use Homebrew, clone the repo and run `install.sh`
+against the project you want to wire:
+
+```bash
 git clone https://github.com/codejunkie99/agentic-stack.git
 cd agentic-stack
-.\install.ps1 claude-code C:\path\to\your-project
+./install.sh claude-code /path/to/your-project
 ```
 
-### Clone install (any platform)
+This path does not install a global `agentic-stack` command. Keep the clone
+around and run future management commands through `./install.sh`.
 
-If you prefer not to use Homebrew:
+### Windows (PowerShell)
 
-```bash
+```powershell
 git clone https://github.com/codejunkie99/agentic-stack.git
-cd agentic-stack && ./install.sh claude-code
+cd agentic-stack
+.\install.ps1 claude-code C:\path\to\your-project
 ```
 
 ## 2. Pick your harness
 
+If you installed with Homebrew, run the CLI from your project root:
+
 ```bash
 cd your-project
 agentic-stack claude-code
 # or: cursor | windsurf | opencode | openclaw | hermes | pi | codex | standalone-python | antigravity
 ```
 
+If you are using a source checkout, the install command above already picked
+the harness. To add another adapter later, run
+`./install.sh add <adapter> /path/to/your-project` from the clone.
+
 The onboarding wizard runs automatically, populating
 `.agent/memory/personal/PREFERENCES.md` and `.agent/memory/.features.json`.
 
@@ -62,7 +75,8 @@ failures with reflection, and (if you let it) proposing skill rewrites.
 
 ## Managing your project
 
-After the initial setup, use verb-style subcommands:
+After the initial setup, Homebrew users can run verb-style subcommands from
+the project root:
 
 ```bash
 agentic-stack dashboard           # TUI dashboard: health, verify, memory, team, skills
@@ -73,14 +87,35 @@ agentic-stack upgrade --yes       # apply latest harness/memory/tools + new skil
 agentic-stack sync-manifest       # rebuild .agent/skills/_manifest.jsonl from SKILL.md
 ```
 
-Adding or removing adapters:
+Source checkout users can run the same verbs through the clone:
+
+```bash
+./install.sh dashboard /path/to/your-project
+./install.sh status /path/to/your-project
+./install.sh doctor /path/to/your-project
+./install.sh upgrade /path/to/your-project --dry-run
+./install.sh upgrade /path/to/your-project --yes
+./install.sh sync-manifest /path/to/your-project
+```
+
+PowerShell users can run the same verbs through `.\install.ps1`.
+
+Adding or removing adapters with Homebrew:
 
 ```bash
 agentic-stack add cursor          # add a second adapter alongside Claude Code
 agentic-stack remove cursor       # confirm prompt + delete
 agentic-stack manage              # interactive TUI for add/remove/audit
 ```
 
+Source checkout equivalents:
+
+```bash
+./install.sh add cursor /path/to/your-project
+./install.sh remove cursor /path/to/your-project
+./install.sh manage /path/to/your-project
+```
+
 ## Optional: add a visual system with `DESIGN.md`
 
 If your project has UI, drop a Google Stitch-style `DESIGN.md` file in the
@@ -100,7 +135,16 @@ npx @google/design.md lint DESIGN.md
 brew update && brew upgrade agentic-stack
 cd your-project
 agentic-stack upgrade --dry-run   # preview changes
-agentic-stack upgrade --yes       # apply (safe — won't overwrite your memory or config)
+agentic-stack upgrade --yes       # apply; won't overwrite your memory or config
+```
+
+Source checkout users should update the clone first:
+
+```bash
+cd /path/to/agentic-stack
+git pull --ff-only
+./install.sh upgrade /path/to/your-project --dry-run
+./install.sh upgrade /path/to/your-project --yes
 ```
 
 The upgrade command refreshes skeleton-owned `.agent` infrastructure

onboard_ui.py

@@ -1,6 +1,11 @@
 """ANSI palette, block-char banner, and clack-style layout atoms (stdlib only)."""
 import sys, os, shutil
 
+try:
+    from harness_manager import __version__ as _AGENTIC_STACK_VERSION
+except Exception:
+    _AGENTIC_STACK_VERSION = "unknown"
+
 _WIN = sys.platform == "win32"
 if _WIN:
     import msvcrt
@@ -25,7 +30,7 @@ def _hex(h, bg=False):
 # 2-row pixel font spells "AGENTIC STACK"
 _L1 = "  ▄▀█ █▀▀ █▀▀ █▄░█ ▀█▀ █ █▀▀  █▀ ▀█▀ ▄▀█ █▀▀ █▄▀ "
 _L2 = "  █▀█ █▄█ ██▄ █░▀█ ░█░ █ █▄▄  ▄█ ░█░ █▀█ █▄▄ █░█ "
-_T  = "  your portable brain  ·  harness-agnostic AI memory  ·  v0.8.0"
+_T  = f"  your portable brain  ·  harness-agnostic AI memory  ·  v{_AGENTIC_STACK_VERSION}"
 
 def _cc(c):
     if c == "█": return f"{PURPLE}{B}{c}{R}"

test_onboard_ui.py

@@ -0,0 +1,7 @@
+from harness_manager import __version__
+import onboard_ui
+
+
+def test_onboarding_banner_uses_package_version():
+    assert f"v{__version__}" in onboard_ui._T
+    assert "v0.8.0" not in onboard_ui._T